Deploy on Railway

Railway deploys containers with a managed Postgres and generated domains. Clerq runs on it as a Postgres plugin plus the published app image, which migrates the database itself on first boot.

1. Create a project and add Postgres

Create a new project, then Add a service -> Database -> PostgreSQL. Railway provisions it and exposes connection variables you can reference from the app.

2. Add the app service

Add a service -> Docker Image and use:

ghcr.io/punterdigital/clerq:latest

3. Set variables

On the app service, add variables. Reference the database with Railway's variable syntax so it stays in sync:

DATABASE_URL=${{Postgres.DATABASE_URL}}
BETTER_AUTH_SECRET=a-32-char-random-secret
BETTER_AUTH_URL=https://your-app.up.railway.app

Railway injects PORT automatically and the image listens on it, so you do not set it yourself. See Environment variables for the full reference.

4. Generate a domain and redeploy

Under the app service's Settings -> Networking, generate a domain. Set BETTER_AUTH_URL to that https:// domain, then redeploy so auth callbacks use the right origin. On boot the container migrates the database and starts serving - open the domain and create your account.

The generated domain is only known after the first deploy, so setting BETTER_AUTH_URL and redeploying once is expected. For backups and version pinning, see Backups & upgrades and the production checklist.