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:

Install Railway CLI: https://docs.railway.com/guides/cli
Authenticate: Run railway login in terminal
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

Verify CLI authentication:

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

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
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

Check current status:

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

If deployment failed, check logs:

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

Common build failures:
- Missing root directory configuration (monorepos)
- Syntax errors in code
- Missing dependencies
- Invalid environment variables
Deploy changes:
- Push to GitHub (auto-deploy if connected)
- Or use deploy tool for manual deployment

Environment Variables

View current variables:
```
list-variables with json=true
```

Set new variables:

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

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

Domain Configuration

Generate Railway domain:

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

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:

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

Missing Environment Variables

Cause: Required environment variables not set.

Fix:

Check current vars: list-variables
Set missing vars: set-variables

Domain Not Working

Cause: DNS not configured or not propagated.

Fix:

Verify CNAME record points to Railway domain
Wait for DNS propagation (up to 72 hours)
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)

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

GoDaddy / Providers Without CNAME Flattening

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

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

Standard CNAME Setup

For subdomains on any provider:

In Railway: Add custom domain (e.g., app.yourdomain.com)
Copy the CNAME target (e.g., abc123.up.railway.app)
In DNS: Add CNAME record pointing subdomain to Railway target
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

create-project-and-link — Create the Railway project
deploy-template with "PostgreSQL" — Add database
Connect GitHub repos for frontend and backend services
set-variables — Wire DATABASE_URL, NEXT_PUBLIC_API_URL, FRONTEND_URL
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 |
|----------|-------------|
| ... | ... |