🚂 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.

Anti-patterns

railway up

*.railway.internal

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

package.json

next

package.json

express

fastify

hono

pyproject.toml

requirements.txt

Cargo.toml

go.mod

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

Dockerfile

Procfile

nixpacks.toml

railway.toml

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

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:

DATABASE_URL

POSTGRES_URL

REDIS_URL

MONGODB_URI

JWT_SECRET

SESSION_SECRET

NEXTAUTH_SECRET

NEXTAUTH_URL

STRIPE_SECRET_KEY

SENDGRID_API_KEY

AWS_ACCESS_KEY_ID

NODE_ENV=production

PORT

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)

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

127.0.0.1

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

npm run build

engines

git status

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)