cwinvestments/memstack-deployment-railway-deploy

🚂 Railway Deploy — Pre-flight check and deploy to Railway...

Validates project configuration, environment variables, and deployment readiness before pushing to Railway.

Activation

When this skill activates, output:

🚂 Railway Deploy — Running pre-flight checks...

Then execute the protocol below.

| Context | Status | |---------|--------| | User says "deploy to railway" or "railway deploy" | ACTIVE | | User says "ship it" or "deploy backend" with a Railway project | ACTIVE | | Preparing a backend/fullstack app for production | ACTIVE | | Deploying to Netlify, Vercel, or other non-Railway platform | DORMANT | | Discussing Railway pricing or features generally | DORMANT |

Anti-patterns

| Trap | Reality Check | |------|---------------| | "I'll just railway up and see what happens" | Pre-flight catches 90% of deploy failures. Check first. | | "Environment vars are probably fine" | Missing vars are the #1 cause of Railway deploy failures. Verify every one. | | "It works locally so it'll work on Railway" | localhost URLs, SQLite paths, and file:// references all break in production. | | "I'll fix the Dockerfile later" | Railway's nixpacks auto-detect fails on monorepos and custom setups. Define build explicitly. | | "The database connection works" | Railway internal networking uses *.railway.internal hostnames. External URLs add latency and cost. |

Protocol

Step 1: Detect Project Type

Identify the project framework and runtime:

# Check for framework indicators
ls package.json pyproject.toml requirements.txt Cargo.toml go.mod 2>/dev/null

| Indicator | Project Type | |-----------|-------------| | package.json with next | Next.js | | package.json with express/fastify/hono | Node.js API | | pyproject.toml or requirements.txt | Python (Django/Flask/FastAPI) | | Cargo.toml | Rust | | go.mod | Go |

Report: Detected: [type] project

Step 2: Check Deployment Files

Verify Railway can build the project:

# Check for explicit build configuration
ls Dockerfile Procfile nixpacks.toml railway.toml 2>/dev/null

| File | Purpose | Required? | |------|---------|-----------| | Dockerfile | Explicit container build | Recommended for complex projects | | Procfile | Process start command | Optional if start script exists | | nixpacks.toml | Nixpacks build config | Optional — auto-detected | | railway.toml | Railway-specific settings | Optional — build/deploy overrides |

If none exist, check that nixpacks can auto-detect:

• Node.js: package.json must have start script or main field
• Python: Must have requirements.txt or pyproject.toml with dependencies

Flag if missing: No build configuration found. Recommend adding railway.toml or Dockerfile.

Step 3: Verify Environment Variables

Cross-reference what the app needs vs what Railway has:

# Find required env vars
cat .env.example .env.sample 2>/dev/null | grep -v '^#' | grep '=' | cut -d= -f1

Check for these common categories:

| Category | Variables to Verify | |----------|-------------------| | Database | DATABASE_URL, POSTGRES_URL, REDIS_URL, MONGODB_URI | | Auth | JWT_SECRET, SESSION_SECRET, NEXTAUTH_SECRET, NEXTAUTH_URL | | External APIs | STRIPE_SECRET_KEY, SENDGRID_API_KEY, AWS_ACCESS_KEY_ID | | App Config | NODE_ENV=production, PORT (Railway sets this automatically) | | URLs | FRONTEND_URL, BACKEND_URL, CORS_ORIGIN |

Output: List each variable with status:

• ✅ Set in .env.example — verify it's configured in Railway dashboard
• ⚠️ Referenced in code but not in .env.example — add to Railway
• ❌ Hardcoded value found — extract to environment variable

Remind user: "Set these in Railway dashboard → Variables tab. Never commit actual values."

Step 4: Verify Build and Start Commands

# Node.js
cat package.json | grep -A2 '"scripts"' | grep -E '"(build|start|dev)"'

# Python
cat Procfile 2>/dev/null || cat pyproject.toml 2>/dev/null | grep -A5 '\[tool.poetry.scripts\]'

Verify:

• Build command exists and produces output (e.g., npm run build → dist/ or .next/)
• Start command uses production mode (not dev or nodemon)
• Port reads from process.env.PORT or os.environ["PORT"] — Railway assigns this dynamically

Flag if: Start command uses hardcoded port (e.g., app.listen(3000) without PORT env fallback).

Step 5: Verify Database Connection Strings

If the project uses a database:

# Search for connection patterns
grep -r "localhost:5432\|localhost:3306\|localhost:6379\|127.0.0.1" --include="*.ts" --include="*.js" --include="*.py" --include="*.env*" .

Railway internal networking rules:

• ✅ ${{Postgres.DATABASE_URL}} — Railway reference variable
• ✅ *.railway.internal:5432 — internal hostname (no egress cost)
• ❌ localhost:5432 — won't resolve in Railway container
• ❌ Public Railway URL with port — adds latency, uses egress bandwidth

Flag if: Any hardcoded localhost or 127.0.0.1 database URLs found.

Step 6: Check Health Check Endpoint

# Search for common health check patterns
grep -rn "\/health\|\/healthz\|\/api\/health\|\/readyz" --include="*.ts" --include="*.js" --include="*.py" .

If no health endpoint exists, recommend adding one:

// Express/Fastify pattern
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', timestamp: new Date().toISOString() });
});

Configure in Railway: Settings → Deploy → Health Check Path → /health

Step 7: Pre-Deploy Checklist

Run the build locally to catch errors before deploying:

# Build test
npm run build  # or equivalent

# Search for localhost references
grep -rn "localhost\|127\.0\.0\.1" --include="*.ts" --include="*.js" --include="*.py" . | grep -v node_modules | grep -v .git

| Check | Command | Pass Criteria | |-------|---------|--------------| | Build passes | npm run build | Exit code 0, no errors | | No hardcoded URLs | grep for localhost | Zero matches in source | | Production env vars | Review .env.example | All vars documented | | Port configuration | grep for PORT | Reads from env, not hardcoded | | Node version | Check engines in package.json | Specified if needed | | Git clean | git status | All changes committed |

Output pre-deploy summary:

🚂 Railway Deploy — Pre-flight Complete

Project: [name] ([type])
Build: ✅ passes
Env vars: ✅ 12 documented, verify in Railway dashboard
Database: ✅ uses Railway internal networking
Health check: ✅ /health endpoint configured
Localhost refs: ✅ none found
Port: ✅ reads from process.env.PORT

Ready to deploy. Run: railway up

Step 8: Post-Deploy Verification

After deployment completes:

1. Health check: curl https://[app].up.railway.app/health
2. Logs: Check Railway dashboard → Deployments → View Logs for startup errors
3. Database: Verify migrations ran (check logs for migration output)
4. Environment: Confirm NODE_ENV=production is active

Rollback plan:

• Railway keeps previous deployments. Go to Deployments → click previous successful deploy → Rollback
• Or via CLI: railway rollback

If deploy fails:

1. Check build logs first — dependency or build script errors
2. Check runtime logs — missing env vars show as undefined/null errors
3. Check health check timeout — app may be starting slowly (increase timeout in Settings)
4. Verify Railway service is connected to correct GitHub branch

Level History

• Lv.1 — Base: Project detection, env var verification, build validation, database connection checks, health endpoint, pre/post-deploy checklists. Based on AdminStack, DeedStack, AlgoStack, and EpsteinScan Railway deployments. (Origin: MemStack Pro v3.2, Mar 2026)