railway

name	railway
description	Railway deployment and infrastructure management skill. This skill should be used when deploying applications to Railway, managing Railway services, checking deployment status, viewing logs, configuring environment variables, or troubleshooting Railway deployments.

Railway Deployment Skill

This skill provides workflows and knowledge for deploying and managing applications on Railway.

Overview

Railway is a modern cloud platform for deploying applications. This skill integrates with the Railway MCP tools to provide deployment, monitoring, and management capabilities.

Prerequisites

Before using Railway MCP tools:

1. Install Railway CLI: https://docs.railway.com/guides/cli
2. Authenticate: Run railway login in terminal
3. Link project: Run railway link in the project directory

Available MCP Tools

Tool	Purpose
check-railway-status	Verify CLI is installed and authenticated
list-projects	List all Railway projects for the account
list-services	List services in the linked project
list-deployments	List deployments with status and metadata
list-variables	Show environment variables for a service
set-variables	Set environment variables
get-logs	Get build or deployment logs
deploy	Upload and deploy from local directory
generate-domain	Generate a Railway domain for the service
link-service	Link to a specific Railway service
link-environment	Link to a specific Railway environment
create-environment	Create a new Railway environment
create-project-and-link	Create and link a new Railway project
deploy-template	Search and deploy Railway templates

Deployment Workflow

First-Time Setup

1. Verify CLI authentication:

   Use check-railway-status to confirm Railway CLI is logged in
   

2. Link project (if not linked):

   • User runs railway login in terminal
   • User runs railway link in the project directory
   • Or use create-project-and-link for new projects

3. Configure root directory (for monorepos):

   • If app is in a subdirectory (e.g., web/, app/, frontend/), configure in Railway Dashboard:
   • Service → Settings → Source → Root Directory

Deployment Process

1. Check current status:

   list-deployments with json=true to see recent deployment statuses
   

2. If deployment failed, check logs:

   get-logs with logType="build" and the failed deploymentId
   

3. Common build failures:

   • Missing root directory configuration (monorepos)
   • Syntax errors in code
   • Missing dependencies
   • Invalid environment variables

4. Deploy changes:

   • Push to GitHub (auto-deploy if connected)
   • Or use deploy tool for manual deployment

Environment Variables

1. View current variables:

   list-variables with json=true
   

2. Set new variables:

   set-variables with variables array like ["KEY=value", "KEY2=value2"]
   

3. Common patterns:

   • NEXT_PUBLIC_* - Next.js client-safe public variables
   • DATABASE_URL - Database connection string
   • *_API_KEY - API keys (server-side only)

Domain Configuration

1. Generate Railway domain:

   generate-domain to get a *.up.railway.app domain
   

2. Custom domains:

   • Configure in Railway Dashboard: Service → Settings → Public Networking
   • Add CNAME record at DNS provider pointing to Railway domain

Framework-Specific Configuration

Next.js

railway.toml (place in app root):

[build]
builder = "nixpacks"

[deploy]
startCommand = "npm run start"
healthcheckPath = "/"
healthcheckTimeout = 300
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10

NestJS + Prisma

railway.toml:

[build]
builder = "nixpacks"
buildCommand = "npx prisma generate && npx prisma migrate deploy && npm run build"

[deploy]
startCommand = "node dist/main.js"
healthcheckPath = "/health"
healthcheckTimeout = 300
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10

Node.js/Express

railway.toml:

[build]
builder = "nixpacks"

[deploy]
startCommand = "node server.js"
healthcheckPath = "/health"

Python/FastAPI

railway.toml:

[build]
builder = "nixpacks"

[deploy]
startCommand = "uvicorn main:app --host 0.0.0.0 --port $PORT"
healthcheckPath = "/health"

Python/Django

railway.toml:

[build]
builder = "nixpacks"
buildCommand = "python manage.py collectstatic --noinput"

[deploy]
startCommand = "gunicorn myproject.wsgi --bind 0.0.0.0:$PORT"
healthcheckPath = "/health"

Troubleshooting

"Railpack could not determine how to build"

Cause: Root directory not set for monorepo structures.

Fix: Set Root Directory in Railway Dashboard → Service → Settings → Source.

Build Syntax Errors

Cause: Code pushed with syntax errors.

Fix:

1. Check build logs: get-logs with logType="build"
2. Fix the error locally
3. Push the fix to trigger new deployment

Missing Environment Variables

Cause: Required environment variables not set.

Fix:

1. Check current vars: list-variables
2. Set missing vars: set-variables

Domain Not Working

Cause: DNS not configured or not propagated.

Fix:

1. Verify CNAME record points to Railway domain
2. Wait for DNS propagation (up to 72 hours)
3. Check Railway Dashboard for verification status

Port Configuration

Railway automatically provides a PORT environment variable. Ensure your application listens on 0.0.0.0:$PORT.

Node.js:

const port = process.env.PORT || 3000;
app.listen(port, '0.0.0.0', () => console.log(`Listening on ${port}`));

Python:

import os
port = int(os.environ.get("PORT", 8000))

Custom Domain Setup by Provider

Cloudflare (Recommended)

1. Add CNAME record: @ → Railway domain
2. Enable Cloudflare proxy (orange cloud)
3. Set SSL/TLS to "Full" (not Full Strict)
4. Enable Universal SSL

GoDaddy / Providers Without CNAME Flattening

GoDaddy and some providers don't support CNAME flattening for root domains. Options:

1. Use subdomain: www.domain.com or app.domain.com with CNAME record
2. Migrate DNS to Cloudflare: Change nameservers in registrar
3. Use forwarding: Forward root to www subdomain

Standard CNAME Setup

For subdomains on any provider:

1. In Railway: Add custom domain (e.g., app.yourdomain.com)
2. Copy the CNAME target (e.g., abc123.up.railway.app)
3. In DNS: Add CNAME record pointing subdomain to Railway target
4. Wait for verification in Railway Dashboard

Multi-Service Projects (Full Stack)

For projects with frontend + backend + database:

Architecture

Railway Project
├── Frontend Service (Next.js) → goteammate/nextjs-template
├── Backend Service (NestJS) → goteammate/nestjs-template
└── PostgreSQL Database → Railway Postgres template

Setup via MCP Tools

1. create-project-and-link — Create the Railway project
2. deploy-template with "PostgreSQL" — Add database
3. Connect GitHub repos for frontend and backend services
4. set-variables — Wire DATABASE_URL, NEXT_PUBLIC_API_URL, FRONTEND_URL
5. generate-domain — Create domains for each service

Auto-Wired Variables

Variable	Service	Source
DATABASE_URL	Backend	Railway Postgres reference
PORT	Both	Railway auto-provides
FRONTEND_URL	Backend	Frontend Railway domain
NEXT_PUBLIC_API_URL	Frontend	Backend Railway domain
NEXT_PUBLIC_APP_URL	Frontend	Frontend Railway domain

Bootstrap Shortcut

Use the new-project skill in teammate-ops to automate the entire multi-service setup from a single conversation.

Project Configuration Template

After importing this skill, add project-specific details to your local skill copy:

## Project Configuration

- **Project Name:** [Your Project]
- **Project ID:** [from Railway Dashboard]
- **Environment ID:** [from Railway Dashboard]
- **Service ID:** [from Railway Dashboard]
- **Root Directory:** [e.g., web/, app/, or /]
- **Custom Domain:** [if configured]
- **Dashboard URL:** https://railway.com/project/[project-id]

### Required Environment Variables

| Variable | Description |
|----------|-------------|
| ... | ... |