Set up Vercel

This walkthrough deploys Tapestry’s frontends on Vercel — your docs site and the Observatory console. In self-host you run this for your own deployment. See Platform dependencies for what’s needed.

Estimated time: 10–15 minutes for a first deploy. Subsequent deploys are automatic on git push.

What you’ll deploy

Frontend	Source	What it serves
Docs site (this site)	apps/docs-site/	Astro Starlight content + the static /llms.txt + per-page /raw/<slug>.md artifacts produced by scripts/generate-static-docs.mjs (prebuild step)
Observatory cockpit	apps/docs-site/src/pages/observatory.astro	Interactive variable-overlay view; SSR (opt-out from static prerender at observatory.astro:1 — export const prerender = false)
Web dashboard (future, not yet deployed)	apps/web-dashboard/ (planned)	Standalone dashboard surface alongside the cockpit

Both the docs site and the cockpit ship from the same Astro project. One Vercel project deploys both.

Prerequisites

• A Vercel account (free tier is enough to start; check Vercel’s pricing when traffic grows)
• Node.js 18+ on your machine
• A GitHub account connected to the tapestry repo

Step 1 — Install the Vercel CLI

From the Vercel getting-started docs:

npm i -g vercel
vercel login

vercel login opens a browser for authentication. After it completes, the CLI can deploy + manage projects from your terminal.

Step 2 — Deploy from the local repo (first deploy)

cd apps/docs-site
vercel

Per the Vercel CLI docs, vercel with no args walks an interactive setup:

1. Asks which Vercel team or scope to deploy under.
2. Asks whether to link to an existing project or create a new one (choose new).
3. Detects the framework (Astro) and the build settings.
4. Builds and deploys to a preview URL like https://tapestry-<hash>.vercel.app.

The preview URL goes live in 1–3 minutes (first build is slowest; subsequent builds cache node_modules).

When you’re ready to deploy to a canonical URL:

vercel --prod

Per Vercel’s deploy docs, --prod promotes the latest build to the production domain.

Step 3 — Confirm the Astro build picks up our prebuild step

The dropdown’s static artifacts are generated by scripts/generate-static-docs.mjs before Astro builds. The wiring is in package.json:

{
  "scripts": {
    "build": "node scripts/generate-static-docs.mjs && astro build"
  }
}

Vercel auto-runs npm run build for Astro projects, so the prebuild fires automatically. Verify by checking the Vercel build log after a deploy — you should see:

[generate-static-docs] wrote public/llms.txt + public/raw/<slug>.md for 37 pages

before the Astro build kicks in.

Step 4 — Connect the GitHub repo for auto-deploys

Manual vercel from your terminal is for one-off deploys. For continuous deploys on git push, link the GitHub repo:

1. In the Vercel dashboard, open the project.
2. Go to Settings → Git → Connect Git Repository.
3. Select Lizo-RoadTown/tapestry and the branch (typically main).

Per Vercel for GitHub docs, every push to the connected branch triggers a deploy. PRs get preview URLs in their checks tab.

Step 5 — Set env vars (if you self-host the Memory MCP)

The docs site is mostly static. The Observatory cockpit, however, reads from the Memory MCP + Registry. If you’re self-hosting (not consuming the upstream tapestry-khaki deployment), set:

MEMORY_BASE_URL=https://your-memory-host.example.com
REGISTRY_BASE_URL=https://your-registry-host.example.com

Per Vercel’s environment variables docs:

1. Settings → Environment Variables → Add New.
2. Scope to Production (and optionally Preview / Development).
3. Redeploy to pick up changes — env vars are bound at build time for static pages, request time for SSR pages.

For the upstream tapestry-khaki.vercel.app deployment, these vars are already set against the upstream memory-mcp Render service.

Step 6 — Set the custom domain (optional)

The default <project>.vercel.app domain is fine for early use. To set a custom domain:

1. Settings → Domains → Add.
2. Follow Vercel’s DNS instructions per the custom domain docs.
3. Vercel handles the TLS certificate automatically.

The Tapestry upstream is at tapestry-khaki.vercel.app (apps/docs-site/astro.config.mjs:12) — if you change this, also update the site: field in astro.config.mjs so internal links resolve.

Step 7 — Verify

After a production deploy:

1. Open the deployed URL — homepage renders.
2. Open <deployed-url>/llms.txt — should return a flattened markdown listing of all docs pages.
3. Open <deployed-url>/raw/systems/observer.md — should return the raw markdown of the Observer system page.
4. Open any docs page and click Copy page in the top-right — the dropdown should appear with three items.
5. Open <deployed-url>/observatory — the cockpit loads (may show empty cards if your Memory + Registry are also fresh; that’s normal — see First Observatory visit).

Optional — Vercel MCP plugin for Claude Code

Vercel ships an official MCP plugin that gives Claude Code direct deploy/env-management access to your Vercel projects:

npx plugins add vercel/vercel-plugin

Per Vercel’s plugin docs, this adds slash commands like /vercel-plugin:deploy prod and /vercel-plugin:env to your Claude Code session. Useful for operators managing the deployment; not needed for consumers reading the deployed site.

Cost notes

Vercel’s Hobby plan (free) covers most static + light-SSR sites; the docs corpus + cockpit fit comfortably. Watch for:

• Function invocations (SSR pages count) — the cockpit is the only SSR page; usage scales with operator dashboard visits, which is low.
• Bandwidth — static markdown + per-page raw markdown is tiny (each page ~5 KB).

The free tier is sufficient for early deployment. Upgrade if function invocations exceed the cap.

Related

• Set up Render — the backend the cockpit reads from
• Set up Grafana Cloud + OTel — the telemetry pipeline
• Observatory system page — what the cockpit is
• Docs MCP system page — the dropdown + static artifacts this Vercel deployment publishes
• Vercel getting-started docs
• Vercel CLI reference
• Vercel environment variables