railway

Railway

Modern deployment platform with zero-config builds, instant databases, and automatic CI/CD.

Quick Start

# Install CLI
npm install -g @railway/cli

# Login
railway login

# Initialize project
railway init

# Deploy
railway up

# Get deployment URL
railway domain

Deployment Methods

From GitHub

1. Connect GitHub account at railway.app
2. Select repository
3. Railway auto-detects framework
4. Automatic deploys on push

From CLI

# Link to existing project
railway link

# Deploy current directory
railway up

# Deploy with logs
railway up --detach

From Template

Use Railway's template gallery for pre-configured stacks.

Project Configuration

railway.json

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 300,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}

Environment Detection

Railway automatically detects:

• Node.js - package.json
• Python - requirements.txt, Pipfile
• Go - go.mod
• Ruby - Gemfile
• Rust - Cargo.toml
• Docker - Dockerfile

Environment Variables

CLI

# Set variable
railway variables set API_KEY=secret

# Set multiple
railway variables set API_KEY=secret DB_URL=postgres://...

# List variables
railway variables

# Delete variable
railway variables delete API_KEY

Dashboard

1. Select service
2. Variables tab
3. Add key-value pairs
4. Redeploy for changes

Reference Variables

# Reference other services
DATABASE_URL=${{Postgres.DATABASE_URL}}
REDIS_URL=${{Redis.REDIS_URL}}

Databases

Provision Database

# Add PostgreSQL
railway add postgresql

# Add MySQL
railway add mysql

# Add Redis
railway add redis

# Add MongoDB
railway add mongodb

Connection Strings

Automatically available as environment variables:

Database Management

# Connect to database shell
railway connect

# Run database migrations
railway run npm run migrate

Node.js Deployment

package.json

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "engines": {
    "node": "20"
  }
}

Express/Fastify

// Use PORT from environment
const port = process.env.PORT || 3000;
app.listen(port, '0.0.0.0', () => {
  console.log(`Server running on port ${port}`);
});

Next.js Deployment

{
  "scripts": {
    "build": "next build",
    "start": "next start -p $PORT"
  }
}

Railway automatically:

• Detects Next.js
• Runs build
• Starts with correct PORT

Dockerfile Deployment

Basic Dockerfile

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000
CMD ["npm", "start"]

Multi-stage Build

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

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

Custom Domains

Add Domain

railway domain
# Returns: your-app.up.railway.app

# Or add custom domain in dashboard
# 1. Service settings > Domains
# 2. Add custom domain
# 3. Configure DNS (CNAME to railway.app)

DNS Configuration

CNAME your-app.up.railway.app

Scaling

Horizontal Scaling

Configure in dashboard:

• Instance count
• Resource limits (CPU, RAM)

Auto-scaling

Railway Pro plans support auto-scaling based on:

• CPU usage
• Memory usage
• Request count

Healthchecks

Configuration

{
  "deploy": {
    "healthcheckPath": "/health",
    "healthcheckTimeout": 300
  }
}

Endpoint

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

Logs & Monitoring

CLI

# Stream logs
railway logs

# Follow logs
railway logs -f

# Specific service
railway logs --service my-service

Dashboard

Real-time logs, metrics, and deployment history in the Railway dashboard.

Preview Environments

Pull Request Previews

Enable in project settings:

1. Settings > Environments
2. Enable PR environments
3. Each PR gets isolated environment

Environment Variables per Environment

# Production
railway variables set --environment production API_URL=https://api.example.com

# Staging
railway variables set --environment staging API_URL=https://staging-api.example.com

CLI Commands

# Project management
railway init          # Initialize new project
railway link          # Link to existing project
railway unlink        # Unlink project

# Deployment
railway up            # Deploy current directory
railway up --detach   # Deploy without logs

# Variables
railway variables     # List variables
railway variables set KEY=value

# Database
railway add postgresql  # Add database
railway connect        # Connect to database

# Logs & shell
railway logs          # View logs
railway run <cmd>     # Run command in Railway env
railway shell         # Interactive shell

# Domains
railway domain        # Get/create domain

Monorepo Support

Root Configuration

{
  "build": {
    "rootDirectory": "apps/api"
  }
}

Multiple Services

Deploy each app as separate Railway service, all in same project.

See references/configuration.md for complete configuration options.