Browse this guideOpen a Site
DevelopmentUpdated 2026-11-10

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

  1. 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.
  2. 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.
  3. Apply the migrations. From site/db, run supabase db push, then supabase migration list.

    • Check: every file in site/db/supabase/migrations appears 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.
  4. Confirm the Deposit is private and the Data API is narrow. The deposit Storage bucket must be private, and the Data API must expose only the api schema.

    • Check: the bucket shows as private, and the Data API settings list api alone.
    • If not: stop and fix it before continuing. A public bucket or a wider schema list breaks the Site's isolation promise.
  5. 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.py
    

    The script prints each identity's password once, as <email> <password>, and writes nothing to disk. Paste each password straight into its service's SITE_DEPOSIT_AUTH_PASSWORD variable 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.
  6. Set the site_ingress password. Ingress connects to Postgres as its own site_ingress role, which can add intake rows 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.
  7. Build ingress's SITE_DATABASE_URL through the session pooler. Use user site_ingress.<project-ref>, port 5432, and sslmode=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.

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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's TWILIO_API_KEY_SID and TWILIO_API_KEY_SECRET, and note the subaccount's SID for TWILIO_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.
  5. 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.
  6. Set TWILIO_SMS_WEBHOOK_URL on 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. A signature_rejected line means the URL in TWILIO_SMS_WEBHOOK_URL does not match the one Twilio signed.
  7. Set TWILIO_AUTH_TOKENS on ingress to the subaccount's auth token. It accepts a comma-separated list so a rotation can overlap; see Rotate credentials.
  8. 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.

  1. Create the project and the production environment.
  2. Create two services from a placeholder image: ingress, which is public with a Railway-generated domain, and worker, 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: ingress has a generated domain, and worker has none.
  3. 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.
  4. Set the runtime variables on each service, following site/backend/.env.example: the ingress section for ingress and the worker section for worker. Leave WORKER_EXTRACT_ENABLED unset: 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.
  5. Create an environment-scoped project token for the production environment. 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

  1. Create a GitHub Environment named site-<site> that accepts deployments from main only. 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 main alone.
  2. Add the Environment variables RAILWAY_ENVIRONMENT_ID, RAILWAY_INGRESS_SERVICE_ID, RAILWAY_WORKER_SERVICE_ID, and INGRESS_HEALTH_URL (https://<ingress domain>/health).
  3. Add the Environment secret RAILWAY_PROJECT_TOKEN.
  4. Add the Site to the workflows' site list. The matrix in deploy.yml and deploy-web.yml names each Site's Environment. Adding one is a reviewed pull request.
  5. Protect main. Branch protection must block force-pushes and deletion.
    • Check: both rules show as on for main.
  6. Run the first deploy by dispatching Deploy from main, 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.

  1. Create the mcp service with Railway's Connect Image, giving it the GitHub container-registry image, the image that Deploy built in GitHub's container registry (<registry image>:<full sha>), and the registry credential in the same step: a classic personal access token with only read: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>.
  2. 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), and MCP_CANONICAL_URL (https://<mcp domain>/mcp). Do not set a start command: Deploy applies 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.
  3. Add the GitHub Environment variables RAILWAY_MCP_SERVICE_ID and MCP_HEALTH_URL (https://<mcp domain>/health).
    • Check: a Deploy run is green, including the wait for MCP's health.

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