Open a Site
Opening a Site means creating its hosting on four platforms and wiring them together. Do the sections in this order: later ones need values the earlier ones produce. The Site web app is a separate procedure, Set up the Site web app, done after this one.
Keep every value you create in the platform that owns it. Do not paste a password, key, or token anywhere except the setting this page names for it.
Before you start. You need Railway Pro, because Railway must pull a private image from GitHub's container registry, and a GitHub plan that supports Environments. You need the Supabase CLI and uv installed to run the scripts.
1. Supabase
-
Disable public sign-ups. In the project's Auth settings, turn off new user sign-ups. Do this first. The database's access rules trust two fixed identity emails, so whoever registered one of them first through an open sign-up would own that identity. Both provisioning scripts refuse to run while sign-ups are on.
- Check: the Auth settings page shows sign-ups disabled.
-
Keep the Email provider on. The Deposit identities sign in with a password, so the Email provider must stay enabled even though sign-ups are off.
- Check: the Email provider shows as enabled.
-
Apply the migrations. From
site/db, runsupabase db push, thensupabase migration list.- Check: every file in
site/db/supabase/migrationsappears as applied both locally and remotely. - If not: read the push error. Do not edit an applied migration. Migrations apply in filename order, so a failure stops everything after it.
- Check: every file in
-
Confirm the Deposit is private and the Data API is narrow. The
depositStorage bucket must be private, and the Data API must expose only theapischema.- Check: the bucket shows as private, and the Data API settings list
apialone. - If not: stop and fix it before continuing. A public bucket or a wider schema list breaks the Site's isolation promise.
- Check: the bucket shows as private, and the Data API settings list
-
Provision the Deposit identities. The ingress and worker services each sign in as their own Auth user: ingress may only add to the Deposit, the worker may add and read. From
site/db, with the service-role key set in the shell for this one run only:$env:SUPABASE_URL = "https://<project-ref>.supabase.co" $env:SUPABASE_SERVICE_ROLE_KEY = "<service-role key>" uv run python scripts/provision_deposit_identities.pyThe script prints each identity's password once, as
<email> <password>, and writes nothing to disk. Paste each password straight into its service'sSITE_DEPOSIT_AUTH_PASSWORDvariable on Railway once that service exists (below). Then close the shell so the service-role key does not linger.- Check: the script exits 0 and prints two lines.
- If not: it exits 2 for a missing setting or while sign-ups are enabled, and 1 if an identity failed. Fix sign-ups, then rerun. The service-role key is an operator credential: neither backend process ever receives it.
-
Set the
site_ingresspassword. Ingress connects to Postgres as its ownsite_ingressrole, which can addintakerows and do nothing else. The migration creates that role with no password, so nothing can sign in as it until you set one in the Supabase SQL editor.- Check: you can build the connection string in step 7 and ingress's health check later reports
db: ok.
- Check: you can build the connection string in step 7 and ingress's health check later reports
-
Build ingress's
SITE_DATABASE_URLthrough the session pooler. Use usersite_ingress.<project-ref>, port 5432, andsslmode=require, with the password percent-encoded. Do not use the direct connection: it is IPv6-only and Railway cannot reach it.- Check: the string names the pooler host, port 5432, and
sslmode=require.
- Check: the string names the pooler host, port 5432, and
The worker's SITE_DATABASE_URL is the postgres role's connection string through the same pooler. The worker is not given a narrower database role of its own.
The operator connection string
Several scripts in this runbook ask for "the Site's operator connection string". It is the postgres role's connection string through the Session pooler. Copy it from the Supabase dashboard's Connect panel for the Site's project: choose the Session pooler, port 5432, and fill in the database password. It is the same string the worker uses as its SITE_DATABASE_URL.
It carries the database password. Never paste it into a file, a ticket, or chat. Set it in the shell for the one run that needs it, then close the shell.
Scripts: provision_deposit_identities.py, and the ingress role in 20261001120000_ingress_role.sql.
2. Twilio
Each Site has its own Twilio subaccount, and everything below belongs to it. A Site's vendor boundary matches its isolation boundary: a leaked Twilio credential should reach one customer's numbers, not every customer's. Never buy a number or create a key in the master account.
- Create the Site's Twilio subaccount. Name it for the Site, using
<site>.- Check: the subaccount appears under the master account, and you have switched to it. Every later Twilio step, including the number, the key, the webhook, and the alert, is done inside it.
- If not: stop before buying anything. A number bought in the master account breaks the boundary this step exists to keep.
- Use an MMS-capable number bought in that subaccount. An SMS-only number cannot receive photos.
- Check: the number's capabilities list MMS, and it is listed under the Site's subaccount.
- Turn on "Enforce HTTP Auth on Media URLs." Do this before the worker captures any MMS, so media can be fetched only with credentials.
- Check: the setting shows as enabled on the account that owns the number.
- Create a restricted media API key for the worker inside the subaccount, initially with only
twilio/messaging/messages.media/read. Keep its SID and secret for the worker'sTWILIO_API_KEY_SIDandTWILIO_API_KEY_SECRET, and note the subaccount's SID forTWILIO_ACCOUNT_SID. At go-live, add the permission to delete MMS media; confirm its exact name in the Twilio console. Once a new text's media is stored in the Deposit, the worker deletes Twilio's copies and leaves the message record. Older captured texts are left alone. Until the key can delete, cleanup retries every five minutes without failing Capture.- Check: the key has media read permission initially, plus media delete at go-live.
- Set the inbound webhook after ingress has its domain (Railway, below). The URL is
https://<ingress domain>/webhooks/twilio/sms#rc=3&rp=5xx,ct,rt. The fragment after#tells Twilio to retry on server errors and connection problems. - Set
TWILIO_SMS_WEBHOOK_URLon ingress to the same URL without the fragment. Twilio signs the URL without the fragment, so including it makes every signature check fail.- Check: send a test text. Ingress logs
intake_inserted. Asignature_rejectedline means the URL inTWILIO_SMS_WEBHOOK_URLdoes not match the one Twilio signed.
- Check: send a test text. Ingress logs
- Set
TWILIO_AUTH_TOKENSon ingress to the subaccount's auth token. It accepts a comma-separated list so a rotation can overlap; see Rotate credentials. - Add a Debugger email alert on error 11200. That error means Twilio could not deliver a webhook to ingress.
- Check: the alert is listed and addressed to the operator's inbox.
Reference: site/backend/.env.example lists every setting by service, with keys only.
3. Railway
One Railway project per Site, with a production environment and two services built from an image, never from the repository. MCP is an optional third service, described below.
- Create the project and the
productionenvironment. - Create two services from a placeholder image:
ingress, which is public with a Railway-generated domain, andworker, which is private. Create them from a placeholder because the first real deploy sets the image. Never connect Railway to the repository. Railway never builds; GitHub builds one image per commit.- Check:
ingresshas a generated domain, andworkerhas none.
- Check:
- Add a registry credential for GitHub's container registry on both services: a classic personal access token with only
read:packages. Without it the first deploy fails at its wait step because Railway cannot pull the image. Put a renewal reminder in the operator's calendar before the token expires.- Check: both services show the credential.
- Set the runtime variables on each service, following
site/backend/.env.example: the ingress section foringressand the worker section forworker. LeaveWORKER_EXTRACT_ENABLEDunset: Extract stays off until Turn Extract on.- Check: every required key for each service is set. A missing required setting stops the service at startup; read its log to see which.
- Create an environment-scoped project token for the
productionenvironment. It goes into GitHub as a secret, next.- Check: the token is scoped to the one environment.
Do not set the service's start command, healthcheck, replica count, or restart policy in the dashboard. The deploy workflow applies them from site/backend/deploy/services.json on every deploy, so a dashboard edit is overwritten.
4. GitHub
- Create a GitHub Environment named
site-<site>that accepts deployments frommainonly. This rule is the guard: a branch can edit its own copy of a workflow, but the Environment will not hand its secrets to a run from any other branch.- Check: the Environment's deployment branches list
mainalone.
- Check: the Environment's deployment branches list
- Add the Environment variables
RAILWAY_ENVIRONMENT_ID,RAILWAY_INGRESS_SERVICE_ID,RAILWAY_WORKER_SERVICE_ID, andINGRESS_HEALTH_URL(https://<ingress domain>/health). - Add the Environment secret
RAILWAY_PROJECT_TOKEN. - Add the Site to the workflows' site list. The matrix in
deploy.ymlanddeploy-web.ymlnames each Site's Environment. Adding one is a reviewed pull request. - Protect
main. Branch protection must block force-pushes and deletion.- Check: both rules show as on for
main.
- Check: both rules show as on for
- Run the first deploy by dispatching
Deployfrommain, then follow Deploy and roll back.
If ingress is ever deleted and recreated, its domain changes. Update the Twilio webhook, TWILIO_SMS_WEBHOOK_URL, and INGRESS_HEALTH_URL together, or ingress rejects every signature and the deploy's health check fails.
Workflow: deploy.yml.
Optional: enable MCP deployment
Only add MCP to a Site when the operator intends to turn on its connection. Until then, omit the
service and its two GitHub Environment variables: the deploy workflow skips MCP when
RAILWAY_MCP_SERVICE_ID is absent.
- Create the
mcpservice with Railway's Connect Image, giving it the GitHub container-registry image, the image thatDeploybuilt in GitHub's container registry (<registry image>:<full sha>), and the registry credential in the same step: a classic personal access token with onlyread:packages. The service is public and needs a Railway-generated domain.- Check: the service shows the image and the credential, and has a generated
<mcp domain>.
- Check: the service shows the image and the credential, and has a generated
- Set MCP's four runtime variables from the MCP section of
site/backend/.env.example:SITE_SUPABASE_URL,SITE_SUPABASE_PUBLISHABLE_KEY,SITE_WEB_URL(the Site web origin), andMCP_CANONICAL_URL(https://<mcp domain>/mcp). Do not set a start command:Deployapplies it.- Check: all four are set. A missing required setting stops the service at startup, and the service will not start without the publishable key. Read its log to see which.
- Add the GitHub Environment variables
RAILWAY_MCP_SERVICE_IDandMCP_HEALTH_URL(https://<mcp domain>/health).- Check: a
Deployrun is green, including the wait for MCP's health.
- Check: a
A running mcp service is not yet a working connection. The rest of the turn-on, including the Supabase OAuth server, the token hook, the Site URL, and the switch that opens it, is Turn MCP on, which also has the troubleshooting.
Before you call the Site open
- Sign-ups are off, and both Deposit identities exist.
GET https://<ingress domain>/healthreturns 200 withdb: okanddeposit_auth: ok.- A test text produces one
intake_insertedline, and the worker moves the row tocaptured. - The worker is still running a few minutes after its deploy. It has no healthcheck, so look at it.