Zero-downtime deploys on a single server

The naive approach and why it hurts

`docker stop && docker run` is a deploy with a hole in it: every request between stop and ready gets a connection error, and if the new image is broken you are down until you notice and fix it.

The pattern

• Build the new image on the server so the architecture always matches.
• Start it alongside the current container on a second internal port.
• Poll its health endpoint until it reports ready, with a timeout.
• Switch the reverse proxy to the new port and let in-flight requests drain.
• Keep the previous container around long enough to roll back instantly.

What a good health check asserts

A health endpoint that returns 200 unconditionally protects you from nothing. It should confirm the things that actually break on deploy: the database connection, required environment variables, and any migration the release depends on.

app.get("/healthz", async (_req, res) => {
  try {
    await db.query("select 1");
    res.status(200).json({ status: "ok" });
  } catch {
    res.status(503).json({ status: "degraded" });
  }
});

Migrations are the hard part

During the swap both versions run briefly, so schema changes must be backwards compatible: add columns before you use them, backfill separately, and only drop the old column in a later release. Expand, migrate, contract.

Automatic rollback

If the health check never passes within the timeout, the deploy is abandoned and the old container keeps serving. Nobody sees the failure but you — and the logs from the failed container are still there to explain why.

Where this runs

This is the default deployment path in Cheaploy on your own Oracle Always Free VM: build on the instance, health-check gate, proxy swap, retained previous release, one-click rollback.