06. Zero-Downtime Blue-Green & Shadow Canary GateCopy Anchor Link

Production Paradigm: Inode-Safe Caddy Config Reload + Next.js Server Action Hash Guard + Shadow Parity Traffic Mirroring + Canary Error Gate + Graceful HTTP Drain.

💥 The Real-World BottleneckCopy Anchor Link

Deploying modern full-stack web applications (especially Next.js App Router) on single VPS instances or container clusters frequently causes two notorious production failures:

1. The Next.js Server Action 404 Disaster:
   • When Next.js compiles a new release, it generates new unique hashes for Server Actions and client chunks (e.g., _next/static/chunks/app-123.js).
   • If a deployment restarts the container abruptly, active browser tabs clicking buttons submit requests to the old hash, resulting in Failed to find Server Action 404 errors.
2. The Inode Bind-Mount Race Condition:
   • Mounting a single Caddyfile or Nginx config as a Docker bind-mount (/etc/caddy/Caddyfile) breaks file-watch reloads when text editors or git overwrite the host inode. Caddy stops reloading changes cleanly.
3. 502 Bad Gateway During Container Restarts:
   • Dropping inflight HTTP and Server-Sent Event (SSE) requests when SIGKILL is sent before active sockets drain.

🏛️ High-Concurrency ArchitectureCopy Anchor Link

This blueprint implements a 7-tier zero-downtime rollout sequence using Caddy, Docker, and shadow canary verification.

Key Architectural PhasesCopy Anchor Link

1. Blue/Green Port Flipping:
   • Identifies the idle port (:3001 vs :3002) and launches the new build without touching the running container.
2. Shadow Parity Traffic Mirroring:
   • Mirrors a small percentage of live read requests into the staging container to verify real-world database queries and memory allocation before cutover.
3. Inode-Safe Caddy Zero-Downtime Reload:
   • Instead of single-file bind-mounting, Caddy mounts the parent folder. Reload is executed via caddy reload --config /etc/caddy/Caddyfile, preserving live TLS certificates and active TCP sockets.
4. Next.js Action Guard Dual Reverse-Proxy Routing:
   • Routes requests containing previous build action IDs to the graceful draining container during the transition period.
5. SIGTERM Graceful Socket Drain (setupGracefulShutdown):
   • Stops accepting new connections while allowing inflight long-polling and SSE streams up to 30 seconds to finish cleanly.

🧩 Composed Functional SlicesCopy Anchor Link

💻 Code ImplementationCopy Anchor Link

mkdir -p src/lib/deploy
cp packages/zero-downtime-deploy/src/graceful-shutdown.ts src/lib/deploy/
cp -r packages/zero-downtime-deploy/src/caddy-reload src/lib/deploy/
cp -r packages/zero-downtime-deploy/src/shadow-canary src/lib/deploy/

import http from 'http';
import { setupGracefulShutdown } from '@/lib/deploy/graceful-shutdown';

const server = http.createServer((req, res) => {
  // Application request handler
});

server.listen(3000, () => {
  console.log('Server running on port 3000');
});

// Register 30s connection drain
setupGracefulShutdown(server, {
  timeoutMs: 30000,
  onShutdown: async () => {
    console.log('Closing database connections and flushing buffers...');
    await db.$disconnect();
  },
});

#!/usr/bin/env bash
set -euo pipefail

# Determine idle port and start new container
ACTIVE_PORT=$(curl -s http://127.0.0.1:2019/config/apps/http/servers/srv0/routes/0/handle/0/upstreams/0/dial | grep -oE '[0-9]+' || echo "3001")
NEW_PORT=$([ "$ACTIVE_PORT" = "3001" ] && echo "3002" || echo "3001")

docker compose up -d --no-deps --build app_$NEW_PORT

# Run healthcheck
until curl -s -f "http://127.0.0.1:$NEW_PORT/api/health" > /dev/null; do
  sleep 1
done

# Atomic Caddy Config Reload
caddy reload --config /etc/caddy/Caddyfile

# Gracefully drain old container
docker stop --time 30 app_$ACTIVE_PORT

📊 Production Scale Benchmark & VerificationCopy Anchor Link