Zero-downtime deploys with rolling swaps

A deploy in dockxo is a job. It runs on the server’s agent, streams its log to the panel, and can be cancelled at any point. Here is the whole sequence for a GitHub service set to rolling.

1. Fetch and build

$ git clone --depth 1 -b main github.com/acme/shop-api
→ Dockerfile at ./Dockerfile, context ./
#4 [2/6] RUN npm ci --omit=dev
#4 CACHED

The agent clones the branch, optionally writes your env as a .env file into the build folder, and runs docker build. The previous image is kept, so unchanged layers come from cache. “Rebuild without cache” is a click away when you need a clean image.

2. Start next to the old one

→ starting api-a41f2c, waiting for :3000

The new container starts on the project network while the old one keeps serving. The agent waits for the container to accept connections on its port. A container that never answers is removed — it does not linger as a half-deployed ghost — and the deploy fails with the log in front of you.

3. Switch routes, then remove

✓ port check passed, routes updated
✓ old container removed — zero downtime

Once the port check passes, the agent rewrites Traefik’s routes with the new container’s IP. Traefik reloads; in-flight requests to the old container finish; new ones go to the new container. Only then is the old container removed.

When to use recreate instead

Recreate removes the old container before starting the new one. Use it for databases, anything that holds an exclusive volume lock, and services that publish a fixed host port. It is the default, precisely because it is the safe choice for stateful things.

Cancelling and history

Every deploy is listed with its commit message, sha, outcome and duration. A running deploy can be cancelled — the agent aborts the build, the clone or the helper container. If the panel itself restarts mid-deploy, the job is marked interrupted so you know to look.

From CI

curl -s -X POST -H "Authorization: Bearer $DOCKXO_TOKEN" \
  "$DOCKXO_PANEL/api/services/api.shop/deploy?wait=1"

With ?wait=1 the call returns when the deploy finishes, with the status and the full log, so a pipeline step can fail on a failed deploy.