Railway
Deploy an app on Railway with its own Postgres database, a public HTTPS address and persistent uploads.
View as MarkdownCoding agents can read this page at /docs/railway.md
Railway runs the app’s Docker image and a Postgres database in one project, gives you an HTTPS address, and redeploys when you push to GitHub. A small app usually fits within the Hobby plan’s included usage (the plan costs $5 per month at the time of writing; check railway.com/pricing). The free plan doesn’t allow custom domains and has too little credit to stay up all month.
The examples use the Scheduler. For another app, replace scheduler with the app’s folder name (for example invoicing).
Deploy on Railway (template)
Each app has a one-click Railway template. It runs the app’s published Docker image next to its own Postgres database, with a volume for uploads, a public HTTPS address and a health check. It also generates AUTH_SECRET for you.
- Scheduler: https://railway.com/deploy/10o43z
- Invoicing: https://railway.com/deploy/b4pESv
- Open the link and click Deploy. Sign in to Railway if asked. A plan with enough usage to stay up all month (Hobby or higher) is recommended.
- Wait for both services to turn green, a minute or two. Nothing is built on your account.
- Open the app service’s public address (Settings → Networking) and go to
/setupto create the admin account. See first admin. - Add what you need when you need it: email (
SMTP_URL,EMAIL_FROM), a custom domain, Google. Each guide has an “Adding this to an existing deploy” section.
To update a template deploy, redeploy the app service in Railway: it pulls the newest image (:latest), and migrations run on startup.
The manual steps below build the app from your own fork instead, if you’d rather change the code.
Deploy manually
Before you start
- A Railway account on a plan that fits your use (Hobby or higher for a custom domain).
- Your own copy of the repository on GitHub. Fork https://github.com/gtalarico/saas-clones so that you decide when to take updates.
- A value for
AUTH_SECRET. Generate it withopenssl rand -base64 32and keep it in a password manager.
1. Create the project from GitHub
- In the Railway dashboard, click New Project.
- Choose GitHub repo and select your fork. If Railway can’t see it, grant the Railway GitHub app access to the repository.
- Choose Add variables instead of Deploy Now, so the first build doesn’t fail for lack of settings.
Railway creates a service for the repository. Keep the service’s root directory empty: the Dockerfile expects the whole repository as its build context.
2. Add Postgres
On the project canvas, click + New (or press Cmd+K / Ctrl+K) and add a PostgreSQL database. Railway names it Postgres by default. Each app needs its own database, so if you deploy a second app, give it its own Postgres too.
3. Set the variables
Open the app service, go to the Variables tab, and add these. You can paste them all at once in the RAW Editor:
RAILWAY_DOCKERFILE_PATH=apps/scheduler/Dockerfile
DATABASE_URL=${{Postgres.DATABASE_URL}}
AUTH_SECRET=<paste the value you generated>
PORT=3000
What each one does:
RAILWAY_DOCKERFILE_PATHtells Railway which app to build. Railway uses it to find a Dockerfile that isn’t at the repository root.${{Postgres.DATABASE_URL}}is a reference variable: Railway fills in the connection string of the service namedPostgres. If you renamed the database, use its name instead.- There’s no
APP_URLhere: on Railway the app uses the service’s public domain (RAILWAY_PUBLIC_DOMAIN, from step 4) whenAPP_URLisn’t set. SetAPP_URLonly for a custom domain. PORT=3000fixes the port so the domain and health check always point at the right place.
Add the optional variables you need now or later, for example:
SMTP_URL=smtp://resend:re_xxxxxxxx@smtp.resend.com:587
EMAIL_FROM=Scheduler <cal@example.com>
See the email guide, the Google OAuth guide, and the app page (Scheduler or Invoicing) for every variable. Variable changes are staged; review and deploy them when Railway prompts you.
4. Create the public address
- Open the app service’s Settings.
- Under Networking, in Public Networking, click Generate Domain. If Railway asks for a port, enter
3000.
You get an address like https://scheduler-production-xxxx.up.railway.app. The app picks it up automatically.
5. Set the health check
In the app service’s Settings, find the deploy section and set the healthcheck path to /api/health. Railway then waits for the app to answer before treating a new deploy as live, and marks the deploy as failed if it never does.
6. Keep uploads
Uploaded logos and profile photos are stored on local disk by default, and a Railway service’s disk is wiped on every deploy. Pick one:
Option A: a volume (simplest).
- Right-click the project canvas (or use
Cmd+K) and create a volume, connected to the app service. - Set its mount path to
/app/data.
No variables are needed: uploads go to /app/data/uploads by default. Railway mounts volumes as root; the app takes ownership of /app/data when it starts and then runs as an unprivileged user, so you don’t need RAILWAY_RUN_UID.
Option B: a Railway Bucket (private S3-compatible storage).
-
On the project canvas, click Create and choose Bucket. Pick a region and a name.
-
Add these variables to the app service. Replace
Bucketwith your bucket’s name on the canvas:STORAGE_DRIVER=s3 S3_ENDPOINT=${{Bucket.ENDPOINT}} S3_REGION=${{Bucket.REGION}} S3_BUCKET=${{Bucket.BUCKET}} S3_ACCESS_KEY_ID=${{Bucket.ACCESS_KEY_ID}} S3_SECRET_ACCESS_KEY=${{Bucket.SECRET_ACCESS_KEY}} S3_FORCE_PATH_STYLE=true
Buckets are private. The app serves files through short-lived signed links, so that’s fine. More in the storage guide.
7. Deploy and check
-
Deploy the staged changes. The first build takes a few minutes.
-
Open the deploy logs. A successful start ends with a line like
[server] Scheduler listening on :3000 (role=all). -
Check the health endpoint:
curl -fsS https://<your-domain>/api/health # {"ok":true,"db":true,"version":"dev"} -
Open
https://<your-domain>/setupand create the admin account. See first admin.
Use a custom domain
- In the app service’s Settings > Networking, add a custom domain such as
cal.example.com. - Add the CNAME and TXT records that Railway shows at your DNS provider and wait for Railway to confirm them.
- Set
APP_URL=https://cal.example.comand redeploy. Without it, the app keeps using theup.railway.appaddress for links and sign-in. - If you use Google or Stripe, update the redirect URIs and webhook URL to the new address.
Using the Railway CLI
A coding agent can do most of these steps with the Railway CLI (railway login, railway init, railway add --database postgres, railway domain, railway logs). Command names change between CLI versions (for example, setting variables), so check railway --help before running them. Some steps, like connecting the GitHub repository and creating a volume, may be easier in the dashboard.
Updating
With the service connected to your fork, Railway redeploys whenever the branch changes. To take a new version, sync your fork with the upstream repository on GitHub. Migrations run on startup. See updates and backups.
Troubleshooting
- Build can’t find a Dockerfile, or builds the wrong thing: check
RAILWAY_DOCKERFILE_PATHand that the service’s root directory is empty. - Deploy fails its health check: read the deploy logs.
Invalid configurationlists missing or wrong variables. A database connection error meansDATABASE_URLdoesn’t point at the Postgres service. - Uploads fail with a permission error on a volume: check the deploy logs for
couldn't take ownership of /app/data. That happens if something makes the container start as a non-root user, such asRAILWAY_RUN_UIDset to a non-zero value; remove it. - Sign-in fails after adding a custom domain: set
APP_URLto the custom domain.