Log inSign up
lightweight
lightweightglimpse2-runbook
Public
Like
glimpse2-runbook
Val Town is a collaborative website to build and scale JavaScript apps.
Deploy APIs, crons, & store data – all from the browser, and deployed in milliseconds.
Sign up now
Code
/
_townie
/
00-setup.md
Search
8/5/2025
Viewing readonly version of main branch: v20
View latest version
00-setup.md

SETUP

Use this file to guide you through the Glimpse setup process.

These instructions are for you. They will guide you through manual steps you should take to get Glimpse going, and are mostly related to setting up environment variables, branching, and merging.

The prompts in code blocks are for Townie, the super helpful AI bot that writes code for you on val.town. Townie will handle scaffolding the Val, user authentication, and webhook authentication.

Once those bits are complete, you can add features til your heart's content.

1-SCAFFOLD.md

  1. Use vt to clone this Val to your computer
  2. Add vars.env at the root of the Val
  3. Add vars.env to the .vtignore file, so that your environment variables aren't uploaded to val.town
  4. Add all of the environment variables that this Val will use to vars.env; see "Environment variables required", below
  5. Go to the Environment Variables section of your Val on val.town and import the vars.env file; once there, all of the environment variables are available to the Val and Townie
  6. Go to Townie, select this Val, and prompt Townie with this line:
Scaffold this Val with what you see in `/TOWNIE/1-SCAFFOLD.md`

Environment variables (required)

  • NOTION_API_KEY - Your Notion integration API key
  • NOTION_WEBHOOK_SECRET - Matches the X-API-KEY custom header coming from Notion webhooks to /tasks/* endpoint(s)
  • GLANCE_DEMOS_DB_ID - Your Notion database ID for demos, which are personalized to prospects and have unique URLs
  • GLANCE_CONTENT_DB_ID - Your Notion database ID for demo page content, which are compiled into demos
  • GLANCE_INTERACTIONS_DB_ID - Your Notion database ID for pageview metrics and the like

If you don't have a vars.env file for this, or you don't have values for these variables, contact your administrator.

2-AUTH.md

  1. In val.town, create a branch in your Val called auth
  2. Go to Townie, select this Val, and then select the auth branch
  3. Prompt Townie with this line:
Add auth to this Val with what you see in `/TOWNIE/2-AUTH.md`

Work with Townie to make sure what appears at / is correct. Once it's correct, move on to the next step.

3-WEBHOOKS.md

  1. In val.town, merge auth into main
  2. Delete the auth branch
  3. Create a branch in your Val called webhooks
  4. Go to Townie, select this Val, and then select the webhooks branch
  5. Prompt Townie with this line:
Add webhook auth to this Val with what you see in `/TOWNIE/3-WEBHOOKS.md`

Test the webhook auth and test webhook

  1. In Notion, add a button to a database row in the Glimpse Demos database
  2. Edit the automation on that button to be a webhook that hits https://<branch subdomain url>/tasks/notion-webhook
  3. Add the custom header for webhook auth: Key: X-API-KEY and Value: <custom header value>. (Find the value in the NOTION_WEBHOOK_SECRET key in vars.env)
  4. Save the button automation
  5. Click the button in Notion
  6. Go to the Logs in your Val and see the latest log statement, which should outline success or failure of your webhook and webhook auth

4-GLIMPSE.md

  1. Merge the webhooks branch into main
  2. Delete the webhooks branch
  3. Create a branch called glimpse
  4. Go to Townie, select this Val, and then select the glimpse branch
  5. Prompt Townie with this line:
Add an endpoint at `/views/glimpse/:id` by following the instructions in `/TOWNIE/4-GLIMPSE.md`

For now we will just have to trust that this new endpoint works. We will verify that's true in the next few steps.

5-DUPLICATE-ROUTE.md

  1. Prompt Townie with this line:
Add a route for `/glimpse/:id` by following the instructions in `/TOWNIE/5-DUPLICATE-ROUTE.md`.

6-URL.md

  1. Merge the glimpse branch into main
  2. Delete the glimpse branch
  3. Create a new branch called url
Follow the instructions in `/TOWNIE/6-URL.md` to add an endpoint at `/tasks/url`.

Test the /tasks/url endpoint

  1. In Notion, add a button to a database row in the Glimpse Demos database called "Staging: set URL"
  2. Edit the automation on that button to be a webhook that hits https://<branch subdomain url>/tasks/url
  3. Add the custom header for webhook auth: Key: X-API-KEY and Value: <custom header value>. (Find the value in the NOTION_WEBHOOK_SECRET key in vars.env)
  4. Save the button automation
  5. Click the button in Notion
  6. You should see the URL property update with a URL to a Glimpse endpoint on val.town
  7. If it fails, clues as to why are in the logs
  8. Go to the Logs in your Val and see the latest log statement
  9. If there's an error captured there, explain that to Townie

7-RELATED.md

  1. Merge url into main
  2. Delete the url branch
  3. Create a new branch called "related"
Add related pages to the /glimpse/:id endpoint by following the instructions in `/TOWNIE/7-RELATED.md`

TODO: have Townie's success message at the end tell the user to update Notion automation with the URL on the main branch

  1. In Notion, click the URL in the URL property; it should not work. That URL is from a previous branch that we deleted.
  2. Go to main.tsx and get the URL for this branch
  3. Edit the automation on the "Set URL" button with that URL; make sure it incudes the /tasks/url endpoint
  4. Save the button automation
  5. Click the button in Notion
  6. You should see the URL property update with a URL to a Glimpse endpoint on val.town
  7. Click the new URL
  8. Authenticate
  9. CTRL+F glimpseContent -- that's the object that holds the related content you see in Notion

8-CACHE.md

  1. Merge related into main
  2. Delete the related branch
  3. Create a new branch called cache
Use the instructions in /TOWNIE/8-CACHE.md to implement a cache for Glimpse demos at the `/glimpse/:id` endpoint
  1. merge cache into main
  2. set cron interval to 1 minute

After merging into main:

CRITICAL: Go to the Val Town web UI and set the cron schedule for /backend/crons/cache_glimpse_data.ts to run every minute

9-REACT.md

Now that we have a responsive endpoint, we can iterate quickly on the front end without waiting for notion to respond and the JSON to render.

  1. Delete the cache branch
  2. Create a new branch called react
Use the instructions in `/TOWNIE/9-REACT.md` to implement a React bootstrap for the `/glimpse/:id` endpoint
  1. test /glimpse/:id endpoint in the react branch
  2. if it looks good, merge react into main
  3. delete react branch

10-HTML.md

  1. Create a new branch called html
  2. Go to townie and select the html branch
  3. Enter this into townie:

TODO: make sure that the html instructions are clear about persisting the page layout with header including auth, sidenav, main content and footer.

use the instructions in `/TOWNIE/10-HTML.md` to format the Notion data as HTML. Use this endpoint for testing: `/glimpse/20089f51-c349-803b-a940-edd14b011876
  1. test /glimpse/:id endpoint in the html branch
  2. if it looks good, merge html into main
  3. delete html branch

11-PDF-EMBEDS.md

  1. Create a new branch called pdf-embeds
  2. Go to Townie and select the pdf-embeds branch
  3. Enter this into Townie:
follow the instructions in /TOWNIE/PDF-EMBEDS.md to implement rendering for certain embed blocks

The link is rendered as a button but it 404s. We need to implement the /glimpse/:id/pdf route.

12-PDF-ROUTE.md

  1. Create a new branch called pdf-route
  2. Go to Townie and select the pdf-route branch
  3. Enter this into Townie:
follow the instructions in /TOWNIE/PDF-ROUTE.md to implement rendering for certain embed blocks