Railway

Deploy Leanbox on Railway with automatic builds, managed PostgreSQL, and built-in networking. Use the one-click template for the fastest path, or wire everything up manually if you want more control.

Prerequisites

Before deploying, you need:

• A Railway account (a free trial is available)
• An Anthropic API key for the AI triage

One-Click Deploy

The fastest way to deploy Leanbox on Railway is using the official template:

This template automatically provisions:

• Leanbox application service
• PostgreSQL database
• Required environment variables with secure defaults

Click the deploy button

Click the Deploy on Railway button above. You'll be redirected to Railway and prompted to log in if needed.

Configure environment variables

Railway will prompt you to configure required variables. At minimum, set:

The template automatically generates secure values for BETTER_AUTH_SECRET and ENCRYPTION_KEY, wires DATABASE_URL to the managed Postgres service, and sets APP_URL to match the Railway-provided domain.

Deploy

Click Deploy to start the deployment. Railway builds the application from the Leanbox Docker image and provisions the database.

This takes approximately 3-5 minutes for the initial build.

Access your deployment

Once deployed, Railway provides a URL like leanbox-production.up.railway.app.

Click the URL in the Railway dashboard to access your Leanbox instance.

Manual Deployment

If you prefer more control over the setup, deploy Leanbox manually.

Create a new project

• Log in to Railway
• Click New Project
• Select Empty Project

Add the Leanbox service

• Click New > Docker Image
• Enter tundekozy/leanbox:latest as the image
• Railway will pull the image and create the service

Add PostgreSQL

• In your project, click New
• Select Database > PostgreSQL
• Railway provisions the database and exposes DATABASE_URL

Configure environment variables

Click on the Leanbox service and go to the Variables tab. Add the following variables:

DATABASE_URL=${{Postgres.DATABASE_URL}}
BETTER_AUTH_SECRET=<generate with: openssl rand -hex 32>
ENCRYPTION_KEY=<generate with: openssl rand -hex 32>
APP_URL=https://<your-railway-url>.up.railway.app
ANTHROPIC_API_KEY=sk-ant-...

Use ${{Postgres.DATABASE_URL}} to reference the Railway-managed Postgres service. Railway automatically resolves this reference and keeps it in sync if the database is updated.

Deploy

Click Deploy or push a commit to trigger a new deployment. Railway builds and deploys the application automatically.

Environment Variables

Railway manages environment variables through its dashboard. The full list of configuration options is documented in the Docker guide.

Referencing Railway Services

Railway lets you reference other services in your project using the ${{ServiceName.VARIABLE}} syntax:

DATABASE_URL=${{Postgres.DATABASE_URL}}

This keeps connection strings in sync when Railway updates service configurations.

Database Setup

Railway's managed PostgreSQL handles provisioning automatically. The database:

• Runs PostgreSQL 16 by default
• Includes automatic backups on paid plans
• Provides connection pooling via the internal network

Leanbox runs database migrations automatically on startup, so there's nothing to invoke manually after each deploy.

Accessing the Database

To connect directly to your database for debugging or maintenance:

• In your Railway project dashboard, select the PostgreSQL service
• Open the Connect tab — it shows the connection string and credentials
• Use the provided connection string with your preferred PostgreSQL client

Custom Domain

Railway provides a generated URL by default. To use your own domain:

Generate a domain

• Click on your Leanbox service
• Go to Settings > Networking
• Click Generate Domain to get a Railway subdomain, or proceed to add a custom domain

Add custom domain

• In Settings > Networking, click Custom Domain
• Enter your domain (e.g. leanbox.yourdomain.com)
• Railway provides DNS records to configure

Configure DNS

Add the following DNS record at your domain registrar:

DNS propagation can take up to 24 hours.

Update environment variable

Update APP_URL to match your custom domain:

APP_URL=https://leanbox.yourdomain.com

Railway automatically provisions and renews SSL certificates for custom domains.

Scaling Options

Railway provides several options for scaling your Leanbox deployment.

Vertical Scaling

Increase resources for your service:

• In the Railway dashboard, select the Leanbox service
• Open Settings, then raise the memory and CPU limits
• Railway scales within these limits based on demand

Horizontal Scaling

Leanbox is stateless (sessions live in Postgres), so it scales horizontally out of the box:

• Select your Leanbox service and open Settings
• Turn on Horizontal Scaling
• Choose how many replicas to run — Railway load-balances traffic across them

Database Scaling

For high-traffic deployments:

• Upgrade to a larger PostgreSQL instance in Railway
• Consider using connection pooling with PgBouncer
• Configure read replicas for read-heavy workloads

Updating Leanbox

To update to a new Leanbox release:

• Open your Leanbox service in Railway
• Go to Settings > Source and update the image tag (e.g. from tundekozy/leanbox:latest to a specific version like tundekozy/leanbox:1.2.0)
• Click Deploy — Railway pulls the new image and runs pending database migrations on startup

Troubleshooting

Build fails

Check the deploy logs in Railway. The most common causes are:

• Wrong image name — confirm it's tundekozy/leanbox:latest
• Missing required environment variables — re-check the list above

Application crashes on startup

Open the Deployments tab and inspect the runtime logs. Usually it's:

• DATABASE_URL not pointing at a reachable Postgres
• ENCRYPTION_KEY or BETTER_AUTH_SECRET not set / not 32 bytes of hex

See Also

• Docker — full environment variable reference
• Connect Gmail — set up Gmail OAuth
• Connect Instagram — set up Instagram OAuth