{"id":"deployment","relativePath":"deployment.md","title":"Deployment — Vercel + Render","markdown":"# Deployment — Vercel + Render\n\nHow the Meta Museum system maps onto hosted infrastructure.\n\n| Piece | Host | Config |\n|---|---|---|\n| Next.js 16 web app (29 pages, 125 API routes) | **Vercel** | `vercel.json` |\n| Postgres (system of record) | **Neon** or Vercel Postgres | `DATABASE_URL` |\n| Validation service (pySHACL) | **Render** | `render.yaml` |\n| Reconciliation service (+ Redis) | **Render** | `render.yaml` |\n| AG2 worker (optional, disabled by default) | **Render** | `render.yaml` |\n| Background workers (outbox / publish queue) | TBD — see [Part C](#part-c--background-workers) | — |\n| Solr / GraphDB (Era C search + graph) | Off for this deploy | gated by `OUTBOX_PROJECT_TO_*` |\n\nA read-only public demo needs only **Vercel + Neon**. The Render services add validation/reconciliation; the workers add async projection/publishing.\n\n---\n\n## Part A — Next.js on Vercel\n\n### One-time setup\n1. Import the repo in Vercel. Framework auto-detects as **Next.js**.\n2. `vercel.json` already overrides the build:\n - `buildCommand: next build` — **critical.** The repo's `pnpm build` runs `session:closeout:check` first, which fails 24h after the last close-out and would break every deploy. `next build` skips that guard. Local `pnpm build` is unchanged and still enforces the guard.\n3. Provision **Neon Postgres** (or Vercel Postgres) and copy the **pooled** connection string.\n4. Set the env vars below (Project → Settings → Environment Variables), then deploy.\n\n### Vercel environment variables\n| Var | Required | Value |\n|---|---|---|\n| `DATABASE_URL` | ✅ | Neon **pooled** connection string |\n| `METAMUSEUM_STORAGE_MODE` | ✅ | `postgres` |\n| `AUTH_SECRET` | ✅ | `openssl rand -base64 32` |\n| `BASE_URL` | ✅ | `https://.vercel.app` |\n| `METAMUSEUM_PUBLIC_READ_BASE_URL` | ✅ | same as `BASE_URL` |\n| `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET` | ⛔ optional | enables GitHub sign-in; omit for public read-only |\n| `VALIDATION_SERVICE_URL` | ⛔ optional | `https://metamuseum-validation.onrender.com/validate` (Part B) |\n| `METAMUSEUM_AG2_BRIDGE_ENABLED` | ⛔ optional | leave unset (bridge stays off) |\n\nNotes:\n- **Storage self-heals on a fresh DB.** Core stores (`records.ts`) catch a missing Postgres document and seed an empty `[]`, so an empty Neon DB won't crash the app.\n- **Runtime is Node, not Edge** for API routes (required by `pg` + Auth.js v5) — this is the App Router default; no action needed.\n- **Read-only FS caveat:** the 16 managed documents go to Postgres, but a route that writes a *non-managed* JSON file would hit Vercel's read-only filesystem. Core browse/explore/records flows are managed-doc only.\n\n---\n\n## Part B — Python services on Render\n\n`render.yaml` is a Blueprint defining three FastAPI web services + a Redis cache.\n\n### Setup\n1. In Render: **New → Blueprint**, point at this repo. It reads `render.yaml`.\n2. Each service: own `rootDir`, `pip install -r requirements.txt`, and\n `uvicorn main:APP --host 0.0.0.0 --port $PORT` (bypasses the hardcoded\n `127.0.0.1` in each `__main__`). Health check: `/health`.\n3. Redis (`metamuseum-reconcile-cache`) is wired into the reconciliation\n service via `RECONCILIATION_REDIS_URL` automatically.\n4. **AG2 worker is optional** — delete that block from `render.yaml` unless you\n plan to enable the bridge.\n\n### Wire services back to Vercel\nAfter Render assigns URLs, set on Vercel:\n- `VALIDATION_SERVICE_URL = https://metamuseum-validation.onrender.com/validate`\n\nThe reconciliation service is invoked by operator scripts/ops tooling rather\nthan the Next runtime; point those at `https://metamuseum-reconciliation.onrender.com`.\n\n> **Free-tier caveat:** Render free web services sleep after inactivity and\n> cold-start in ~30–60s. Fine for a demo; upgrade to paid for pilots.\n\n---\n\n## Part C — Background workers\n\nTwo long-running drains exist as `tsx` scripts; neither runs on Vercel\n(no persistent processes):\n\n| Worker | Script | Needed when |\n|---|---|---|\n| Outbox projector | `pnpm outbox:projector` | Solr/GraphDB projection is enabled (off in this deploy) |\n| Publish queue worker | `pnpm publish:queue:worker` | Wiki/publication publishing is used |\n\n**For the read-only demo: neither is required.** Decide before enabling\nprojection or publishing. Options:\n\n1. **Vercel Cron → drain-once endpoint** (recommended for demo→beta).\n Add `vercel.json` cron entries hitting thin API routes that call the\n `--once` drain path, e.g. every 5 min. Serverless-native, no extra host.\n Requires adding small `/api/cron/outbox` + `/api/cron/publish` routes.\n2. **Render Cron Job / Background Worker** (recommended if projection is heavy).\n Add a Node-runtime cron service to `render.yaml` running\n `pnpm outbox:projector:once`. Keeps long/heavy drains off the request path.\n3. **External scheduler** (GitHub Actions on a schedule) — simplest, lowest\n throughput; good for low-volume publishing.\n\n**Recommendation:** ship the demo with workers off; when projection/publishing\nis turned on, use **Vercel Cron (option 1)** first and graduate to **Render\n(option 2)** only if drain volume outgrows serverless timeouts.\n\n---\n\n## Quick path to a live demo\n1. Neon DB → copy pooled `DATABASE_URL`.\n2. Vercel import → set `DATABASE_URL`, `METAMUSEUM_STORAGE_MODE=postgres`,\n `AUTH_SECRET`, `BASE_URL`, `METAMUSEUM_PUBLIC_READ_BASE_URL` → deploy.\n3. (Optional) Render Blueprint → set `VALIDATION_SERVICE_URL` on Vercel → redeploy.\n4. Workers stay off until projection/publishing is needed.\n","sections":[{"level":2,"heading":"Part A — Next.js on Vercel","anchor":"part-a-next-js-on-vercel"},{"level":3,"heading":"One-time setup","anchor":"one-time-setup"},{"level":3,"heading":"Vercel environment variables","anchor":"vercel-environment-variables"},{"level":2,"heading":"Part B — Python services on Render","anchor":"part-b-python-services-on-render"},{"level":3,"heading":"Setup","anchor":"setup"},{"level":3,"heading":"Wire services back to Vercel","anchor":"wire-services-back-to-vercel"},{"level":2,"heading":"Part C — Background workers","anchor":"part-c-background-workers"},{"level":2,"heading":"Quick path to a live demo","anchor":"quick-path-to-a-live-demo"}],"html":"

Deployment — Vercel + Render

\n

How the Meta Museum system maps onto hosted infrastructure.

\n

| Piece | Host | Config |

\n

|---|---|---|

\n

| Next.js 16 web app (29 pages, 125 API routes) | Vercel | `vercel.json` |

\n

| Postgres (system of record) | Neon or Vercel Postgres | `DATABASE_URL` |

\n

| Validation service (pySHACL) | Render | `render.yaml` |

\n

| Reconciliation service (+ Redis) | Render | `render.yaml` |

\n

| AG2 worker (optional, disabled by default) | Render | `render.yaml` |

\n

| Background workers (outbox / publish queue) | TBD — see Part C(#part-c--background-workers) | — |

\n

| Solr / GraphDB (Era C search + graph) | Off for this deploy | gated by `OUTBOX_PROJECT_TO_*` |

\n

A read-only public demo needs only Vercel + Neon. The Render services add validation/reconciliation; the workers add async projection/publishing.

\n

---

\n

Part A — Next.js on Vercel

\n

One-time setup

\n
  1. Import the repo in Vercel. Framework auto-detects as Next.js.
\n
  1. `vercel.json` already overrides the build:
\n
  1. Provision Neon Postgres (or Vercel Postgres) and copy the pooled connection string.
\n
  1. Set the env vars below (Project → Settings → Environment Variables), then deploy.
\n\n

Vercel environment variables

\n

| Var | Required | Value |

\n

|---|---|---|

\n

| `DATABASE_URL` | ✅ | Neon pooled connection string |

\n

| `METAMUSEUM_STORAGE_MODE` | ✅ | `postgres` |

\n

| `AUTH_SECRET` | ✅ | `openssl rand -base64 32` |

\n

| `BASE_URL` | ✅ | `https://<your-app>.vercel.app` |

\n

| `METAMUSEUM_PUBLIC_READ_BASE_URL` | ✅ | same as `BASE_URL` |

\n

| `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET` | ⛔ optional | enables GitHub sign-in; omit for public read-only |

\n

| `VALIDATION_SERVICE_URL` | ⛔ optional | `https://metamuseum-validation.onrender.com/validate` (Part B) |

\n

| `METAMUSEUM_AG2_BRIDGE_ENABLED` | ⛔ optional | leave unset (bridge stays off) |

\n

Notes:

\n\n

---

\n

Part B — Python services on Render

\n

`render.yaml` is a Blueprint defining three FastAPI web services + a Redis cache.

\n

Setup

\n
  1. In Render: New → Blueprint, point at this repo. It reads `render.yaml`.
\n
  1. Each service: own `rootDir`, `pip install -r requirements.txt`, and
\n

`uvicorn main:APP --host 0.0.0.0 --port $PORT` (bypasses the hardcoded

\n

`127.0.0.1` in each `__main__`). Health check: `/health`.

\n
  1. Redis (`metamuseum-reconcile-cache`) is wired into the reconciliation
\n

service via `RECONCILIATION_REDIS_URL` automatically.

\n
  1. AG2 worker is optional — delete that block from `render.yaml` unless you
\n

plan to enable the bridge.

\n

Wire services back to Vercel

\n

After Render assigns URLs, set on Vercel:

\n\n

The reconciliation service is invoked by operator scripts/ops tooling rather

\n

than the Next runtime; point those at `https://metamuseum-reconciliation.onrender.com`.

\n
Free-tier caveat: Render free web services sleep after inactivity and
\n
cold-start in ~30–60s. Fine for a demo; upgrade to paid for pilots.
\n

---

\n

Part C — Background workers

\n

Two long-running drains exist as `tsx` scripts; neither runs on Vercel

\n

(no persistent processes):

\n

| Worker | Script | Needed when |

\n

|---|---|---|

\n

| Outbox projector | `pnpm outbox:projector` | Solr/GraphDB projection is enabled (off in this deploy) |

\n

| Publish queue worker | `pnpm publish:queue:worker` | Wiki/publication publishing is used |

\n

For the read-only demo: neither is required. Decide before enabling

\n

projection or publishing. Options:

\n
  1. Vercel Cron → drain-once endpoint (recommended for demo→beta).
\n

Add `vercel.json` cron entries hitting thin API routes that call the

\n

`--once` drain path, e.g. every 5 min. Serverless-native, no extra host.

\n

Requires adding small `/api/cron/outbox` + `/api/cron/publish` routes.

\n
  1. Render Cron Job / Background Worker (recommended if projection is heavy).
\n

Add a Node-runtime cron service to `render.yaml` running

\n

`pnpm outbox:projector:once`. Keeps long/heavy drains off the request path.

\n
  1. External scheduler (GitHub Actions on a schedule) — simplest, lowest
\n

throughput; good for low-volume publishing.

\n

Recommendation: ship the demo with workers off; when projection/publishing

\n

is turned on, use Vercel Cron (option 1) first and graduate to **Render

\n

(option 2)** only if drain volume outgrows serverless timeouts.

\n

---

\n

Quick path to a live demo

\n
  1. Neon DB → copy pooled `DATABASE_URL`.
\n
  1. Vercel import → set `DATABASE_URL`, `METAMUSEUM_STORAGE_MODE=postgres`,
\n

`AUTH_SECRET`, `BASE_URL`, `METAMUSEUM_PUBLIC_READ_BASE_URL` → deploy.

\n
  1. (Optional) Render Blueprint → set `VALIDATION_SERVICE_URL` on Vercel → redeploy.
\n
  1. Workers stay off until projection/publishing is needed.
","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"4911b1f459b5c331dc05f45b1d453bee478c0b43f5485b0e90293e03b51289ac","checksumPrefix":"4911b1f459b5","anchorCount":8,"lineCount":108,"rawUrl":"/api/docs/content?path=deployment.md","htmlUrl":"/docs?doc=deployment.md","apiUrl":"/api/docs/content?path=deployment.md"}