---
title: Set up Vercel 
description: Step-by-step walkthrough for deploying Tapestry's frontend on Vercel — the Astro Starlight docs site (this site) and the Observatory cockpit. You run this once per surface for your own deployment.
---

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](/reference/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/`](https://github.com/Lizo-RoadTown/tapestry/tree/main/apps/docs-site) | Astro Starlight content + the static `/llms.txt` + per-page `/raw/<slug>.md` artifacts produced by [`scripts/generate-static-docs.mjs`](https://github.com/Lizo-RoadTown/tapestry/blob/main/apps/docs-site/scripts/generate-static-docs.mjs) (prebuild step) |
| **Observatory cockpit** | [`apps/docs-site/src/pages/observatory.astro`](https://github.com/Lizo-RoadTown/tapestry/tree/main/apps/docs-site/src/pages) | Interactive variable-overlay view; SSR (opt-out from static prerender at [observatory.astro:1](https://github.com/Lizo-RoadTown/tapestry/blob/main/apps/docs-site/src/pages/observatory.astro) — `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](https://vercel.com/signup) (free tier is enough to start; check [Vercel's pricing](https://vercel.com/pricing) when traffic grows)
- [Node.js 18+](https://nodejs.org/) on your machine
- A GitHub account connected to the tapestry repo

## Step 1 — Install the Vercel CLI

From the [Vercel getting-started docs](https://vercel.com/docs/getting-started-with-vercel):

```sh
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)

```sh
cd apps/docs-site
vercel
```

Per the [Vercel CLI docs](https://vercel.com/docs/cli), `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:

```sh
vercel --prod
```

Per [Vercel's deploy docs](https://vercel.com/docs/getting-started-with-vercel), `--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](https://github.com/Lizo-RoadTown/tapestry/blob/main/apps/docs-site/package.json):

```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](https://vercel.com/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](https://vercel.com/docs/git/vercel-for-github), 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](https://vercel.com/docs/environment-variables):

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](https://vercel.com/docs/domains/set-up-custom-domain).
3. Vercel handles the TLS certificate automatically.

The Tapestry upstream is at `tapestry-khaki.vercel.app` ([apps/docs-site/astro.config.mjs:12](https://github.com/Lizo-RoadTown/tapestry/blob/main/apps/docs-site/astro.config.mjs)) — 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](/start/first-observatory-visit/)).

## Optional — Vercel MCP plugin for Claude Code

Vercel ships an [official MCP plugin](https://vercel.com/docs/agent-resources/vercel-plugin) that gives Claude Code direct deploy/env-management access to your Vercel projects:

```sh
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)](https://vercel.com/pricing) 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](/how-to/set-up-render/) — the backend the cockpit reads from
- [Set up Grafana Cloud + OTel](/how-to/set-up-grafana-cloud/) — the telemetry pipeline
- [Observatory system page](/systems/observatory/) — what the cockpit is
- [Docs MCP system page](/systems/docs-mcp/) — the dropdown + static artifacts this Vercel deployment publishes
- [Vercel getting-started docs](https://vercel.com/docs/getting-started-with-vercel)
- [Vercel CLI reference](https://vercel.com/docs/cli)
- [Vercel environment variables](https://vercel.com/docs/environment-variables)