Railway Deployment Knowledge Base

Railway Platform Overview

Railway is a modern PaaS that deploys applications from Git repositories with automatic builds and deployments.

Key Concepts

• Project: Container for all services and environments
• Service: Individual deployable unit (backend, frontend, database)
• Environment: Isolated deployment target (staging, production)
• Deployment: Specific version of code running in an environment

Auto-Deploy Configuration

Railway automatically deploys when you push to configured branches:

Setting Up Auto-Deploy

1. Go to Railway Dashboard → Project → Settings
2. Under "Deployments", configure:
   • Source branch for each environment
   • Build command (auto-detected usually)
   • Start command

Project Structure Patterns

Monorepo (Multiple Services)

project/
├── frontend/
│   ├── Dockerfile
│   └── package.json
├── backend/
│   ├── Dockerfile
│   └── requirements.txt
└── railway.json

Single Service

project/
├── Dockerfile (or detected runtime)
├── package.json / requirements.txt
└── railway.json (optional)

railway.json Configuration

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "DOCKERFILE",
    "dockerfilePath": "Dockerfile"
  },
  "deploy": {
    "numReplicas": 1,
    "healthcheckPath": "/health",
    "healthcheckTimeout": 300,
    "restartPolicyType": "ON_FAILURE"
  }
}

Dockerfile Best Practices for Railway

# Multi-stage build for smaller images
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]

Python Example

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Environment Variables

Railway-Provided Variables

RAILWAY_ENVIRONMENT=production
RAILWAY_SERVICE_NAME=backend
RAILWAY_PROJECT_ID=xxx
PORT=<assigned port>

Common Application Variables

ENVIRONMENT=production
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
API_KEY=xxx
CORS_ORIGINS=https://myapp.com

Health Checks

Railway performs health checks to ensure your app is running:

# FastAPI example
@app.get("/health")
async def health_check():
    return {"status": "healthy"}

// Express example
app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

Networking

Internal Networking

Services within the same project can communicate via internal DNS:

http://backend.railway.internal:8000

External Access

• Railway provides *.up.railway.app domains
• Custom domains can be configured in settings

Logging

Viewing Logs

# Via CLI
railway logs
railway logs --environment production
railway logs -n 100  # Last 100 lines

# Via Dashboard
Project → Service → Logs tab

Structured Logging Best Practices

import logging
import json

logging.basicConfig(
    format='%(message)s',
    level=logging.INFO
)

def log_json(level, message, **kwargs):
    log_entry = {"message": message, **kwargs}
    getattr(logging, level)(json.dumps(log_entry))

Scaling

Horizontal Scaling

// railway.json
{
  "deploy": {
    "numReplicas": 3
  }
}

Resource Limits

Configure in Railway Dashboard:

• Memory limit
• CPU limit
• Instance count

Database Connections

Connection Pooling

For production, use connection pooling:

# SQLAlchemy with pool
engine = create_engine(
    DATABASE_URL,
    pool_size=5,
    max_overflow=10,
    pool_pre_ping=True
)

Deployment Monitoring

Key Metrics to Watch

• Build time
• Deployment status
• Memory usage
• CPU usage
• Response times
• Error rates

Alerts

Configure alerts in Railway Dashboard for:

• Deployment failures
• High memory usage
• Service crashes

Rollback Procedures

Quick Rollback

1. Go to Railway Dashboard
2. Select service → Deployments
3. Click "Rollback" on previous healthy deployment

Git-Based Rollback

git revert HEAD
git push origin main
# Railway auto-deploys reverted code

Cost Optimization

• Use multi-stage Docker builds (smaller images)
• Set appropriate resource limits
• Use sleep/hibernation for staging if not needed 24/7
• Monitor usage in Railway Dashboard

Troubleshooting