Skip to content
quest'n'click

Clever CloudExplanationFor adminsApplies from 4.2.3

Redeploys

Cette page en françaisThis page on the GitHub wiki

On Clever Cloud a deploy (or a push, or clever restart) starts the new instance while the old one still serves. The Studio Server is built for that overlap: no write is lost, but writes are slow or refused for about a minute. This page says why, what was measured, and how to deploy so that members are not surprised.

Why

Spike S measured it on 17 October 2026: during clever restart --without-cache, the new instance started while the old one still answered, and the old one never logged a SIGTERM. Two instances writing the same game at once would corrupt its history, and waiting for a signal that does not come would stall the switch. So:

  • The instances share a service lease in PostgreSQL: one holds it and serves writes. It lasts 30 s and is renewed every 10 s on the database's clock; an instance that cannot renew stops writing by its own clock before the 30 s can pass.
  • The new instance starts, answers /startz (Clever's health check, CC_HEALTH_CHECK_PATH=/startz), then waits: /readyz is 503 ("writes":"waiting") and its writes are 503 with Retry-After: 2 ("this instance does not serve writes yet; try again").
  • The handoff (since 4.2.3). Once it listens, the new instance asks for the lease; the holder gives it back at its next renewal (10 s at most) and logs {"event":"lease-lost",…}; the new one logs {"event":"lease-taken",…}. An older instance never takes the lease back from a newer one.
  • A client retries a refused write with the same operation id (X-Studio-Op) and it is applied once. The journal's own fenced lease still keeps two instances from writing over the same head.

What was measured

Clever Cloud keeps the old instance STOPPING for about two minutes, still receiving requests until the deploy ends, and it logs no stopping line.

In all, about a minute of slow or refused writes per deploy, none lost.

While both instances run they hold twice the connections: on the PostgreSQL DEV plan (5) background work fails with "too many connections" during each deploy, and an older version's write could fail with it (a 500). Take a larger plan for a deployment people use (Apps and add-ons).

Deploying without surprising the team

Verified on: 19 October 2026 (the measures above; engine commits before the 4.2.3 tag, package.json 4.2.2). This page's text itself is not verified on a live installation.

  1. Tell the members, or pick a quiet moment: about a minute of slow writes; about two and a half minutes of refused writes for the first deploy onto 4.2.3 or later from an older version.

  1. Deploy from your machine, in the engine repository, the worker first when both change:

    # on your machine, in the engine repository
clever deploy --alias my-game-worker
clever deploy --alias my-game-studio

  1. Watch /readyz come back to 200 and the lease-taken line (its instance is the new one):

    # on your machine
until curl -sf https://studio.example.fr/readyz; do sleep 2; done
  1. Make one write (a note) and see it saved, at the next revision.

Alternatives set aside

  • Relying on SIGTERM to hand the lease over: Clever never delivered it observably (spike S, the reference deployment).
  • Stopping the old instance first (clever stop, then deploy): a minute or more with no Studio at all. Kept for one case only, a migration that changes what the old version reads (Upgrading the server).
  • Several instances serving at once: the journal needs one writer per game.

Trade-offs

The handoff shortens the refused window from minutes to seconds, but Clever's routing to the old instance until the deploy ends keeps 10 to 16 s of 503. A /readyz alert must tolerate that (Monitoring).

Decisions and ADRs