Deploy to Railway — SKILL.md

---
name: "Deploy to Railway"
description: "Full deployment workflow for Railway — init project, add Postgres, set env vars, deploy, configure domains"
version: "1.0.0"
author: "skynet"
category: "infrastructure"
agents: ["claude-code", "codex", "gemini"]
tags: ["railway", "deploy", "hosting", "postgres"]
tools_required: ["shell"]
---

# Deploy to Railway

# Deploy to Railway

## When to use

Use this skill when you need to deploy a web application (FastAPI, Next.js, Express, etc.) to Railway with optional Postgres, Redis, or other add-ons.

## Prerequisites

- Railway CLI installed and authenticated: `railway whoami` should return `worklocalinc`
- If not installed: `npm install -g @railway/cli && railway login`
- Project source code ready with a valid Dockerfile or supported runtime

## Instructions

### Step 1: Initialize the Railway project

```bash
cd /path/to/project
railway init
# Select "Empty Project" or link to existing
```

If linking to a GitHub repo:
```bash
railway link
# Select the project from the list
```

### Step 2: Add a Postgres database (if needed)

```bash
railway add -d postgres
```

This provisions a Postgres instance and sets `DATABASE_URL`, `DATABASE_PUBLIC_URL`, `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` as service variables automatically.

For Prisma projects, the internal `DATABASE_URL` uses private networking (faster, no egress cost). Use `DATABASE_PUBLIC_URL` only for external access (migrations from local machine, etc.).

### Step 3: Set environment variables

```bash
railway variables set NODE_ENV=production
railway variables set SECRET_KEY=$(openssl rand -hex 32)
# Add any project-specific vars
```

To set multiple at once:
```bash
railway variables set KEY1=val1 KEY2=val2 KEY3=val3
```

### Step 4: Deploy

```bash
railway up --detach
```

The `--detach` flag returns immediately. Railway auto-detects the runtime:
- Dockerfile present -> Docker build
- package.json -> Node.js (Nixpacks)
- requirements.txt / pyproject.toml -> Python (Nixpacks)

### Step 5: Get a public domain

```bash
railway domain
```

This generates a `*.up.railway.app` URL. For custom domains:
```bash
railway domain add api.example.com
```

Then add a CNAME record pointing `api.example.com` to the Railway-provided target.

### Step 6: Verify deployment

```bash
railway logs
railway status
```

### Common patterns

**FastAPI deploy:**
```bash
# Ensure Dockerfile or Procfile exists
# Procfile: web: uvicorn main:app --host 0.0.0.0 --port $PORT
railway up --detach
```

**Next.js deploy:**
```bash
# Railway auto-detects Next.js from package.json
# Set PORT=3000 if not auto-detected
railway variables set PORT=3000
railway up --detach
```

**Switch between services in multi-service project:**
```bash
railway service <service-name>
railway logs  # now shows logs for that service
```

**Link GitHub for auto-deploy on push:**
```bash
railway add --repo worklocalinc/<repo-name>
```

## Troubleshooting

- **Build fails**: Check `railway logs` for Nixpacks/Docker errors. Ensure start command is correct.
- **Port issues**: Railway injects `$PORT`. Your app must listen on `0.0.0.0:$PORT`, not localhost.
- **DB connection refused**: Use the internal URL (`DATABASE_URL`), not the public one, from within Railway services.
- **Deploy stuck**: `railway redeploy` forces a fresh build.
- **CLI not linked**: Run `railway link` to re-associate the local directory with a project.

## References

- Railway docs: https://docs.railway.com
- Railway CLI: https://docs.railway.com/guides/cli
- James's Railway account: `worklocalinc`