Railway

Railway Platform - Skills Documentation

This documentation provides comprehensive information about Railway.com for LLM-based assistants to help users deploy, configure, and manage applications on the Railway platform.

Last Updated: 2026-01-23 Source: https://docs.railway.com

Documentation Structure

IMPORTANT: This skill includes modular documentation files. When you need detailed information, read the appropriate file using the Read tool:

• api.md - Complete GraphQL API reference with authentication, queries, mutations, and examples

  • Read this file when user asks about: API usage, GraphQL queries, mutations, authentication tokens, rate limits

• projects.md - Project structure, environment management, services, deployments, and team collaboration

  • Read this file when user asks about: project organization, environments, services, team management, templates

• frameworks.md - Framework-specific deployment guides for Node.js, Python, Go, Ruby, PHP, Java, Rust, and Elixir

  • Read this file when user asks about: deploying specific frameworks, framework configuration, language-specific setup

Usage: When a user question requires detailed information from these topics, use the Read tool to load the relevant file from .claude/skills/railway/ directory.

Table of Contents

1. Platform Overview
2. Core Concepts
3. Quick Start
4. CLI Reference
5. API Reference
6. Configuration
7. Networking & Domains
8. Databases & Volumes
9. Best Practices

Platform Overview

Railway is a modern cloud deployment platform that enables instant application deployment with zero-configuration builds and efficient scaling capabilities.

Key Features

• Zero-Configuration Deployments: Automatic language and framework detection
• Railpack Build System: Automatic code analysis and container image generation
• Private Networking: WireGuard mesh network for inter-service communication
• Multiple Deployment Sources: GitHub, Docker images, local directories
• Built-in Databases: PostgreSQL, MySQL, Redis, MongoDB templates
• Instant Scaling: Vertical autoscaling and horizontal replicas
• CLI & GraphQL API: Comprehensive automation support

Deployment Methods

1. GitHub Integration - Auto-deploy on git push
2. Docker Images - Public/private registries support
3. CLI Deployment - railway up command
4. Templates - One-click deployments from marketplace

Core Concepts

Projects

Projects are infrastructure containers that hold all application components. See projects.md for complete details.

Key features:

• Services - Individual application deployments
• Environments - Isolated deployment contexts (production, staging, etc.)
• Variables - Configuration management
• Activity Feed - Change tracking
• Collaboration - Team member access control

Services

Services are deployment targets for applications:

• Deploy from GitHub repos, Docker images, or local directories
• Each service gets its own configuration and variables
• Supports horizontal scaling with replicas
• Can attach one volume for persistent storage
• Automatic or manual deployment triggers

Environments

Isolated instances of project infrastructure:

• Default production environment included
• Create additional environments (staging, development)
• Each environment has separate variables and deployments
• PR Environments: Temporary instances for pull requests (auto-created/deleted)
• Environment syncing to propagate services between environments

Variables

Configuration management system:

• Service Variables: Scoped to individual services
• Shared Variables: Referenced across multiple services using ${{ shared.VAR }}
• Reference Variables: Cross-service references using ${{ SERVICE_NAME.VAR }}
• Sealed Variables: Enhanced security - values never visible in UI
• Platform Variables: Auto-provided like RAILWAY_PUBLIC_DOMAIN, RAILWAY_PRIVATE_DOMAIN

Quick Start

1. Install Railway CLI

# macOS/Linux
curl -fsSL https://railway.com/install.sh | sh

# Windows (PowerShell)
iwr https://railway.com/install.ps1 | iex

# npm
npm install -g @railway/cli

2. Login

railway login

3. Create a New Project

# Initialize new project
railway init

# Or link to existing project
railway link

4. Deploy

# Deploy from local directory
railway up

# Deploy with build logs
railway up --verbose

5. Manage Variables

# Set a variable
railway variables set KEY=value

# View all variables
railway variables

# Run command with variables
railway run npm start

CLI Reference

Project Management

Environment Operations

Service & Deployment

Development Tools

Configuration

Full CLI Documentation

railway --help              # Show all commands
railway <command> --help    # Command-specific help

API Reference

Railway provides a GraphQL API for programmatic access. See api.md for complete API documentation.

Quick Reference

Endpoint: https://backboard.railway.com/graphql/v2

Authentication:

curl --request POST \
  --url https://backboard.railway.com/graphql/v2 \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { me { name email } }"}'

Token Types:

1. Account Tokens - Personal resources
2. Team Tokens - Team resources (Pro feature)
3. Project Tokens - Single environment scope

Rate Limits:

• Free: 100 requests/hour
• Hobby: 1,000 requests/hour, 10 requests/second
• Pro: 10,000 requests/hour, 50 requests/second
• Enterprise: Custom limits

Common Operations:

• Get user info: query { me { name email } }
• List projects: query { workspace(workspaceId: "...") { projects { ... } } }
• Create service: mutation { serviceCreate(input: {...}) { id } }
• Fetch deployments: query { deployments(input: {...}) { ... } }
• Manage variables: mutation { variableUpsert(input: {...}) }

For complete API documentation, see api.md

Configuration

railway.json / railway.toml

Configure build and deployment behavior:

Basic railway.json

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

Basic railway.toml

[build]
builder = "NIXPACKS"
buildCommand = "npm run build"

[deploy]
startCommand = "npm start"
healthcheckPath = "/health"
healthcheckTimeout = 100
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10

Build Configuration

Builder Options:

• NIXPACKS (default) - Zero-config builds
• DOCKERFILE - Use project's Dockerfile

Build Settings:

{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm run build",
    "watchPatterns": ["src/**"],
    "dockerfilePath": "./Dockerfile"
  }
}

Deploy Configuration

Deploy Settings:

{
  "deploy": {
    "startCommand": "node server.js",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 100,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10,
    "numReplicas": 2,
    "region": "us-west1"
  }
}

Restart Policies:

• ON_FAILURE - Restart only on failure
• ALWAYS - Always restart
• NEVER - Never restart

nixpacks.toml

Override Nixpacks build behavior:

[phases.setup]
nixPkgs = ["nodejs-18_x", "python310"]

[phases.install]
cmds = ["npm install"]

[phases.build]
cmds = ["npm run build"]

[start]
cmd = "npm start"

Networking & Domains

Public Networking

Railway-Provided Domain:

• Automatically generated: <service-name>-production-<hash>.railway.app
• Enable in Service Settings → Networking → Public Networking

Custom Domains:

# Add custom domain
railway domain add example.com

# List domains
railway domain list

DNS Configuration:

• Add CNAME record: your-subdomain.example.com → <service>.railway.app
• Root domain: Add A/AAAA records provided by Railway

Private Networking

Automatic Service Discovery:

• All services in same project/environment communicate via private network
• Use service name as hostname: http://<service-name>:PORT
• Port defined by PORT environment variable

Private Networking Variables:

• RAILWAY_PRIVATE_DOMAIN - Private DNS name for service
• RAILWAY_TCP_PROXY_DOMAIN - TCP proxy domain (if enabled)
• RAILWAY_TCP_PROXY_PORT - TCP proxy port

Example:

// Service A connecting to Service B
const response = await fetch(`http://${process.env.BACKEND_PRIVATE_DOMAIN}:3000/api`);

TCP Proxy

For TCP/UDP protocols:

1. Enable in Service Settings → Networking → TCP Proxy
2. Use RAILWAY_TCP_PROXY_DOMAIN and RAILWAY_TCP_PROXY_PORT
3. Supports: databases, game servers, custom protocols

Databases & Volumes

Databases

Railway provides one-click database templates:

Available Databases:

• PostgreSQL
• MySQL
• MongoDB
• Redis
• Valkey

Adding a Database:

# Via CLI
railway add --database postgres

# Or via Dashboard: Add Service → Database → Select type

Connection Variables: Automatically provided after database creation:

• PostgreSQL: DATABASE_URL, PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE
• MySQL: MYSQL_URL, MYSQLHOST, MYSQLPORT, MYSQLUSER, MYSQLPASSWORD, MYSQLDATABASE
• MongoDB: MONGO_URL
• Redis: REDIS_URL

Connecting from Another Service:

# Reference database variable from another service
DATABASE_URL=${{ database-service.DATABASE_URL }}

Volumes

Persistent storage for services:

Creating a Volume:

1. Service Settings → Volumes → Add Volume
2. Specify mount path (e.g., /data)
3. Volume persists across deployments

Via CLI:

railway volume add --mount /data
railway volume list

Important:

• Each service can attach ONE volume
• Volumes are environment-specific
• Size limit: 50GB (Hobby), 100GB+ (Pro)
• NOT shared between services (use database/object storage for shared data)

Use Cases:

• User uploads
• Application data
• SQLite databases
• Logs and caches

Best Practices

Environment Variables

1. Use sealed variables for secrets (API keys, tokens)
2. Leverage shared variables to reduce duplication
3. Use reference variables for service URLs: ${{ api.RAILWAY_PRIVATE_DOMAIN }}
4. Import from .env files for easier migration
5. Never commit secrets to version control

Deployment

1. Configure health checks for zero-downtime deployments
2. Use PR environments for testing before merging
3. Set resource limits to control costs
4. Enable auto-sleep for development environments
5. Use multiple environments (dev, staging, production)

Networking

1. Use private networking for inter-service communication
2. Enable public networking only when needed
3. Configure custom domains for production
4. Set up health checks at /health endpoint
5. Use TCP proxy for non-HTTP protocols

Performance

1. Deploy in region closest to users
2. Use horizontal replicas for high availability
3. Configure cron jobs for scheduled tasks
4. Monitor resource usage in Metrics tab
5. Use volumes sparingly (prefer databases/object storage)

Security

1. Use sealed variables for sensitive data
2. Rotate secrets regularly
3. Restrict environment access (Enterprise)
4. Review activity feed for changes
5. Use least-privilege API tokens (project tokens vs account tokens)

Cost Optimization

1. Set usage limits per service
2. Enable auto-sleep for inactive services
3. Use appropriate instance sizes
4. Monitor spend in Usage tab
5. Clean up unused services and environments

Framework-Specific Guides

Railway supports automatic detection and deployment for many frameworks. See frameworks.md for complete framework guides.

Supported Frameworks

Node.js:

• Next.js
• Express.js
• Nest.js
• Remix
• Nuxt.js

Python:

• Django
• Flask
• FastAPI
• Streamlit

Go:

• Standard library
• Gin
• Echo
• Fiber

Ruby:

• Rails
• Sinatra

PHP:

• Laravel
• Symfony

Java:

• Spring Boot
• Quarkus

Rust:

• Axum
• Actix Web
• Rocket

Elixir:

• Phoenix

Quick Deploy Examples

Next.js:

{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "npm start"
  }
}

Django:

{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "python manage.py collectstatic --noinput"
  },
  "deploy": {
    "startCommand": "gunicorn myapp.wsgi"
  }
}

For complete framework documentation, see frameworks.md

Troubleshooting

Common Issues

Build Failures

Issue: Build fails with "command not found"

• Solution: Add required packages to nixpacks.toml or use custom Dockerfile

Issue: Build times out

• Solution: Optimize build process, increase timeout in settings, or use build cache

Deployment Issues

Issue: Service crashes immediately after deployment

• Solution: Check logs (railway logs), verify start command, check environment variables

Issue: Healthcheck fails

• Solution: Verify healthcheck path returns 200 status, increase timeout

Networking Issues

Issue: Can't connect to database

• Solution: Verify connection string, check if database service is running, use private domain

Issue: 502 Bad Gateway

• Solution: Ensure app listens on 0.0.0.0:$PORT, verify app is running

Debugging Commands

# View recent logs
railway logs

# View logs with follow
railway logs --follow

# Connect to service shell
railway ssh

# Connect to database
railway connect postgres

# Check service status
railway status

# View variables
railway variables

Getting Help

1. Documentation: https://docs.railway.com
2. Discord Community: Join Railway Discord
3. Status Page: https://status.railway.com
4. GitHub Issues: Report bugs at railway-app/railway

Additional Resources

• Main Documentation: https://docs.railway.com
• API Reference: See api.md
• Project Management: See projects.md
• Framework Guides: See frameworks.md
• GraphiQL Playground: https://railway.com/graphiql
• Railway Blog: https://railway.com/blog
• Railway Discord: https://discord.gg/railway

Last Updated: 2026-01-23 Documentation extracted from https://docs.railway.com