Skip to main content
Railway is the fastest way to get BunShip running in production. It handles builds, deployments, networking, and TLS certificates automatically.

​
Prerequisites

​
Deploy to Railway

1

Create a new project

Log in to Railway and click New Project. Choose Deploy from GitHub repo and select your BunShip repository.Railway detects the Dockerfile automatically. Point it to docker/Dockerfile.api if it does not detect it on its own:
  1. Go to your service Settings
  2. Under Build, set the Dockerfile path to docker/Dockerfile.api
  3. Set the build context to / (repository root)
2

Add a Redis service

In your Railway project, click New and select Database > Redis.Railway provisions a managed Redis instance and exposes a REDIS_URL variable. Link it to your API service:
  1. Click the API service
  2. Go to Variables
  3. Add a reference variable: REDIS_URL = ${{Redis.REDIS_URL}}
  4. Add REDIS_HOST = ${{Redis.REDISHOST}}
  5. Add REDIS_PORT = ${{Redis.REDISPORT}}
3

Set up Turso database

BunShip uses Turso for its database. Create a production database:
Add these as Railway variables:
  • DATABASE_URL = libsql://your-db-name.turso.io
  • DATABASE_AUTH_TOKEN = your token
4

Configure environment variables

Add all remaining variables in the Railway service settings. See the full list in the Deployment Overview.The minimum set:
Generate JWT secrets with openssl rand -base64 32. Use different values for JWT_SECRET and JWT_REFRESH_SECRET.
5

Add a worker service

BunShip needs a separate worker process for background jobs. In your Railway project:
  1. Click New > GitHub Repo and select the same repository
  2. Name the service worker
  3. Set the Dockerfile path to docker/Dockerfile.api
  4. Override the start command: bun run apps/api/src/worker.ts
  5. Copy all environment variables from the API service
  6. Link the same Redis instance
The worker does not need a public domain or port.
6

Run database migrations

Open the API service’s Shell tab in Railway and run:
Alternatively, run migrations locally against the production Turso database:
7

Deploy

Push to your main branch. Railway builds and deploys automatically.
Watch the build logs in the Railway dashboard. Once the deployment succeeds, Railway assigns a public URL like https://your-service.up.railway.app.

​
Custom Domains

1

Add a domain in Railway

Go to your API service Settings > Networking > Public Networking and click Generate Domain or Custom Domain.Enter your domain, for example api.yourdomain.com.
2

Update DNS

Add a CNAME record pointing to your Railway domain:
3

Update environment variables

Change API_URL to match your custom domain:
Update the Stripe webhook endpoint URL as well.
Railway provisions TLS certificates automatically. No additional configuration is needed for HTTPS.

​
Monitoring

​
Build and Deploy Logs

Railway shows real-time build output and deploy logs in the dashboard. Click a service, then switch to the Deployments tab to see previous deployments and their logs.

​
Health Checks

Railway monitors your service automatically. To add an explicit health check:
  1. Go to service Settings > Deploy
  2. Set the health check path to /health
  3. Set the health check timeout to 30 seconds
Railway will wait for a 200 response before routing traffic to a new deployment.

​
Metrics

The Railway dashboard shows CPU, memory, and network usage per service. For deeper observability, add Sentry error tracking:

​
Alerts

Railway sends notifications for failed deployments. Configure Slack or Discord webhooks under Project Settings > Integrations for team-wide alerts.

​
Costs and Scaling

Railway bills per resource-second. Typical BunShip costs for a small SaaS: To handle more traffic, increase the API service’s memory and CPU in Settings > Resources, or deploy multiple instances by increasing the replica count.

​
Redeployments

Railway redeploys automatically on every push to your connected branch. To trigger a manual redeploy:
  1. Go to the service Deployments tab
  2. Click Redeploy on the latest deployment
To roll back, click a previous successful deployment and select Rollback.