adaptationio/railway-deployment

Railway Deployment Management

Complete deployment workflows for Railway.com including deployment from multiple sources, rollback strategies, health verification, and staging-to-production promotion.

Overview

This skill provides comprehensive deployment management for Railway:

• Deploy from sources: GitHub auto-deploy, Docker images, local directory
• Monitor deployments: Real-time logs, status tracking, build progress
• Verify health: Automated health checks and validation
• Rollback strategies: Safe rollback to previous deployments
• Environment management: Staging → production workflows
• CI/CD integration: Automated deployment pipelines

Prerequisites

• Railway CLI installed and authenticated (use railway-auth skill)
• Project linked (use railway-project-management skill)
• Service created in target environment

When to Use

• Deploying new code to Railway
• Redeploying after configuration changes
• Rolling back failed deployments
• Promoting staging to production
• Setting up automated deployments
• Monitoring deployment progress
• Verifying deployment health

---

5-Step Deployment Workflow

Step 1: Prepare Deployment

Verify authentication, project context, and service health before deploying.

Commands:

# Verify authentication
railway whoami

# Check project and environment context
railway status

# List services in current environment
railway list

# Check current deployment status
railway status --json

Pre-deployment checklist:

• [ ] Authenticated with Railway
• [ ] Correct project linked
• [ ] Target environment selected
• [ ] Service exists in environment
• [ ] No pending deployments
• [ ] Environment variables set

Use automation:

.claude/skills/railway-deployment/scripts/pre-deploy-check.sh

---

Step 2: Deploy

Deploy from GitHub, Docker, or local directory.

Deploy from GitHub (Auto-Deploy)

Setup auto-deploy:

# Link service to GitHub repo
railway add --repo owner/repository

# Configure branch (via dashboard or railway.json)
railway open

Trigger deployment:

# Push to configured branch
git push origin main

# Railway automatically deploys
# Monitor in real-time:
railway logs --deployment

Manual redeploy:

# Redeploy latest commit
railway redeploy

# Redeploy specific deployment ID
railway redeploy --deployment <deployment-id>

Deploy from Local Directory

Deploy current directory:

# Deploy and wait for completion
railway up

# Deploy without waiting (detached)
railway up --detach

# Deploy in CI mode (build logs only)
railway up --ci

# Deploy specific service
railway up --service backend

What happens:

1. CLI uploads local directory to Railway
2. Railway detects build configuration (Nixpacks/Dockerfile)
3. Build starts automatically
4. Deployment triggers on successful build
5. Service restarts with new code

Deploy from Docker Image

Public image:

# Deploy Docker Hub image
railway add --image postgres:15

# Deploy with tag
railway add --image myapp/backend:v1.2.3

Private registry:

# Set registry credentials
railway variables set --sealed DOCKER_USERNAME=user
railway variables set --sealed DOCKER_PASSWORD=pass

# Deploy from private registry
railway add --image registry.example.com/app:latest

Update image tag (rollback/upgrade):

# Via environment variable
railway variables set IMAGE_TAG=v1.2.2

# Force redeploy with new tag
railway redeploy

See references/deployment-sources.md for detailed configuration.

---

Step 3: Monitor Deployment

Track deployment progress and identify issues in real-time.

Real-time logs:

# Follow deployment logs
railway logs --deployment

# Filter by service
railway logs --service backend --deployment

# Show last 100 lines
railway logs --tail 100

# Include timestamps
railway logs --timestamps

Deployment status:

# Check deployment status
railway status

# Get detailed JSON status
railway status --json | jq '.deployments[0]'

# List recent deployments
railway list deployments

# Check specific deployment
railway deployment <deployment-id>

Build progress indicators:

Building... ████████░░░░░░░░ 60%
Installing dependencies...
Running build script...
Optimizing assets...

Watch for issues:

• Build failures (missing dependencies)
• Environment variable errors
• Port binding issues
• Memory/CPU limits exceeded
• Health check failures

Automated monitoring:

# Monitor and alert on failures
.claude/skills/railway-deployment/scripts/monitor-deployment.sh

---

Step 4: Verify Deployment

Validate that deployment is healthy and functioning correctly.

Health check commands:

# Check service health endpoint
curl https://your-service.railway.app/health

# Verify with custom validation
.claude/skills/railway-deployment/scripts/verify-health.sh

Validation checklist:

• [ ] Service is running (not crashed)
• [ ] Health endpoint returns 200 OK
• [ ] Environment variables loaded correctly
• [ ] Database connections established
• [ ] API endpoints responding
• [ ] Static assets loading
• [ ] No error logs present

Automated validation:

# Run full health check suite
.claude/skills/railway-deployment/scripts/deploy.sh --verify

# Output:
# ✅ Service running
# ✅ Health check passed (200 OK)
# ✅ Environment variables loaded
# ✅ Database connection successful
# ✅ API responding correctly

Common validation issues:

| Issue | Symptom | Solution | |-------|---------|----------| | Service not starting | Status: "crashed" | Check logs for startup errors | | Health check failing | 503 Service Unavailable | Verify health endpoint path | | Variables missing | Application errors | Check railway variables list | | Port binding error | "EADDRINUSE" | Ensure PORT variable used | | Database connection | "ECONNREFUSED" | Verify DATABASE_URL set |

---

Step 5: Rollback if Needed

Safely rollback to previous deployment if issues are detected.

Quick rollback:

# Redeploy previous deployment
railway redeploy --deployment <previous-deployment-id>

# List recent deployments to find ID
railway list deployments

Automated rollback:

# Rollback with safety checks
.claude/skills/railway-deployment/scripts/rollback.sh

# Rollback to specific version
.claude/skills/railway-deployment/scripts/rollback.sh v1.2.3

Rollback strategies:

1. Redeploy Previous Commit (GitHub):

   # Find previous working commit
   git log --oneline
   
   # Revert to previous commit
   git revert HEAD
   git push origin main
   
   # Railway auto-deploys
   

2. Redeploy Previous Deployment (any source):

   # List deployments
   railway list deployments
   
   # Redeploy specific deployment ID
   railway redeploy --deployment dep_abc123xyz
   

3. Docker Image Tag Rollback:

   # Update image tag to previous version
   railway variables set IMAGE_TAG=v1.2.2
   
   # Redeploy with previous tag
   railway redeploy
   

4. Environment Variable Rollback:

   # Restore previous variable values
   railway variables set API_VERSION=v1
   railway variables set FEATURE_FLAGS=old-config
   
   # Redeploy with previous config
   railway redeploy
   

See references/rollback-strategies.md for detailed rollback procedures.

Rollback verification:

# After rollback, verify health
.claude/skills/railway-deployment/scripts/verify-health.sh

# Check logs for errors
railway logs --tail 50

# Verify specific functionality
curl https://your-service.railway.app/api/test

---

Staging → Production Workflow

Typical promotion flow:

# 1. Deploy to staging first
railway environment staging
railway up

# 2. Verify staging deployment
.claude/skills/railway-deployment/scripts/verify-health.sh

# 3. Run staging tests
npm run test:staging

# 4. Promote to production
railway environment production

# 5. Deploy same code
railway up

# 6. Verify production
.claude/skills/railway-deployment/scripts/verify-health.sh

# 7. Monitor production logs
railway logs --deployment

Automated staging workflow:

# Complete staging → production workflow
.claude/skills/railway-deployment/scripts/promote-to-production.sh

See references/staging-workflow.md for detailed staging strategies.

---

CI/CD Integration

GitHub Actions

name: Deploy to Railway
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Railway CLI
        run: npm install -g @railway/cli

      - name: Deploy to Railway
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
        run: |
          railway up --ci

      - name: Verify Deployment
        run: |
          sleep 30
          curl -f https://your-service.railway.app/health || exit 1

GitLab CI

deploy:staging:
  stage: deploy
  image: node:20
  script:
    - npm install -g @railway/cli
    - railway environment staging
    - railway up --ci
  environment:
    name: staging
  only:
    - develop

deploy:production:
  stage: deploy
  image: node:20
  script:
    - npm install -g @railway/cli
    - railway environment production
    - railway up --ci
  environment:
    name: production
  only:
    - main
  when: manual

---

Advanced Deployment Patterns

Blue-Green Deployment

# 1. Deploy to "green" environment
railway environment green
railway up

# 2. Verify green is healthy
.claude/skills/railway-deployment/scripts/verify-health.sh

# 3. Switch traffic to green
# (Update DNS or load balancer)

# 4. Keep blue as rollback option
railway environment blue
# (Don't delete until green is stable)

Canary Deployment

# 1. Deploy canary version
railway environment canary
railway up

# 2. Route small % of traffic to canary
# (Configure via load balancer)

# 3. Monitor canary metrics
railway logs --service canary

# 4. Gradually increase traffic
# (Adjust load balancer weights)

# 5. Promote to production if successful
railway environment production
railway up

Rolling Deployment

# Deploy to instances one at a time
# (Requires horizontal scaling)

# Railway handles rolling deploys automatically
# when multiple replicas are configured
railway up

# Monitors health and rolls back on failure

---

Deployment Troubleshooting

Build Failures

# Check build logs
railway logs --deployment

# Common issues:
# - Missing package.json
# - Node/Python version mismatch
# - Build command failures
# - Environment variables not set

# Fix and redeploy
railway up

Deployment Stuck

# Check deployment status
railway status --json

# Cancel stuck deployment
railway deployment cancel <deployment-id>

# Redeploy
railway up

Health Check Failures

# Check service logs
railway logs

# Verify health endpoint exists
curl -v https://your-service.railway.app/health

# Check port configuration
railway variables list | grep PORT

# Verify restart policy
railway open  # Check service settings

Memory/CPU Limits

# Check resource usage
railway metrics

# Increase limits (via dashboard)
railway open

# Or upgrade plan

---

Quick Reference

Core Deployment Commands

| Command | Description | |---------|-------------| | railway up | Deploy local directory | | railway up --detach | Deploy without waiting | | railway up --ci | Deploy in CI mode | | railway redeploy | Redeploy latest deployment | | railway logs --deployment | Monitor deployment logs | | railway status | Check deployment status |

Deployment Sources

| Source | Command | Auto-Deploy | |--------|---------|-------------| | GitHub | railway add --repo owner/repo | ✅ Yes (on push) | | Local | railway up | ❌ Manual | | Docker | railway add --image image:tag | ❌ Manual |

Environment Workflow

# Staging
railway environment staging
railway up

# Production
railway environment production
railway up

---

Automated Scripts

Smart Deployment with Health Checks

# Deploy with automatic health verification
.claude/skills/railway-deployment/scripts/deploy.sh

# Deploy specific service
.claude/skills/railway-deployment/scripts/deploy.sh backend

# Deploy with custom health endpoint
.claude/skills/railway-deployment/scripts/deploy.sh backend /api/health

Safe Rollback

# Rollback with confirmation prompt
.claude/skills/railway-deployment/scripts/rollback.sh

# Rollback to specific deployment
.claude/skills/railway-deployment/scripts/rollback.sh dep_abc123

# Emergency rollback (no confirmation)
.claude/skills/railway-deployment/scripts/rollback.sh --force

Pre-Deployment Validation

# Check all prerequisites
.claude/skills/railway-deployment/scripts/pre-deploy-check.sh

# Validates:
# - Railway authentication
# - Project linked
# - Environment selected
# - No pending deployments
# - Variables configured

---

Related Skills

• railway-auth: Authenticate with Railway CLI and manage tokens
• railway-project-management: Create projects, manage environments, configure variables
• railway-observability: Monitor metrics, logs, and traces
• railway-api: GraphQL API automation for advanced workflows

---

Additional Resources

• References:

  • references/deployment-sources.md: GitHub, Docker, and local deployment details
  • references/rollback-strategies.md: Comprehensive rollback procedures
  • references/staging-workflow.md: Staging → production best practices

• Scripts:

  • scripts/deploy.sh: Smart deployment with health checks
  • scripts/rollback.sh: Safe rollback with confirmation
  • scripts/verify-health.sh: Automated health validation
  • scripts/pre-deploy-check.sh: Pre-deployment validation
  • scripts/promote-to-production.sh: Staging → production automation

• Railway Documentation:

  • Deployments
  • CLI Commands
  • GitHub Integration
  • Docker Deployments

---

Last Updated: November 2025 Status: Production-ready Version: 1.0.0