Comprehensive Railway Module

A complete Railway platform skill covering the full lifecycle — from project creation through deployment, monitoring, and scaling. Comprehensive Railway Module serves as a one-stop reference for Railway CLI commands, configuration patterns, and operational best practices.

When to Use This Skill

Choose Comprehensive Railway Module when:

• You need a broad overview of Railway capabilities for a new project
• Working across multiple Railway concerns (deploy, database, domains, variables)
• Onboarding a team to Railway and need comprehensive reference material
• Troubleshooting cross-cutting Railway issues that span multiple services

Consider alternatives when:

• You have a specific narrow task (use the focused Railway skill for that area)
• You're using a different hosting platform entirely
• You need application-level architecture guidance (not Railway-specific)

Quick Start

Copy
claude "Set up a complete Railway project with API, worker, PostgreSQL, and Redis"

Copy
# 1. Create and initialize project
railway init --name my-app

# 2. Add databases
railway add --plugin postgresql
railway add --plugin redis

# 3. Deploy API service
cd api && railway link && railway up

# 4. Deploy worker service
cd ../worker && railway link && railway up

# 5. Wire variables
railway variables --set DATABASE_URL='${{Postgres.DATABASE_URL}}'
railway variables --set REDIS_URL='${{Redis.REDIS_URL}}'

# 6. Add domain
railway domain

# 7. Check status
railway status

Core Concepts

Railway CLI Command Reference

Command	Purpose	Common Flags
railway init	Create new project	--name
railway link	Link directory to project	—
railway up	Deploy current directory	--environment
railway down	Remove current deployment	—
railway status	Show project/service status	—
railway logs	View deployment logs	--tail, --deployment
railway domain	Add/manage domains	--set
railway variables	Manage environment variables	--set, --delete
railway add	Add plugins/databases	--plugin
railway connect	Open TCP proxy to service	postgresql, redis
railway list	List all projects	—
railway environment	Manage environments	create, use

Project Architecture Patterns

Copy
## Monolith
railway init → railway up
Single service, single deployment

## API + Database
railway init → railway add --plugin postgresql → railway up
One service with managed database

## Microservices
railway init → multiple `railway link` + `railway up` per service
Multiple services sharing databases via variable references

## Full Stack
Frontend (static) + API (dynamic) + Database + Cache
Each as a separate Railway service in one project

Configuration File

Copy
// railway.json
{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm ci && npm run build",
    "watchPatterns": ["src/**", "package.json"]
  },
  "deploy": {
    "startCommand": "node dist/server.js",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 30,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 5,
    "numReplicas": 1
  }
}

Configuration

Parameter	Description	Default
builder	NIXPACKS or DOCKERFILE	NIXPACKS
region	Deployment region	us-west1
healthcheckPath	HTTP health check endpoint	None
restartPolicyType	ON_FAILURE, ALWAYS, NEVER	ON_FAILURE
numReplicas	Service instance count	1

Best Practices

1. Structure projects by bounded context. Don't put unrelated services in the same Railway project. Group services that share databases and need to communicate — an API, its worker, and their shared PostgreSQL belong together. A separate marketing site does not.

2. Use railway.json for all deployment configuration. Avoid setting build and deploy commands through the dashboard alone. Committing railway.json to version control ensures consistent deployments and makes configuration reviewable in pull requests.

3. Implement health checks on every service. Railway uses health checks to determine when a deployment is ready for traffic. Without them, Railway routes traffic immediately after the process starts, potentially before your app is ready to handle requests.

4. Use private networking between services. Services in the same project can communicate via *.railway.internal hostnames. This is faster and more secure than routing through public domains. Set internal URLs using variable references.

5. Monitor costs proactively. Railway bills by resource usage. Set up usage alerts and review the billing dashboard weekly. A misconfigured service with high replica count or a runaway background job can generate unexpected charges.

Common Issues

Multiple services deploy but can't communicate. Verify they're in the same Railway project. Use private networking (*.railway.internal) for service-to-service calls instead of public domains. Check that the target service's port is correct — Railway services listen on process.env.PORT.

Deployment works locally but fails on Railway. Common differences: Railway uses Nixpacks (not your local Node/Python version), environment variables differ, and filesystem is ephemeral. Check railway logs for the specific error and verify all required environment variables are set.

Build times are slow. Railway rebuilds from scratch by default. Add a .railwayignore to exclude large files (test fixtures, documentation, local databases). For monorepos, set rootDirectory to the specific service directory to avoid building the entire repo.