deployer

name	deployer
description	Railway platform deployment with optimal configuration and troubleshooting. Also use when the user mentions 'deploy,' 'railway,' 'push to production,' 'environment variables,' 'deployment failed,' 'build error,' 'railway logs,' 'custom domain,' or 'database provisioning.' Use this even if the user just says 'ship it' or 'get it live.'
license	MIT
version	1.0.0
author	stevederico

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/<project> && railway service link <service-name> && 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: JWT_SECRET, STRIPE_KEY, 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 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