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
- 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 passingCI.- Check: the project shows no connected git repository, and its saved Framework Preset shows Next.js.
- 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.
- Check: the project's environment variables list is empty of
- 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, andNEXT_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_URLis the app's own address with no path, and must behttpsfor 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:
20261112120000_current_principal.sql, which supplies the caller read used by the access gate.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.- 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.
- Configure an SMTP provider for the hosted Supabase project's Auth emails.
- Check: send a test email from the Auth settings and receive it.
- Set the Auth Site URL to
<site url>, and allow the redirect<site url>/auth/callback.- Check: both appear in the Auth URL settings.
- 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.
- 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.
-
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.provisionedDaybook 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.
- Check: the script prints
-
Revoke an administrator when they leave:
uv run python scripts/provision_administrator.py --revoke <email>. It revokes administrators only, emitsprincipal.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.
- Check: the run reaches its deploy step and finishes. It reports its own failure by exit code: 2 for a missing or wrong setting, 3 pulling the project, 4 building, 5 deploying.
- If not: exit 2 names the key to fix in the GitHub Environment. Exit 4 with
No Output Directory named "public"means the Framework Preset had not been saved as Next.js, so Vercel used its static builder. Exit 5 with a missingsite/web/site/webpath, or a missingnode_modules/.pnpm/...file, means the CLI ran from the wrong directory; it must run from the repository root. For another exit 3 to 5 failure, check the Vercel token, project ids, and Root Directory in that order.
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.
- 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.
- 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.
- 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.
- 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
depositbucket are the first places to look.
- Check: the original opens. If it does not, the Deposit Storage policies and the
Then continue to Turn Extract on.