Railway Deployment

Prerequisites

Railway account (sign up free)
Railway CLI (optional)
GitHub account for automatic deployments

Architecture Overview

Railway provides a simple deployment platform with:

Automatic builds from GitHub repositories
Managed PostgreSQL database
Managed Redis cache
Automatic SSL certificates
Environment variables management
Zero configuration deployments

Quick Start (Web Dashboard)

1. Create New Project

Go to Railway Dashboard
Click "New Project"
Select "Deploy from GitHub repo"
Authorize Railway to access your repositories
Select your Jiffoo Mall repository

2. Add Database Services

Add PostgreSQL

Click "+ New" in your project
Select "Database" → "Add PostgreSQL"
Railway automatically provisions a PostgreSQL instance
Connection details are available in the service variables

Add Redis

Click "+ New" in your project
Select "Database" → "Add Redis"
Railway automatically provisions a Redis instance
Connection details are available in the service variables

3. Deploy Services

Railway will automatically detect your monorepo structure if configured correctly. For Jiffoo Mall:

Deploy API Service

Click "+ New" → "GitHub Repo"
Select your repository
Configure the service:
- Name: jiffoo-api
- Root Directory: apps/api (or leave empty if using workspace)
- Build Command: cd apps/api && npm install && npm run build
- Start Command: cd apps/api && npm start
- Port: 3001

Deploy Shop Service

Click "+ New" → "GitHub Repo"
Select your repository
Configure the service:
- Name: jiffoo-shop
- Root Directory: apps/shop
- Build Command: cd apps/shop && npm install && npm run build
- Start Command: cd apps/shop && npm start
- Port: 3000

Deploy Admin Service

Click "+ New" → "GitHub Repo"
Select your repository
Configure the service:
- Name: jiffoo-admin
- Root Directory: apps/admin
- Build Command: cd apps/admin && npm install && npm run build
- Start Command: cd apps/admin && npm start
- Port: 3003

Quick Start (Railway CLI)

1. Install Railway CLI

# macOS/Linux
brew install railway

# Windows
scoop install railway

# npm
npm install -g @railway/cli

railway login

3. Initialize Project

# Create new project
railway init

# Link to existing project
railway link

4. Add Services

# Add PostgreSQL
railway add --database postgresql

# Add Redis
railway add --database redis

5. Deploy Services

# Deploy API
cd apps/api
railway up

# Deploy Shop
cd ../shop
railway up

# Deploy Admin
cd ../admin
railway up

Configuration

Environment Variables

Railway automatically injects database connection strings. Configure additional variables:

API Service Variables

# Using CLI
railway variables set NODE_ENV=production
railway variables set PORT=3001
railway variables set JWT_SECRET=your-secret-key

# Or set in Railway Dashboard > Service > Variables

Railway automatically provides:

DATABASE_URL - PostgreSQL connection string
REDIS_URL - Redis connection string

Shop Service Variables

railway variables set NEXT_PUBLIC_API_URL=https://jiffoo-api.up.railway.app
railway variables set PORT=3000

Admin Service Variables

railway variables set NEXT_PUBLIC_API_URL=https://jiffoo-api.up.railway.app
railway variables set PORT=3003

Using railway.json

Create railway.json in each service directory for configuration:

apps/api/railway.json

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm install && npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

apps/shop/railway.json

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm install && npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

Monorepo Configuration

For turborepo monorepos, Railway needs special configuration:

Option 1: Root-Level Deployment

Create railway.toml in the project root:

[build]
builder = "nixpacks"
buildCommand = "npm install && npx turbo run build --filter=api"

[deploy]
startCommand = "cd apps/api && npm start"

Option 2: Service-Specific Configuration

Use Railway's service settings to specify:

Root Directory: Leave empty or set to /
Build Command: npx turbo run build --filter=api
Start Command: cd apps/api && npm start

Database Management

Run Migrations

# Using Railway CLI
railway run npm run migrate

# Or connect to the database directly
railway connect postgres

# Then run migrations manually
npm run migrate

Seed Database

railway run npm run seed

Database Backups

Railway automatically backs up PostgreSQL databases. To create manual backups:

Go to Database Service in Railway Dashboard
Click "Backups" tab
Click "Create Backup"

Restore from Backup

# List backups
railway backups list

# Restore from backup
railway backups restore <backup-id>

Custom Domains

Add Custom Domain

Go to your service in Railway Dashboard
Click "Settings" → "Domains"
Click "Add Domain"
Enter your custom domain (e.g., shop.yourdomain.com)
Add the provided CNAME record to your DNS provider:
```
CNAME shop.yourdomain.com -> <railway-domain>
```

Railway automatically provisions SSL certificates via Let's Encrypt.

Multiple Domains

You can add multiple domains per service:

shop.yourdomain.com -> Shop Service
admin.yourdomain.com -> Admin Service
api.yourdomain.com -> API Service

Monitoring and Logs

View Logs

# Using CLI
railway logs

# Follow logs in real-time
railway logs --follow

# Filter by service
railway logs --service jiffoo-api

Metrics Dashboard

Railway provides built-in metrics:

Go to your service in Railway Dashboard
Click "Metrics" tab
View CPU, Memory, Network usage

Webhooks

Set up webhooks for deployment notifications:

Go to Project Settings → Webhooks
Add webhook URL
Select events: deployment.success, deployment.failed

Scaling

Vertical Scaling

Railway automatically scales vertically based on resource usage:

Memory: Up to 8GB per service
CPU: Shared CPU resources

Horizontal Scaling

Railway currently supports single instance per service. For high availability:

Use Railway's Teams Plan for better resources
Implement application-level caching
Use CDN for static assets

CI/CD Integration

Railway automatically deploys on git push when connected to GitHub.

Manual Deployments

# Deploy current branch
railway up

# Deploy specific environment
railway up --environment production

Deployment Triggers

Configure deployment triggers in Railway Dashboard:

Auto-deploy: Deploy on every push (default)
Manual deploy: Require manual trigger
Branch-specific: Only deploy specific branches

GitHub Actions Integration

Create .github/workflows/railway-preview.yml:

name: Railway Preview

on:
  pull_request:
    branches: [main]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Railway CLI
        run: npm install -g @railway/cli

      - name: Deploy to Railway PR environment
        run: railway up --environment pr-${{ github.event.pull_request.number }}
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

Environment Management

Railway supports multiple environments per project:

Create Environment

# Using CLI
railway environment create staging

# Switch environment
railway environment use staging

Environment Variables per Environment

Each environment can have different variables:

# Production
railway environment use production
railway variables set DATABASE_URL=prod-db-url

# Staging
railway environment use staging
railway variables set DATABASE_URL=staging-db-url

Cost Optimization

Railway Pricing Tiers

Hobby Plan: $5/month, 512MB RAM, $0.20/GB egress
Pro Plan: $20/month, 8GB RAM, $0.10/GB egress
Team Plan: Custom pricing

Optimization Tips

Remove unused services to reduce costs
Use caching to reduce database queries
Optimize images to reduce bandwidth
Use Railway's CDN for static assets
Scale down non-production environments

Troubleshooting

Build Failures

# Check build logs
railway logs --build

# Common issues:
# - Missing dependencies: Add to package.json
# - Build command fails: Check railway.json
# - Out of memory: Upgrade to Pro plan

Service Not Starting

# Check service logs
railway logs --service jiffoo-api

# Verify environment variables
railway variables

# Check health endpoint
curl https://jiffoo-api.up.railway.app/health

Database Connection Issues

# Verify database is running
railway status

# Check DATABASE_URL variable
railway variables get DATABASE_URL

# Test connection
railway connect postgres

Performance Issues

Check metrics in Railway Dashboard
Upgrade to Pro plan for more resources
Optimize database queries using indexes
Enable Redis caching for frequently accessed data
Use CDN for static assets

Migration from Other Platforms

From Heroku

Railway is Heroku-compatible:

Export Heroku config vars:
```
heroku config -s > .env
```
Import to Railway:
```
railway variables set $(cat .env)
```
Update database connection strings to Railway's format

From Vercel

Deploy backend services to Railway
Keep frontend on Vercel or migrate to Railway
Update API URLs in Vercel environment variables

Security Best Practices

Use environment variables for all secrets
Enable private networking between services (Pro plan)
Restrict database access to Railway internal network
Regular updates - Railway auto-updates base images
Use Railway's secret scanning to detect leaked credentials
Enable 2FA on your Railway account

Advanced Features

Private Networking

Railway Pro plan includes private networking:

# Services can communicate via internal DNS
# Instead of: https://jiffoo-api.up.railway.app
# Use: http://jiffoo-api.railway.internal:3001

TCP Proxying

For services that need TCP connections:

Enable TCP proxy in service settings
Railway provides a TCP endpoint
Connect using the provided host:port

Cron Jobs

Deploy background jobs using Railway's CLI:

# Schedule a cron job
railway run --cron "0 0 * * *" npm run cleanup

Railway Deployment

On this page