Updating a self-hosted EntryWick (week 21)

How a self-hosted instance learns about a new release, how to install it with entrywick update, and what happens when an update fails. PRICING_ENTITLEMENTS §5, ADR-019, ADR-020. The command's reference: cli.md.

Who opens it: whoever runs a self-hosted install, when the license banner or entrywick doctor says a new version is available.

What they came to do: move to the new release without putting an event at risk, and know what happens if it does not work.

What must be true when they leave: the instance runs the newest release signed for its license's channel — or, when the update failed, the release it ran before, with its data — and they know which of the two it is.

Channels

The license key names an update channel. Changing it needs a new key from EntryWick.

An install on stable never runs a beta: entrywick refuses one (exit 5).

How a new release is found

• The nightly heartbeat (03:45 UTC, heartbeat.md) brings back the newest version on each channel.
• Owners and Admins then see a quiet line in the admin's license banner, and entrywick doctor warns update_available … is available: entrywick update.
• entrywick update --check asks now (it sends a heartbeat first) and says X.Y.Z is available on the stable channel (this is …). Run entrywick update., or that the instance is already on the newest.

entrywick update installs the version the heartbeat named — never one the license server has not announced, unless you name it with --to=X.Y.Z. It never goes to an older version.

Signatures

Every release is signed by EntryWick's release workflow, once for each channel it is on. Before it pulls anything, entrywick update checks with Sigstore's cosign that the release was signed for your license's channel by that workflow, then pulls and runs exactly the image that was signed (by its digest, in /opt/entrywick/.env.version). A release that is not signed for the channel is refused and nothing is pulled (exit 5). The details: cli.md.

Updating

1. Pick a time with no live event. An update restarts the app, and a failed one can put the database back to a backup taken minutes before (below). entrywick update refuses while an event is live unless told --force.
2. Check the instance first:

   entrywick doctor
   

   Fix any FAIL before updating; the update needs a healthy app to back up.
3. Start it inside tmux, so a dropped connection does not cut it short:

   tmux
   entrywick update
   

   (apt-get install -y tmux if it is missing.) If the connection drops, log in again and run tmux attach to see it carry on.
4. It reads the license, checks the target's signature, and asks Update from 1.0.0 to 1.0.1? A backup is taken first, and the app restarts. (y/N). Answer y.
5. It then backs up (the same backup as entrywick backup, backup.md), pulls the release, swaps in its Compose files, starts it, migrates the database, re-seeds EntryWick's own roles, plans and event templates, rebuilds the live counters, restarts Horizon, and waits up to three minutes for everything to answer.
6. It ends Updated from 1.0.0 to 1.0.1. The backup taken first is 20270215-021500. Run entrywick doctor once more.

During the minute or two the app restarts, pages may not load. Paired scanners keep scanning and upload their queue when the app is back; the app is never put into maintenance mode.

Options: --to=X.Y.Z (a release other than the newest announced), --check (only say whether one is available), --force (update although an event is live), --yes (do not ask; needed when there is no terminal).

The entrywick command is not replaced by an update. To use a newer tool, download it as in install.md, step 6.

When the update refuses

Nothing on the instance has changed in any of these.

When an update fails

A failure after the pull — the new release does not start, a migration fails, or it is not healthy within three minutes — rolls back by itself:

1. the previous Compose files and .env.version go back, and the previous release starts again;
2. only if the failed release's migrations changed the database, the database is restored from the backup taken at the start of the update. Migrations only go forward, so the previous release cannot run on the newer tables. What was written between that backup and the rollback — registrations, check-ins, changes — is lost. When the failed release did not change the database, it is kept as it is, with nothing lost;
3. stored files are left as they are; a file the failed release wrote is harmless.

It ends Rolled back to 1.0.0 …. The update did not go through: … and exits 10. The instance runs the release it ran before. Send EntryWick the output.

If the previous release does not come back healthy either, it exits 11: The rollback did not finish: …, and names the backup taken before the update. Run entrywick doctor; if the database is the problem, restore that backup with entrywick restore <backup> (backup.md).

An update cut short

If the update stops in the middle — the connection dropped without tmux, the server restarted — the next entrywick update refuses:

error: An update from 1.0.0 to 1.0.1 did not finish (it stopped at: migrate). Run entrywick update --rollback to put 1.0.0 back.

and entrywick doctor fails with an update did not finish. Run:

entrywick update --rollback

It rolls back exactly as above (the database only if the update had started migrating and changed it), and exits 10. Then update again.

Exit codes of entrywick update