Railway Deployment
Deploy projects to Railway with proper Dockerfile, config, and multi-environment support.
How Railway Works
Railway builds and runs your app from a Dockerfile (or auto-detects with Nixpacks). Each project can have multiple services (web, worker, cron) across multiple environments (dev, production). Railway assigns a dynamic PORT env var that your app must listen on.
Prerequisites
Railway credentials (for GraphQL API deployments) go in the current project's repo-root .env file — see .env.example for the full list. Get your API token at https://railway.app/account/tokens.
Railway CLI should be installed and authenticated. Verify:
railway --version # Should show v4.x+
railway whoami # Should show logged-in user
If not installed: brew install railway (macOS) or npm i -g @railway/cli, then railway login.
Deployment Approaches
Railway supports two deployment methods. Choose based on the project's needs:
Approach 1: Railway CLI (simple projects)
Best for quick deploys, single-service apps, and projects where you want Railway to auto-detect the build.
# Link to existing project (or create new)
railway link # Interactive — select project + environment
# OR
railway init # Create new project
# Deploy
railway up # Builds and deploys from current directory
# Check status
railway status
railway logs
Approach 2: GraphQL API + Deploy Script (multi-service, CI/CD)
Best for projects with multiple services (web + worker), automated deployments, or when you need programmatic control. See references/deploy-script.md for a ready-to-use deploy script pattern.
Setting Up a New Project for Railway
Detect the stack. Read package.json / requirements.txt / Cargo.toml / go.mod to identify language, framework, entry point, and system deps. See references/dockerfile-recipes.md for the full stack detection checklist.
Create the Dockerfile. Pick the recipe matching your stack — references/dockerfile-recipes.md has Python/FastAPI, Node.js/Express/Next.js, and Astro templates, plus Dockerfile best practices.
Create railway.toml. The standard template with startCommand, healthcheckPath, restartPolicyType is in references/dockerfile-recipes.md.
Create .dockerignore. Exclude dev deps, local DBs, build artifacts. Template in references/dockerfile-recipes.md.
Add a health check endpoint. Railway uses it to know when the app is ready. Python/FastAPI and Node/Express snippets are in references/dockerfile-recipes.md.
Optional fallback: Railway prefers Dockerfile but falls back to a Procfile if present — only relevant when you can't ship a Dockerfile. See the Procfile section in references/dockerfile-recipes.md.
Environment Variables, Multi-Service, Troubleshooting
For env var management (railway variables set), multi-service setups (web + worker on the same project), the full deployment checklist, and troubleshooting common deploy failures (build errors, crash loops, health check timeouts, 502 errors, port binding), read references/multi-service-setup.md.
Reference Files
references/dockerfile-recipes.md — per-language Dockerfile templates (Python, Node, Astro), railway.toml, .dockerignore, health check endpoints, Procfile
references/multi-service-setup.md — env vars, multi-service (web + worker), deployment checklist, troubleshooting
references/deploy-script.md — Python deploy script pattern using Railway's GraphQL API
1---2name: railway-deploy3version: 1.3.14description: >5 Deploy projects to Railway — Dockerfile creation, railway.toml config, environment variables,6 multi-service setups (web + worker), and deployment via CLI or GraphQL API. Trigger on "deploy to7 Railway", "ship it on Railway", or "set up Railway hosting", and on questions about Railway8 configuration, health checks, deployment status, or env var management.9requires_agent_teams: false10requires_claude_code: false11min_plan: starter12owns:13 directories: []14 patterns: ["railway.toml"]15 shared_read: ["*"]16allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]17composes_with: ["infrastructure-agent", "deployment-checklist"]18spawned_by: []19metadata:20 source: https://skillmd.com/skills/ivy00johns/railway-deploy21---2223# Railway Deployment2425Deploy projects to Railway with proper Dockerfile, config, and multi-environment support.2627## How Railway Works2829Railway builds and runs your app from a Dockerfile (or auto-detects with Nixpacks). Each project can have multiple **services** (web, worker, cron) across multiple **environments** (dev, production). Railway assigns a dynamic `PORT` env var that your app must listen on.3031## Prerequisites3233**Railway credentials** (for GraphQL API deployments) go in the current project's repo-root `.env` file — see `.env.example` for the full list. Get your API token at https://railway.app/account/tokens.3435**Railway CLI** should be installed and authenticated. Verify:3637```bash38railway --version # Should show v4.x+39railway whoami # Should show logged-in user40```4142If not installed: `brew install railway` (macOS) or `npm i -g @railway/cli`, then `railway login`.4344## Deployment Approaches4546Railway supports two deployment methods. Choose based on the project's needs:4748### Approach 1: Railway CLI (simple projects)4950Best for quick deploys, single-service apps, and projects where you want Railway to auto-detect the build.5152```bash53# Link to existing project (or create new)54railway link # Interactive — select project + environment55# OR56railway init # Create new project5758# Deploy59railway up # Builds and deploys from current directory6061# Check status62railway status63railway logs64```6566### Approach 2: GraphQL API + Deploy Script (multi-service, CI/CD)6768Best for projects with multiple services (web + worker), automated deployments, or when you need programmatic control. See `references/deploy-script.md` for a ready-to-use deploy script pattern.6970## Setting Up a New Project for Railway71721. **Detect the stack.** Read `package.json` / `requirements.txt` / `Cargo.toml` / `go.mod` to identify language, framework, entry point, and system deps. See `references/dockerfile-recipes.md` for the full stack detection checklist.73742. **Create the Dockerfile.** Pick the recipe matching your stack — `references/dockerfile-recipes.md` has Python/FastAPI, Node.js/Express/Next.js, and Astro templates, plus Dockerfile best practices.75763. **Create `railway.toml`.** The standard template with `startCommand`, `healthcheckPath`, `restartPolicyType` is in `references/dockerfile-recipes.md`.77784. **Create `.dockerignore`.** Exclude dev deps, local DBs, build artifacts. Template in `references/dockerfile-recipes.md`.79805. **Add a health check endpoint.** Railway uses it to know when the app is ready. Python/FastAPI and Node/Express snippets are in `references/dockerfile-recipes.md`.8182> **Optional fallback:** Railway prefers Dockerfile but falls back to a Procfile if present — only relevant when you can't ship a Dockerfile. See the Procfile section in `references/dockerfile-recipes.md`.8384## Environment Variables, Multi-Service, Troubleshooting8586For env var management (`railway variables set`), multi-service setups (web + worker on the same project), the full deployment checklist, and troubleshooting common deploy failures (build errors, crash loops, health check timeouts, 502 errors, port binding), read `references/multi-service-setup.md`.8788## Reference Files8990- `references/dockerfile-recipes.md` — per-language Dockerfile templates (Python, Node, Astro), railway.toml, .dockerignore, health check endpoints, Procfile91- `references/multi-service-setup.md` — env vars, multi-service (web + worker), deployment checklist, troubleshooting92- `references/deploy-script.md` — Python deploy script pattern using Railway's GraphQL API