Deployer

Railway Deployment Skill

Expert Railway deployment engineer with deep knowledge of Railway CLI, containerized deployments, and cloud infrastructure optimization.

When to Use This Skill

Activate this skill when:

• Deploying applications to Railway platform
• Configuring Railway services and environment variables
• Managing databases and add-ons through Railway
• Troubleshooting Railway deployments
• Setting up custom domains on Railway
• Interacting with Railway CLI

Do NOT use when:

• Writing application code (use frontend/backend skills)
• Debugging application logic (use debug skill)
• Security auditing (use security skill)

Priority Matrix

| Priority | Category | Rules | |----------|----------|-------| | CRITICAL | Deployment Method & Verification | RD01-RD04 | | HIGH | Configuration | RD05-RD08 | | MEDIUM | CLI Operations | RD09-RD11 | | LOW | Optimization | RD12-RD13 |

Core Principles

Priority: CRITICAL

[RD01] Always Use CLI Push Deployment

• Always use railway up (CLI push). Never use git-based deployment.
• Workflow: cd ~/Desktop/projects/ && railway service link && railway up 2>&1

[RD02] Never Sleep After Deploy

• NEVER sleep after railway up. It streams build logs to stdout — run in foreground, wait to complete, then verify production URL.
• If deploy needs propagation time, retry curl 3-5 times with 5s gaps — never blind sleep.

[RD03] Verify Production with Correct User-Agent

• After deploy, verify production with curl -s -A "Claude-Agent" (Cloudflare blocks default curl UA)
• railway logs uses -n for line count, not --limit
• Check for startup errors, port binding, database connections
• Deployment is NOT complete until service is confirmed running

[RD04] Dockerfile Deployment Preferred

• Always prefer Dockerfile over Nixpacks for full control
• Use Deno image (denoland/deno:2.1.4) when possible
• Fall back to Node.js 22+ when Deno won't work
• Set builder to DOCKERFILE in railway.json

Priority: HIGH

[RD05] Environment Variables

• Set all required env vars BEFORE deployment
• Use railway variables --set "KEY=value"
• Never commit secrets to version control
• Verify PORT variable works with Railway's automatic assignment
• Required backend vars: JWTSECRET, STRIPEKEY, NODE_ENV=production

[RD06] Single-Origin Deployment

• For combined frontend+backend, set backendURL: "" in constants.json
• This makes frontend use same-origin requests (avoids CORS issues)
• Prevents CSP violations like "connect-src 'self'"
• Use devBackendURL for local development

[RD07] Node.js Version Configuration

• Railway's Nixpacks defaults to Node 18 (often too old)
• For Node 22+, add to package.json:

{
  "engines": {
    "node": ">=22.5.0"
  }
}

• Or create .node-version file with: 22
• Or set NIXPACKS_NODE_VERSION=22 environment variable

[RD08] CORS Configuration

• Verify CORS allows the frontend domain
• For single-origin, CORS not needed
• For separate services, set origin to exact frontend URL
• Never use origin: '*' in production

Priority: MEDIUM

[RD09] Railway CLI Commands

• railway init - Create new project
• railway link - Link to existing project
• railway up - Deploy current directory
• railway logs - Stream live logs
• railway logs -n 100 - Last 100 log lines
• railway variables - List all variables
• railway variables --set "KEY=value" - Set variable
• railway domain - Generate Railway domain
• railway status - Show deployment status

[RD10] Database Provisioning

• railway add --database postgres - Add PostgreSQL
• railway add --database mysql - Add MySQL
• railway add --database redis - Add Redis
• railway add --database mongo - Add MongoDB
• Railway auto-injects connection variables like DATABASE_URL

[RD11] Troubleshooting Workflow

1. Check build logs: railway logs --build
2. Check deployment logs: railway logs --deployment
3. Check live logs: railway logs
4. Verify environment variables: railway variables
5. Check service status: railway status

Priority: LOW

[RD12] Monorepo Strategy

• Set root directory in Railway or use railway.json
• For backend: Set start command to node server.js
• For frontend: Set build command and output directory
• Consider single service serving both (backend serves frontend build)

[RD13] SQLite Consideration

• Railway uses ephemeral storage for SQLite
• Recommend switching to PostgreSQL for production persistence
• Add PostgreSQL with: railway add --database postgres

Dockerfile Templates

Deno (Preferred):

FROM denoland/deno:2.1.4
WORKDIR /app
COPY package*.json deno.json* ./
RUN deno install
COPY . .
RUN deno run build
EXPOSE 8000
CMD ["deno", "run", "--allow-net", "--allow-read", "--allow-env", "backend/server.js"]

Node.js (Fallback):

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 8000
CMD ["node", "--experimental-sqlite", "backend/server.js"]

railway.json for Dockerfile:

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "DOCKERFILE",
    "dockerfilePath": "Dockerfile"
  }
}

Deployment Workflow

New Projects:

1. Verify Railway CLI installed: railway --version
2. Authenticate: railway login
3. Initialize: railway init
4. Set environment variables: railway variables --set "KEY=value"
5. Deploy: railway up
6. CRITICAL: Verify with logs: railway logs -n 10
7. Generate domain: railway domain

Existing Projects:

1. Link to project: railway link
2. Check status: railway status
3. Update variables if needed
4. Deploy: railway up
5. CRITICAL: Verify with logs: railway logs -n 10

Common Issues

| Issue | Cause | Solution | |-------|-------|----------| | Build fails | Node version too old | Add engines to package.json or .node-version file | | "bad option: --experimental-sqlite" | Node < 22.5 | Update Node version configuration | | CORS errors | Origin mismatch | Set backendURL: "" for same-origin or configure CORS | | CSP violation | connect-src policy | Use same-origin deployment | | Port binding error | Wrong PORT usage | Ensure server uses process.env.PORT | | Database connection fails | Missing env vars | Check DATABASE_URL is set |

Security Practices

[RD-X01] Never commit .env files [RD-X02] Never log environment variables [RD-X03] Use different secrets per environment [RD-X04] Rotate secrets regularly [RD-X05] Never hardcode credentials

Quality Checklist

Before completing deployment:

• [ ] All required environment variables set
• [ ] Successful build confirmed in logs
• [ ] Server started successfully (verified in logs)
• [ ] Service responds to requests
• [ ] Database connectivity verified (if applicable)
• [ ] CORS allows frontend domain (if separate services)
• [ ] Domain generated and accessible

References

See [references/railway-commands.md](references/railway-commands.md) for:

• Complete CLI command reference
• Troubleshooting guides
• Configuration examples
• Best practices

Task-Specific Questions

1. First deploy or updating an existing service?
2. Which Railway service should this deploy to?
3. Are all environment variables configured?
4. Does this need a custom domain?
5. Is there a Dockerfile or should Nixpacks handle the build?

Output Format

Structure deployments as:

1. Pre-Deploy Checklist — env vars, build verification, service link
2. Deploy — railway up output and build logs
3. Verification — production URL check with curl -A "Claude-Agent"

Related Skills

• backend: For the server code being deployed
• security: For verifying no secrets are exposed in the build

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stevederico
• Source: stevederico/skills
• License: MIT

Install and usage instructions live in the source repository linked above.