Deploy SaaS kit to Railway

Railway is an all-in-one deployment platform that provides hosting, PostgreSQL database, and S3-compatible storage in a single dashboard. Deploy your MakerKit application by connecting your GitHub repo, adding a Postgres database and storage bucket, configuring environment variables using Railway's reference syntax (${{Postgres.DATABASE_URL}}), and running migrations. Railway handles SSL, auto-deploys on push, and provides built-in monitoring.

This guide walks through the complete deployment process step by step.

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 or 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 Makerkit 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 minimum required environment variables that you need to set:

Plus your billing provider-specific variables as listed above.

Note: please make sure to add the environment variables that you retrieved from the previous steps to your Railway project so that you can successfully customize your deployment when you go live, otherwise the default values will be used (e.g. the ones in .env and .env.production). If you modified these values directly, it's okay as well.

Step 5: Run Database Migrations

After setting up your environment variables, run Prisma 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 && npx prisma migrate deploy --schema packages/database/src/prisma/schema.prisma

This command:

1. Prompts you to paste the URL without displaying it in your terminal history
2. Runs prisma migrate deploy to apply existing migrations

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

Pricing Considerations

Railway offers usage-based pricing. Key points for MakerKit deployments:

• Hobby plan ($5/month): Includes $5 of usage credits, suitable for development and low-traffic production apps. Apps may sleep after inactivity.
• Pro plan ($20/month): Includes $20 of usage credits, no sleep behavior, team features, and priority support.
• Usage costs: Billed per GB of RAM, vCPU hours, storage, and egress. A typical MakerKit app with light traffic costs $5-15/month in usage.

For current pricing, see Railway's pricing page.

Common Pitfalls

Watch out for these Railway-specific issues:

• Private vs public DATABASE_URL: Use the private networking URL (starts with ${{Postgres...}}) for internal connections. The public URL adds latency and egress costs.
• Storage bucket region is permanent: Choose the region carefully during creation—it cannot be changed afterward.
• Build minutes count toward usage: Large monorepo builds consume credits. Optimize your Dockerfile or use build caching.
• Hobby plan sleep behavior: Applications on the Hobby plan may sleep after 10 minutes of inactivity. Upgrade to Pro for always-on deployments.

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

Related Guides

• Environment Setup - Complete environment variable reference
• Deployment Overview - General deployment guidelines
• Docker - Self-host with Docker instead