Pro Deploy Workspace

A Railway-focused skill for managing deployment workflows, rollbacks, and release strategies on the Railway platform. Pro Deploy Workspace handles multi-service deployments, environment promotion, health check configuration, and zero-downtime rollback procedures.

When to Use This Skill

Choose Pro Deploy Workspace when:

• Deploying applications to Railway with specific configuration requirements
• Setting up deployment pipelines with staging and production environments
• Configuring health checks and readiness probes for Railway services
• Performing rollbacks when a deployment introduces issues

Consider alternatives when:

• Using a different hosting platform (Vercel, AWS, Fly.io)
• You need CI/CD pipeline design (use GitHub Actions or similar)
• You're deploying static sites (Railway is designed for dynamic services)

Quick Start

Copy
claude "Deploy my Node.js app to Railway with health checks"

Copy
# Deploy current directory to Railway
railway up

# Deploy with specific environment
railway up --environment production

# Check deployment status
railway status

# View deployment logs
railway logs

Copy
// railway.json — Deployment configuration
{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm ci && npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 30,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}

Core Concepts

Deployment Strategies

Strategy	Description	When to Use
Rolling	Replace instances gradually	Default, most services
Recreate	Stop old, start new	Database schema changes
Blue-Green	Run both, switch traffic	Zero-downtime critical services
Canary	Route % of traffic to new	High-risk changes

Environment Promotion

Copy
# Railway environments workflow
railway environment create staging
railway environment create production

# Deploy to staging first
railway up --environment staging

# After testing, promote to production
railway up --environment production

Health Check Configuration

Copy
// /health endpoint for Railway
app.get('/health', (req, res) => {
  const health = {
    status: 'ok',
    uptime: process.uptime(),
    timestamp: Date.now(),
    checks: {
      database: 'connected',
      redis: 'connected'
    }
  };
  res.status(200).json(health);
});

Configuration

Parameter	Description	Default
builder	Build system (NIXPACKS, DOCKERFILE)	NIXPACKS
healthcheckPath	HTTP path for health probes	/health
healthcheckTimeout	Seconds before health check fails	30
restartPolicyType	ON_FAILURE, ALWAYS, or NEVER	ON_FAILURE
numReplicas	Number of service instances	1

Best Practices

1. Always configure health checks. Without a health check, Railway considers a deployment successful as soon as the process starts. Set healthcheckPath to an endpoint that verifies database connectivity and critical dependencies — this prevents routing traffic to unhealthy instances.

2. Use environment-based deployments. Deploy to staging first, run smoke tests, then deploy to production. Railway's environment system makes this straightforward — each environment has isolated variables and deployments.

3. Set resource limits for production services. Configure memory and CPU limits to prevent a single service from consuming all available resources. This protects other services in the same project from resource starvation.

4. Keep deployment logs accessible. Use railway logs --tail during deployments to catch startup errors immediately. Set up log drains to an external service for persistent log storage beyond Railway's retention period.

5. Test rollback procedures before you need them. Practice rolling back a deployment on staging so the team knows the process. In an incident, you want muscle memory — not a frantic search through documentation.

Common Issues

Deployment succeeds but app returns 502. The process started but isn't listening on the correct port. Railway injects PORT as an environment variable — ensure your app binds to process.env.PORT, not a hardcoded port. Check railway logs for startup errors that might prevent the server from binding.

Health check times out during deployment. Increase healthcheckTimeout if your app needs more than 30 seconds to start (common with large Node.js builds or Java apps). Also verify the health check endpoint doesn't depend on services that aren't ready yet — use a basic /health that returns 200 without database checks during startup.

Environment variables missing after deployment. Railway variables are scoped to environments. If you added variables in staging but deployed to production, they won't be present. Use railway variables --environment production to verify. Consider using a shared variable group for values common across environments.