Skip to main content
Railway provides a simple, template-based deployment for Openfront with managed PostgreSQL database and automatic deployments.

​
One-Click Deployment

Click the button below to deploy Openfront to Railway: Deploy on Railway This will:
  • Create a new Railway project
  • Provision a managed PostgreSQL database
  • Configure environment variables automatically
  • Deploy Openfront with optimized build settings

​
Railway Template Configuration

Openfront includes a railway.toml configuration file that optimizes the deployment: 
[build]
buildCommand = "keystone build --no-ui && next build"

[deploy]
startCommand = "npm run migrate && next start"
Railway can’t access the database during the build phase, so migrations are run at startup instead of during build.

​
Deployment Process

1

Click Deploy Button

Click the “Deploy on Railway” button above to start deployment
2

Log In to Railway

Sign in with GitHub or create a Railway account
3

Configure Project

Railway will automatically:
  • Create a new project
  • Provision PostgreSQL database
  • Set up environment variables
  • Connect the GitHub repository
4

Set Session Secret

Add the required SESSION_SECRET environment variable (see below)
5

Deploy

Railway will automatically build and deploy your application
6

Access Application

Once deployed, click the generated URL to access your Openfront instance

​
Environment Variables

​
Automatic Configuration

Railway automatically configures:
  • DATABASE_URL - PostgreSQL connection string
  • PORT - Application port
  • Service networking and URLs

​
Required Variables

You must manually add:

​
SESSION_SECRET

SESSION_SECRET="your-very-long-session-secret-key-minimum-32-characters"
Generate a cryptographically secure session secret:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
To add environment variables in Railway:
  1. Select your Openfront service
  2. Go to the “Variables” tab
  3. Click “New Variable”
  4. Add SESSION_SECRET with your generated value
  5. Save and redeploy

​
Optional Variables

Add these for additional functionality:

​
Payment Providers

Stripe: 
STRIPE_SECRET_KEY="sk_test_51..."
STRIPE_WEBHOOK_SECRET="whsec_..."
PayPal: 
PAYPAL_CLIENT_ID="your-paypal-client-id"
PAYPAL_CLIENT_SECRET="your-paypal-client-secret"

​
Shipping Provider

SHIPPO_API_KEY="shippo_test_..."

​
File Storage (S3)

S3_BUCKET_NAME="your-bucket-name"
S3_REGION="us-east-1"
S3_ACCESS_KEY_ID="your-access-key"
S3_SECRET_ACCESS_KEY="your-secret-key"
Railway provides persistent volumes, but S3 storage is recommended for production deployments for better performance and CDN integration.

​
Email Configuration

SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="[email protected]"
SMTP_PASS="your-app-password"
FROM_EMAIL="[email protected]"

​
Database Configuration

​
Managed PostgreSQL

Railway automatically provisions a PostgreSQL database with:
  • Automatic backups
  • Connection pooling
  • Monitoring and metrics
  • Automatic scaling
The DATABASE_URL is automatically injected as an environment variable.

​
Database Migrations

Unlike standard deployments, Railway runs migrations at startup: 
npm run migrate && next start
This is because Railway’s build environment doesn’t have database access. The first startup may take 30-60 seconds while migrations run.
During the first deployment, the application will be unavailable until migrations complete. Subsequent deployments with no new migrations will start faster.

​
External Database

To use an external PostgreSQL database:
  1. Remove the Railway PostgreSQL service
  2. Add DATABASE_URL environment variable:
DATABASE_URL="postgresql://username:password@host:5432/database"

​
Build Process

​
Build Command

The Railway template uses a custom build command: 
keystone build --no-ui && next build
This:
  1. Generates KeystoneJS schema and GraphQL types
  2. Builds Next.js application for production
  3. Skips Keystone Admin UI (not needed)

​
Start Command

The start command runs migrations before starting: 
npm run migrate && next start

​
Build Time

Expect build times of 4-6 minutes:
  • Dependency installation: 1-2 minutes
  • KeystoneJS build: 30-60 seconds
  • Next.js build: 2-3 minutes
  • Initial startup (with migrations): 30-60 seconds

​
Railway-Specific Features

​
Automatic Deployments

Railway automatically deploys when you:
  • Push to the connected GitHub repository
  • Update environment variables
  • Manually trigger a deployment

​
Preview Environments

Create preview environments for:
  • Pull requests
  • Feature branches
  • Testing new features
Each preview gets its own database and URL.

​
Monitoring and Logs

Railway provides:
  • Real-time logs
  • CPU and memory metrics
  • Network traffic monitoring
  • Database performance metrics

​
Custom Domains

Add custom domains:
  1. Go to project settings
  2. Click “Domains”
  3. Add your domain
  4. Configure DNS records
  5. SSL certificates are automatic

​
Volume Storage

​
Persistent Storage

Railway provides persistent volumes for file storage:
  1. Go to your service settings
  2. Click “Volumes”
  3. Create a new volume
  4. Mount at /app/public/uploads
Volumes persist between deployments but are limited to a single region. For multi-region deployments, use S3 storage.

​
Post-Deployment Setup

1

Access Your Application

Click the Railway-generated URL to access Openfront
2

Wait for Initial Migration

The first startup may take 30-60 seconds while database migrations run
3

Create Admin User

Navigate to /dashboard/init to create your first admin user
4

Run Store Onboarding

Complete the onboarding process to set up your store
5

Configure Integrations

Add payment and shipping provider credentials

​
Webhook Configuration

​
Stripe Webhooks

  1. Go to Stripe Dashboard > Developers > Webhooks
  2. Add endpoint: https://your-railway-app.railway.app/api/webhooks/stripe
  3. Select events:
    • payment_intent.succeeded
    • payment_intent.payment_failed
    • charge.refunded
  4. Copy webhook signing secret to Railway environment variables

​
PayPal Webhooks

  1. Go to PayPal Developer Dashboard
  2. Add webhook: https://your-railway-app.railway.app/api/webhooks/paypal
  3. Select event types:
    • PAYMENT.CAPTURE.COMPLETED
    • PAYMENT.CAPTURE.DENIED

​
Troubleshooting

​
Deployment Failures

Build timeout:
  • Railway has a 15-minute build timeout
  • If builds consistently timeout, check for network issues
  • Consider optimizing dependencies
Migration errors:
  • Check logs during startup
  • Verify database is accessible
  • Ensure DATABASE_URL is correctly set

​
Runtime Issues

Application crashes at startup:
  • Check logs for migration errors
  • Verify all required environment variables are set
  • Check database connection string
Slow startup:
  • First startup with migrations takes 30-60 seconds
  • Subsequent startups should be faster
  • Check database performance
File upload issues:
  • Configure persistent volume or S3 storage
  • Check volume mount path
  • Verify write permissions

​
Database Issues

Connection pool errors:
  • Railway provides connection pooling by default
  • Check number of concurrent connections
  • Consider upgrading database plan
Out of space:
  • Check Railway database storage limits
  • Clean up old data
  • Upgrade to larger plan

​
Scaling on Railway

​
Vertical Scaling

Increase resources for your service:
  • More CPU for better performance
  • More memory for larger datasets
  • Adjust in service settings

​
Database Scaling

Scale your PostgreSQL database:
  • Storage: Increase as needed
  • Memory: Better query performance
  • CPU: Handle more concurrent queries

​
Horizontal Scaling

Horizontal scaling (multiple instances) requires:
  • S3 file storage (not local volumes)
  • External session store
  • Load balancer configuration

​
Cost Optimization

​
Railway Pricing

  • Hobby Plan: $5/month credit (limited resources)
  • Pro Plan: Usage-based pricing
  • Enterprise: Custom pricing

​
Cost-Saving Tips

  1. Use sleep mode: Enable for development environments
  2. Optimize builds: Cache dependencies to reduce build time
  3. Monitor usage: Use Railway’s cost estimation tools
  4. Right-size resources: Don’t over-provision

​
Monitoring and Maintenance

​
Health Checks

Railway automatically monitors:
  • HTTP health checks
  • Service availability
  • Resource usage

​
Backups

Railway PostgreSQL includes:
  • Automatic daily backups
  • Point-in-time recovery
  • Manual backup triggers
For production, implement additional backup strategies for critical data.

​
Updates and Maintenance

  1. Test updates in preview environment
  2. Monitor logs during deployment
  3. Keep dependencies updated
  4. Regular database maintenance

​
Advanced Configuration

​
Custom Build Settings

Modify railway.toml for custom configuration: 
[build]
buildCommand = "keystone build --no-ui && next build"
watchPatterns = ["**/*.ts", "**/*.tsx"]

[deploy]
startCommand = "npm run migrate && next start"
restartPolicyType = "on-failure"
restartPolicyMaxRetries = 3

​
Health Check Endpoint

Configure Railway to monitor: 
HEALTHCHECK_PATH="/api/health"

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us