Browse this guideSet up the Site web app
DevelopmentUpdated 2026-11-12

Set up the Site web app

The Site web app is where a customer's administrator signs in, runs the Review Queue, and maintains projects, people, and the typology. An active staff login reaches Connected apps and can approve its own assistant connections. Each Site has its own Vercel project and its own build. Do this after Open a Site: it needs the Supabase project and the GitHub Environment.

Choose the Site's address first. It can be a Vercel-generated domain or a custom one. The address is baked into the build and into Supabase's sign-in settings, so changing it later means repeating steps 3 and 4 below.

1. Vercel

  1. Create one Vercel project for the Site with git integration off, Root Directory site/web, and Framework Preset Next.js. Save the project settings after choosing the preset. Vercel must never build this repository on its own schedule: the deploy workflow builds and uploads, so no commit reaches a Site without passing CI.
    • Check: the project shows no connected git repository, and its saved Framework Preset shows Next.js.
  2. Set no NEXT_PUBLIC_* variables in Vercel itself. The deploy workflow supplies them at build time from the GitHub Environment.
    • Check: the project's environment variables list is empty of NEXT_PUBLIC_* keys.
  3. Add these to the Site's GitHub Environment site-<site>. Variables: VERCEL_ORG_ID, VERCEL_PROJECT_ID, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, and NEXT_PUBLIC_SITE_URL. Secret: VERCEL_TOKEN.
    • The publishable key is designed to ship in browser code and reaches only what a signed-in caller's access rules allow. The service-role key never goes in this Environment and never reaches the app.
    • NEXT_PUBLIC_SITE_URL is the app's own address with no path, and must be https for a deployment.
    • Check: the deploy step in step 5 passes its settings check. A missing or malformed setting is reported by key name, never by value.

References: site/web/.env.example lists the three public keys, and deploy-web.yml builds and deploys on every green main.

2. Apply the migrations the app needs

The app's access gate calls api.current_principal() for signed-in requests to non-public routes. It admits any active Site principal and shows pages by role: administrators reach the whole Site; staff reach /connected-apps and /oauth/consent. Other paths redirect staff to Connected apps. A missing or revoked principal, or platform support, gets no access; a failed check returns 503.

Apply the Site's migrations before deploying the web app, in this order:

  1. 20261112120000_current_principal.sql, which supplies the caller read used by the access gate.
  2. 20261113100000_company_name_for_principals.sql, which lets active Site principals read the company name for the header. Setting the name remains administrator-only, and OAuth client tokens cannot call this read.
  3. Deploy the web app.

When rolling back, roll back the web deploy before reversing these migrations. Reversing the company-name read restores administrator-only access without changing stored data; reversing the caller read while the new web app still runs makes its access check fail. The MCP server also uses api.current_principal(), so roll it back before removing that function. The order rule is in Deploy and roll back.

3. Sign-in email

Administrators and staff with an active login sign in with a magic link emailed to them.

  1. Configure an SMTP provider for the hosted Supabase project's Auth emails.
    • Check: send a test email from the Auth settings and receive it.
  2. Set the Auth Site URL to <site url>, and allow the redirect <site url>/auth/callback.
    • Check: both appear in the Auth URL settings.
  3. Keep sign-ups disabled. The app never creates users: its sign-in request refuses to create one, and an administrator exists only because an operator provisioned them.
  4. Optional: make links work on another device. Set the magic-link email template to {{ .SiteURL }}/auth/callback?token_hash={{ .TokenHash }}&type=magiclink. With the default template, a link works only in the browser that requested it.

4. Administrators

An administrator is a customer's person who signs in to run their Site. The operator has no Site account and no standing access to a customer's content; provisioning is the only thing the operator does here.

  1. Provision each administrator, once per person. From site/db, with the service-role key and the operator connection string set in the shell for this run only:

    $env:SUPABASE_URL = "https://<project-ref>.supabase.co"
    $env:SUPABASE_SERVICE_ROLE_KEY = "<service-role key>"
    $env:SITE_DATABASE_URL = "<operator connection string>"
    uv run python scripts/provision_administrator.py --email <email> --name "<display name>"
    

    The script creates a confirmed Auth user with no password, so the only way in is a link mailed to that address. In one transaction it also creates the person, the principal holding the administrator role, and a principal.provisioned Daybook event.

    • Check: the script prints <email> <principal id> and exits 0.
    • If not: it exits 2 for a missing setting or while sign-ups are enabled, and 1 for any other failure. If the database step fails after the Auth user was created, the script deletes the Auth user again, so a rerun is safe.
  2. Revoke an administrator when they leave: uv run python scripts/provision_administrator.py --revoke <email>. It revokes administrators only, emits principal.revoked, and signs the user out everywhere.

    • Check: the revoked person can still request a link, but the app shows "no access".
    • An access token already issued stays valid for up to an hour (jwt_expiry), though the revoked principal is denied every read at once.

Script: provision_administrator.py.

5. First deploy

Dispatch Deploy web from main, or merge to main and let CI trigger it. The workflow runs the Vercel CLI from the repository root, the pnpm workspace root, while the Vercel project's Root Directory remains site/web. Watch the first Deploy web run closely.

6. First checks after a Site's first web deploy

Do these once, as the first administrator, before the customer's administrator is told the Site is ready.

  1. Sign in with a magic link.
    • Check: you land in the app. If you see "no access", the principal was not provisioned or was revoked. If you see a 503, the access gate's migration is not applied.
  2. Set the company name. Open Settings and enter the company's name, then save. The Site's header shows it.
    • Check: the header shows the name after saving.
  3. Walk Projects and People, Typology, and the Review Queue once. For each Review Queue item type, take its actions, check the customer-visible confirmation where there is one, and open an attachment.
    • Check: every action completes without an error page.
  4. Open an original message. Confirm an administrator can open the original of an intake, which proves the Deposit Storage read works through the app.
    • Check: the original opens. If it does not, the Deposit Storage policies and the deposit bucket are the first places to look.

Then continue to Turn Extract on.