Railway

Railway is a modern platform that makes it easy to deploy full-stack applications. It offers a generous free tier and seamless integration with GitHub.

Why Railway?

• Simple deployment - Connect your GitHub repo and deploy in minutes
• Free tier available - Great for testing and MVPs
• Automatic HTTPS - SSL certificates handled automatically
• Database included - Can provision PostgreSQL directly
• Environment variables - Easy management through the dashboard

Deploying to Railway

1. Create Railway Account

Sign up for a free account at railway.com.

2. Create New Project

1. Click "New Project" in the Railway dashboard
2. Select "Deploy from GitHub repo"
3. Connect your GitHub account if prompted
4. Select your repository

3. Configure Build Settings

Railway will auto-detect Next.js, but you can verify these settings:

• Build Command: npm run build
• Start Command: npm start
• Root Directory: / (root of your project)

4. Add Environment Variables

Add the deployment variables in the Railway dashboard. DATABASE_URL and BETTER_AUTH_SECRET are required. Add the Stripe and Resend variables when those features are enabled:

1. Go to your project → Variables tab
2. Add variables from your .env:

DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=...
NEXT_PUBLIC_SITE_URL=https://your-app.railway.app
STRIPE_SECRET_KEY=...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=...
STRIPE_WEBHOOK_SECRET=...
NEXT_PUBLIC_STRIPE_PRICE_PRO_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_PRO_YEARLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_LIFETIME=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_STARTER=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_PRO=price_...
RESEND_API_KEY=...
EMAIL_FROM=...

5. Provision Database (Optional)

Railway can provision a PostgreSQL database for you:

1. Click "New" → "Database" → "Add PostgreSQL"
2. Railway will automatically set the DATABASE_URL environment variable
3. Configure the pre-deploy migration command before releasing the web service

6. Deploy

Railway will automatically:

• Install dependencies
• Build your application
• Deploy to their infrastructure

Your app will be available at https://your-app.railway.app.

Database Migrations

Keep the build command as npm run build. In the web service settings, set the Pre-Deploy Command to:

npm run db:migrate

Railway runs this command in a separate container after the build and before the new deployment starts. The command receives the service environment variables, including DATABASE_URL. A non-zero exit stops the deployment.

For a controlled one-off migration, you can run the same script from a trusted local checkout with Railway's production variables:

railway run npm run db:migrate

Do not append migrations to npm run build and do not run them from every web replica at startup.

Custom Domain

To use a custom domain:

1. Go to Settings → Domains
2. Click "Add Domain"
3. Follow the DNS configuration instructions
4. Update NEXT_PUBLIC_SITE_URL to your custom domain

Environment-Specific Variables

Railway supports environment-specific variables:

• Production - Used for production deployments
• Preview - Used for preview deployments (from PRs)
• Development - Used for local development with Railway CLI

Monitoring

Railway provides:

• Logs - View real-time application logs
• Metrics - CPU, memory, and network usage
• Deployments - View deployment history

Troubleshooting

Build Failures

• Check build logs in the Railway dashboard
• Ensure all dependencies are in package.json
• Verify Node.js 22.21.1 is active, matching the version in package.json

Database Connection Issues

• Verify DATABASE_URL is set correctly
• Check if database requires SSL (add ?sslmode=require)
• Ensure database is accessible from Railway's IPs

Environment Variables Not Loading

• Verify variables are set in the correct environment
• Check for typos in variable names
• Redeploy after adding new variables