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