Deploy SaaS kit to Railway

Railway is a modern cloud platform that makes it easy to deploy full-stack applications with databases and storage. This guide walks you through deploying your application to Railway.

Prerequisites

Before you begin, ensure you have:

1. A Railway account
2. Your application code pushed to a GitHub repository
3. Your billing provider credentials (Stripe, Polar)

Architecture Overview

Your Railway deployment will consist of three services:

1. Web Service - Your Next.js application
2. Postgres Database - Railway's managed PostgreSQL instance (if you use a different database, you can use the external provider's database)
3. Storage Bucket - S3-compatible object storage for file uploads (if you use a different storage provider, you can use the external provider's storage)

Step 1: Create a New Railway Project

1. Log in to your Railway dashboard
2. Click New Project
3. Select Deploy from GitHub repo
4. Connect your GitHub account if not already connected
5. Select your repository

Railway will automatically detect your Next.js application and begin the initial deployment setup.

Note: the initial deployment will fail because we need to configure the environment variables. It's okay, we will do that in the next steps.

Step 2: Add a PostgreSQL Database

1. In your project canvas, click the + New button
2. Select Database → Add PostgreSQL
3. Railway will provision a PostgreSQL instance with SSL enabled

The database will appear in your architecture view with a postgres-volume for persistent storage.

We will need the variable DATABASE_URL to connect to the database. You can find it in the Credentials tab of the Postgres service.

Step 3: Add S3-Compatible Storage

Railway provides S3-compatible storage buckets for file uploads:

1. Click the + New button in your project canvas
2. Select Storage Bucket
3. Choose your preferred region (e.g., US West - California, USA)

After creation, click on the Storage Bucket service to view:

• Credentials tab: Contains your S3 access credentials
• Settings tab: Shows the bucket region and management options

Step 4: Configure Environment Variables

Click on your web service and navigate to the Variables tab. You need to configure the following environment variables:

Database Configuration

DATABASE_URL=${{Postgres.DATABASE_URL}}

Railway automatically injects the DATABASE_URL when you reference it using the ${{Postgres.DATABASE_URL}} syntax. This ensures your web service always has the correct connection string.

Site Configuration

Please copy the exposes URL of your web service that you find in the web service and set it as the NEXT_PUBLIC_SITE_URL environment variable.

NEXT_PUBLIC_SITE_URL=https://your-domain.up.railway.app

Replace with your actual Railway domain or custom domain.

Storage Configuration

Configure the S3-compatible storage variables from your Storage Bucket credentials:

STORAGE_BASE_URL=https://your-bucket.railway.storage
STORAGE_S3_ACCESS_KEY_ID=your-access-key
STORAGE_S3_SECRET_ACCESS_KEY=your-secret-key
STORAGE_S3_BUCKET=your-bucket-name
STORAGE_S3_REGION=us-west-1

Billing Provider Configuration

Set your billing provider and its credentials:

NEXT_PUBLIC_BILLING_PROVIDER=stripe

The NEXT_PUBLIC_BILLING_PROVIDER can be one of: stripe or polar.

For Stripe:

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

For Polar:

NEXT_PUBLIC_BILLING_PROVIDER=polar
POLAR_ACCESS_TOKEN=your-polar-access-token

Complete Environment Variables List

Here's a summary of all the minumum required environment variables that you need to set:

Plus your billing provider-specific variables as listed above.

Other Environment Variables

Step 5: Run Database Migrations

After setting up your environment variables, run Drizzle migrations to create your database schema.

Copy the DATABASE_URL from Railway's Postgres Variables tab and run:

read -s DATABASE_URL && export DATABASE_URL && pnpm --filter "@kit/database" drizzle:migrate

This prompts you to paste the URL without displaying it in your terminal history.

Deployment Workflow

Once configured, Railway automatically deploys your application when you push to your connected branch:

1. Push changes to GitHub
2. Railway detects the push and starts a new deployment
3. The build runs with your configured settings
4. If successful, the new version goes live

Monitoring and Logs

Railway provides built-in monitoring:

• Deployments tab: View deployment history and status
• Logs tab: Real-time application logs
• Metrics tab: CPU, memory, and network usage
• Observability: Application performance monitoring

Troubleshooting

Database Connection Issues

If your application can't connect to the database:

1. Verify DATABASE_URL is correctly set using Railway's variable reference syntax
2. Check that your Postgres service is Online
3. Ensure you're using the private networking URL for internal connections

Build Failures

If your build fails:

1. Check the build logs in the Deployments tab
2. Verify all required environment variables are set
3. Ensure your package.json scripts are correct
4. For monorepos, verify the root directory setting

Storage Issues

If file uploads aren't working:

1. Verify all STORAGE_S3_* variables are correctly set
2. Check that the Storage Bucket service is active
3. Ensure your application code uses the correct S3 client configuration

Production Checklist

Before going live, ensure:

• [ ] All environment variables are set
• [ ] Database migrations have been run
• [ ] Billing webhooks are configured
• [ ] Custom domain is set up (if using)
• [ ] SSL is enabled (automatic with Railway)
• [ ] Application health checks are passing
• [ ] Monitoring and alerts are configured