Zero-Downtime Deployments in Node.js: Blue-Green, Rolling, and Canary Explained
Every production deployment is a bet. You’re betting that your changes are correct, your infrastructure will cooperate, and your users won’t notice anything happened. Most of the time, the bet pays off. But when it doesn’t — when a bad deploy takes down your Node.js service at 2 PM on a Tuesday — the cost is real: lost revenue, damaged trust, and a team scrambling to roll back.
Zero-downtime deployment removes the bet. Instead of replacing your running service with the new version and hoping for the best, you introduce the new version alongside the old one, validate it, and shift traffic gradually. If something breaks, you catch it early and reverse — before your users do.
This guide covers three production-ready strategies: blue-green, rolling, and canary deployments. We’ll look at when to use each, how to implement them for Node.js specifically, and what you need to have in place for any of them to work.
Why Node.js Deployments Fail (And When)
Before the strategies, let’s be clear about the actual failure modes:
Process crashes on startup. Your new version has a syntax error, a missing environment variable, or a database migration conflict. The old process is gone, the new one won’t start, your load balancer is routing to nothing.
Graceful shutdown not implemented. Your deployment kills the old process mid-request. Active HTTP connections get dropped. In-flight jobs are lost.
Health checks that lie. Your new version responds 200 OK on /health but has a broken connection to its database. Traffic is routed to it. Errors spike.
Memory leaks in new code. The new version looks fine for 10 minutes, then memory climbs. By the time you notice, every instance is affected.
Zero-downtime strategies solve the first two directly. The other two require proper health checks and monitoring — which you need regardless of deployment strategy.
Prerequisites: What Every Strategy Requires
You cannot do zero-downtime deployments without these:
1. A working health check endpoint
// app.js
app.get('/health', async (req, res) => {
const checks = {
status: 'ok',
uptime: process.uptime(),
timestamp: new Date().toISOString(),
db: await checkDatabase(),
memory: process.memoryUsage().heapUsed / 1024 / 1024
};
const isHealthy = checks.db === 'connected' && checks.memory < 400; // MB
res.status(isHealthy ? 200 : 503).json(checks);
});
async function checkDatabase() {
try {
await pool.query('SELECT 1');
return 'connected';
} catch {
return 'disconnected';
}
}
2. Graceful shutdown
// Handle SIGTERM (sent by process managers and orchestrators)
process.on('SIGTERM', async () => {
console.log('SIGTERM received — starting graceful shutdown');
// Stop accepting new connections
server.close(async () => {
// Wait for in-flight requests to complete
await drainConnections();
// Close database connections
await pool.end();
console.log('Graceful shutdown complete');
process.exit(0);
});
// Force kill after 30 seconds if something hangs
setTimeout(() => {
console.error('Graceful shutdown timed out — forcing exit');
process.exit(1);
}, 30000);
});
3. A load balancer or reverse proxy
NGINX, HAProxy, AWS ALB, Cloudflare, or your PaaS provider’s built-in routing — you need something sitting in front of your Node.js instances that can be told “route traffic here, not there.”
With these in place, let’s look at the strategies.
Strategy 1: Blue-Green Deployment
The concept: Maintain two identical production environments — “blue” (current live) and “green” (new version). Deploy to green, validate it fully, then switch all traffic from blue to green in a single step. Blue becomes your instant rollback.
Before deploy: [Users] → [Load Balancer] → [Blue: v1.2.3] [Green: idle]
Deploy to green: [Users] → [Load Balancer] → [Blue: v1.2.3] [Green: v1.3.0 ← deploying]
After validation: [Users] → [Load Balancer] → [Blue: v1.2.3] [Green: v1.3.0 ✓]
Switch traffic: [Users] → [Load Balancer] → [Blue: v1.2.3] [Green: v1.3.0 → LIVE]
Implementing blue-green with PM2 + NGINX:
# ecosystem.config.js defines both environments
// ecosystem.config.js
module.exports = {
apps: [
{
name: 'app-blue',
script: './dist/server.js',
instances: 2,
env: { PORT: 3000, NODE_ENV: 'production' }
},
{
name: 'app-green',
script: './dist/server.js',
instances: 2,
env: { PORT: 3001, NODE_ENV: 'production' }
}
]
};
# nginx.conf
upstream active_app {
server localhost:3000; # Blue: change to 3001 to switch to Green
}
server {
listen 80;
location / {
proxy_pass http://active_app;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
}
location /health {
proxy_pass http://active_app/health;
access_log off;
}
}
Deployment script:
#!/bin/bash
# deploy-blue-green.sh
NEW_VERSION=$1
CURRENT=$(cat /var/app/active-slot) # "blue" or "green"
NEW_SLOT=$([ "$CURRENT" = "blue" ] && echo "green" || echo "blue")
NEW_PORT=$([ "$NEW_SLOT" = "blue" ] && echo "3000" || echo "3001")
echo "Current: $CURRENT | Deploying to: $NEW_SLOT (port $NEW_PORT)"
# 1. Pull new code and build
git pull origin main
npm ci --production
npm run build
# 2. Start the new slot
pm2 start ecosystem.config.js --only "app-$NEW_SLOT"
# 3. Wait for it to be healthy
echo "Waiting for $NEW_SLOT to become healthy..."
for i in {1..30}; do
STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$NEW_PORT/health)
if [ "$STATUS" = "200" ]; then
echo "Health check passed"
break
fi
echo "Attempt $i: status $STATUS — waiting..."
sleep 2
if [ $i -eq 30 ]; then
echo "Health check failed after 60s — aborting"
pm2 stop "app-$NEW_SLOT"
exit 1
fi
done
# 4. Switch NGINX traffic to new slot
sed -i "s/server localhost:[0-9]*/server localhost:$NEW_PORT/" /etc/nginx/conf.d/app.conf
nginx -t && nginx -s reload
# 5. Record the switch and stop old slot
echo "$NEW_SLOT" > /var/app/active-slot
sleep 5
pm2 stop "app-$CURRENT"
echo "Deploy complete. Active: $NEW_SLOT ($NEW_VERSION)"
When to use blue-green:
- You need instant, complete rollback capability
- Your migrations are additive (blue and green can share a database)
- You can afford to run double infrastructure (even briefly)
- You’re on a PaaS that supports slot-based deployment (Railway, Render, Azure App Service)
When not to: If your database schema changes are destructive (column drops, renames), blue-green is tricky — old blue can’t run against green’s schema. Use expand-contract migrations.
Strategy 2: Rolling Deployment
The concept: Replace instances of the old version one by one (or in small batches), while keeping the remaining old instances live. At any point during the rollout, both versions are serving traffic simultaneously.
Start: [v1][v1][v1][v1]
Step 1: [v2][v1][v1][v1] ← replace 1 instance
Step 2: [v2][v2][v1][v1] ← replace 1 more
Step 3: [v2][v2][v2][v1] ← replace 1 more
Done: [v2][v2][v2][v2] ← all updated
Implementing rolling updates with Kubernetes:
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: node-app
spec:
replicas: 4
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1 # Add 1 new pod before removing old
maxUnavailable: 0 # Never remove old until new is healthy
template:
spec:
containers:
- name: app
image: my-app:1.3.0
ports:
- containerPort: 3000
readinessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 10
periodSeconds: 5
failureThreshold: 3
livenessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 30
periodSeconds: 10
lifecycle:
preStop:
exec:
command: ["/bin/sh", "-c", "sleep 5"] # Drain in-flight requests
# Deploy with rollout monitoring
kubectl set image deployment/node-app app=my-app:1.3.0
kubectl rollout status deployment/node-app --timeout=5m
# Rollback if something goes wrong
kubectl rollout undo deployment/node-app
Implementing rolling updates with PM2 (no Kubernetes):
PM2’s built-in rolling restart handles this elegantly:
# Zero-downtime reload — restarts workers one at a time
pm2 reload ecosystem.config.js --update-env
# Or just the app name
pm2 reload app-name
What PM2 does: sends SIGINT to the first worker, waits for it to drain and exit, starts a new worker, waits for it to be ready, then moves to the next — while all other workers keep serving traffic.
When to use rolling:
- Multiple instances of the same service (standard for any production service)
- You’re already using Kubernetes, Docker Swarm, or PM2
- Database changes are backward-compatible with the old version
- You want fine-grained control over rollout speed
Key consideration: During a rolling deploy, v1 and v2 are simultaneously live. Your API changes must be backward-compatible. Adding a new optional field is fine. Removing a field that v1 uses is not.
Strategy 3: Canary Deployment
The concept: Route a small percentage of real traffic (5–10%) to the new version. Monitor error rates, latency, and business metrics. If healthy, gradually increase the percentage. If not, route all traffic back to the old version.
Canary phase: [Users] → 95% → [v1 fleet]
→ 5% → [v2 canary]
Monitor for 30min: errors? latency? business metrics? ✓
Expand to 25%: [Users] → 75% → [v1 fleet]
→ 25% → [v2 canary]
Expand to 100%: [Users] → 100% → [v2 fleet]
Implementing canary with NGINX weighted upstream:
upstream app_v1 {
server app-v1:3000 weight=95;
}
upstream app_v2 {
server app-v2:3000 weight=5;
}
# Custom upstream selection
split_clients "$request_id" $app_upstream {
5% app_v2;
* app_v1;
}
server {
location / {
proxy_pass http://$app_upstream;
}
}
Implementing canary with feature flags (code-level canary):
Sometimes you don’t need infrastructure-level traffic splitting — you can canary at the application level:
// middleware/canary.js
const CANARY_FEATURES = {
newCheckoutFlow: { percentage: 5, sticky: true },
improvedSearch: { percentage: 10, sticky: false }
};
function isInCanary(userId, feature) {
const config = CANARY_FEATURES[feature];
if (!config) return false;
// Sticky: same user always gets same experience
if (config.sticky) {
const hash = require('crypto')
.createHash('md5')
.update(`${userId}-${feature}`)
.digest('hex');
return parseInt(hash.slice(0, 8), 16) % 100 < config.percentage;
}
// Random: different on each request
return Math.random() * 100 < config.percentage;
}
// Usage in route handler
app.post('/checkout', (req, res) => {
if (isInCanary(req.user.id, 'newCheckoutFlow')) {
return newCheckoutHandler(req, res);
}
return legacyCheckoutHandler(req, res);
});
Monitoring during canary (the only thing that makes it useful):
// Track canary vs. control metrics
const { Histogram, Counter } = require('prom-client');
const requestDuration = new Histogram({
name: 'http_request_duration_ms',
help: 'HTTP request duration in milliseconds',
labelNames: ['method', 'route', 'status', 'version'],
buckets: [5, 10, 25, 50, 100, 250, 500, 1000]
});
const errorCounter = new Counter({
name: 'http_errors_total',
help: 'Total HTTP errors',
labelNames: ['route', 'error_type', 'version']
});
// Middleware
app.use((req, res, next) => {
const version = process.env.APP_VERSION || 'unknown';
const start = Date.now();
res.on('finish', () => {
const duration = Date.now() - start;
requestDuration.labels(req.method, req.route?.path || 'unknown', res.statusCode, version)
.observe(duration);
if (res.statusCode >= 500) {
errorCounter.labels(req.route?.path || 'unknown', 'server_error', version).inc();
}
});
next();
});
Compare version="v2" metrics against version="v1" in your dashboards. If error rate or p99 latency climbs, roll back.
When to use canary:
- High-risk changes (new payment flows, auth changes, database queries at scale)
- You want real production validation without full exposure
- You have observability in place to actually compare metrics
- Your changes affect a subset of users (A/B test territory)
Choosing the Right Strategy
|
Blue-Green |
Rolling |
Canary |
| Rollback speed |
Instant |
Minutes |
Instant |
| Infrastructure cost |
2x (brief) |
Normal + 1 instance |
Normal + small canary |
| Both versions live simultaneously |
No |
Yes |
Yes |
| Best for |
Major releases, DB migrations |
Standard weekly deploys |
High-risk or A/B changes |
| Requires |
Slot routing, 2x infra |
Orchestration (K8s, PM2) |
Traffic splitting + monitoring |
For most Node.js services:
-
Daily/weekly deploys: Rolling with PM2 or Kubernetes
-
Major releases: Blue-green with database expand-contract
-
Risky feature launches: Canary with observability
The One Tool to Add Right Now
Before any of these strategies work, your application needs to correctly report its own health. Run npx node-deploy-check in your project root to audit your production readiness:
It checks for missing health endpoints, graceful shutdown handlers, environment variable validation, and 12+ other production essentials — in under 5 seconds.
Final Thought
Zero-downtime deployment isn’t a luxury — it’s the baseline for any service people depend on. The implementation complexity is real, but the alternatives (maintenance windows, crossed fingers, midnight rollbacks) are worse.
Pick one strategy that matches your infrastructure. Implement it fully, including health checks and graceful shutdown. Run it on a staging environment until it’s boring. Then your production deploys will be, too.
Follow the AXIOM experiment at axiom-experiment.hashnode.dev — an autonomous AI agent building a business from scratch, documented in real time.
This article is part of the **Node.js in Production* series. Check out the companion tool node-deploy-check on npm.*
