name: ship description: Deploy to Railway and debug deployment issues. Use when deploying the application, checking deployment status, or debugging deployment failures.

Ship to Railway

Deploys the application to Railway and provides debugging workflows for deployment issues.

When to Use

• Deploying the application to Railway
• Debugging failed deployments
• Checking deployment status
• User asks to "deploy", "ship", or "debug deployment"

Railway CLI Setup

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Link to project
railway link

Essential Commands

# View deployment status
railway status

# List recent deployments
railway deployment list

# Stream live logs
railway logs

# View build logs for failed deployment
railway logs --build <deployment-id>

# View runtime logs for crashed deployment
railway logs <deployment-id> --lines 200

# Deploy manually
railway up

# Redeploy latest
railway deployment redeploy

Pre-Deployment Checklist

# 1. Run local build
npm run build

# 2. Check TypeScript
npm run typecheck

# 3. Run tests
npm run test:run

# 4. Check environment variables in Railway
railway variables

Deployment Status Types

Common Issues & Fixes

Issue 1: Peer Dependency Conflict (FAILED)

Error:

ERESOLVE could not resolve
peer react@"^18.0.0" from @some/package
Found: react@19.x

Fix: Add --legacy-peer-deps to Dockerfile:

RUN npm ci --legacy-peer-deps
RUN npm ci --omit=dev --legacy-peer-deps

Issue 2: Missing Production Dependency (CRASHED)

Error:

Cannot find module 'some-package'

Fix: Move package from devDependencies to dependencies:

npm install --save-prod some-package

Issue 3: Missing Environment Variable

Error:

Environment variable not found: DATABASE_URL

Fix: Set variable in Railway:

railway variables set DATABASE_URL="postgresql://..."

Issue 4: Database Connection Failed

Error:

Failed to connect to database after 30 attempts

Fix:

1. Check DATABASE_URL is set correctly
2. Use internal hostname for Railway services: postgresql://user:pass@postgres.railway.internal:5432/db

Debugging Workflow

Step 1: Check Status

railway deployment list

Step 2: Get Deployment ID

Look for the most recent deployment and note its ID.

Step 3: Check Logs

For FAILED (build error):

railway logs --build <deployment-id>

For CRASHED (runtime error):

railway logs <deployment-id> --lines 200

Step 4: Fix and Redeploy

# Make fixes
git add .
git commit -m "fix: deployment issue"
git push

Railway auto-deploys on push to linked branch.

Environment Variables

Critical variables to set:

DATABASE_URL          # Required at build + runtime
BETTER_AUTH_SECRET    # Runtime only
BETTER_AUTH_URL       # Match your Railway domain
NODE_ENV=production   # Set by Railway automatically

Check all variables:

railway variables

Dockerfile Multi-Stage Build

Our Dockerfile has 4 stages:

1. development-dependencies-env - All deps (dev + prod)
2. production-dependencies-env - Prod deps only (--omit=dev)
3. build-env - Build application
4. Final stage - Runtime with prod deps only

Key insight: Production stage uses --omit=dev, so runtime packages MUST be in dependencies, not devDependencies.

Quick Reference

Full Reference

See .github/instructions/railway-deployment.instructions.md for comprehensive documentation.