# Railway

> Deploy an app on Railway with its own Postgres database, a public HTTPS address and persistent uploads.

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](https://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

1. 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.
2. Wait for both services to turn green, a minute or two. Nothing is built on your account.
3. Open the app service's public address (Settings → Networking) and go to `/setup` to create the admin account. See [first admin](./first-admin.md).
4. Add what you need when you need it: [email](./email.md) (`SMTP_URL`, `EMAIL_FROM`), a [custom domain](#use-a-custom-domain), [Google](./google-oauth.md). 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 with `openssl rand -base64 32` and keep it in a password manager.

### 1. Create the project from GitHub

1. In the Railway dashboard, click **New Project**.
2. Choose **GitHub repo** and select your fork. If Railway can't see it, grant the Railway GitHub app access to the repository.
3. 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**:

```sh
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_PATH` tells 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 named `Postgres`. If you renamed the database, use its name instead.
- There's no `APP_URL` here: on Railway the app uses the service's public domain (`RAILWAY_PUBLIC_DOMAIN`, from step 4) when `APP_URL` isn't set. Set `APP_URL` only for a custom domain.
- `PORT=3000` fixes 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:

```sh
SMTP_URL=smtp://resend:re_xxxxxxxx@smtp.resend.com:587
EMAIL_FROM=Scheduler <cal@example.com>
```

See the [email guide](./email.md), the [Google OAuth guide](./google-oauth.md), and the app page ([Scheduler](./scheduler.md) or [Invoicing](./invoicing.md)) for every variable. Variable changes are staged; review and deploy them when Railway prompts you.

### 4. Create the public address

1. Open the app service's **Settings**.
2. 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).**

1. Right-click the project canvas (or use `Cmd+K`) and create a volume, connected to the app service.
2. 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).

1. On the project canvas, click **Create** and choose **Bucket**. Pick a region and a name.
2. Add these variables to the app service. Replace `Bucket` with your bucket's name on the canvas:

   ```sh
   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](./storage.md#railway-buckets).

### 7. Deploy and check

1. Deploy the staged changes. The first build takes a few minutes.
2. Open the deploy logs. A successful start ends with a line like `[server] Scheduler listening on :3000 (role=all)`.
3. Check the health endpoint:

   ```sh
   curl -fsS https://<your-domain>/api/health
   # {"ok":true,"db":true,"version":"dev"}
   ```

4. Open `https://<your-domain>/setup` and create the admin account. See [first admin](./first-admin.md).

## Use a custom domain

1. In the app service's **Settings > Networking**, add a custom domain such as `cal.example.com`.
2. Add the CNAME and TXT records that Railway shows at your DNS provider and wait for Railway to confirm them.
3. Set `APP_URL=https://cal.example.com` and redeploy. Without it, the app keeps using the `up.railway.app` address for links and sign-in.
4. 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](https://docs.railway.com/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](./updates-backups.md).

## Troubleshooting

- **Build can't find a Dockerfile, or builds the wrong thing:** check `RAILWAY_DOCKERFILE_PATH` and that the service's root directory is empty.
- **Deploy fails its health check:** read the deploy logs. `Invalid configuration` lists missing or wrong variables. A database connection error means `DATABASE_URL` doesn'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 as `RAILWAY_RUN_UID` set to a non-zero value; remove it.
- **Sign-in fails after adding a custom domain:** set `APP_URL` to the custom domain.