Zero-Downtime Deploys Explained: How Neo's Blue-Green Switch Works

The sequence

Every redeploy follows the same steps, whether it's your second deploy or your two-hundredth:

1. Start the new container alongside the old one, named app-<name>-next
2. Wait for it to pass its health check (TCP connectivity, or an HTTP check if health: is configured)
3. Run any release: commands inside it
4. Switch Caddy's route from the old container to the new one — traffic moves instantly
5. Stop and remove the old container
6. Rename the new container to the canonical name

If step 2 or step 3 fails, Neo removes the new container and stops. The old one was never touched — it's still running, still serving, and you get a clear error instead of a broken deploy.

Why this matters for command:

A container whose command: exits immediately fails step 2 by definition — there's nothing running to health-check. The rollback still happens correctly; it just means the failure you see is "health check failed" unless Neo's built-in diagnosis catches the likely cause.

Configuring the health check

health:
  cmd: "curl -f http://localhost:8080/health"
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

Without this, Neo checks TCP connectivity on the container's port — enough to know the process is listening, not that it's actually healthy. An HTTP check catches an app that starts but immediately errors on every request.

What this guarantees, and what it doesn't

Zero-downtime here means no dropped requests during the switch — Caddy doesn't route to the new container until it's confirmed ready, and doesn't stop routing to the old one until then either. It does not mean zero risk: a migration that changes the schema in a way the old code can't read will still break the old container for the brief window before the switch, which is one more reason release: running before the switch — not after — is the right order.