Updating an instance

An ordinary update is two commands:

git pull
docker compose up -d --build

The application applies its own new migrations before it serves.

Danger

Take a backup before it, whichever of the two in Taking backups you keep. An update brings the migrations it needs, a migration rewrites your tables, and there is no undoing one.

Installing happens once, at First start. This is the part that repeats.

What the second command costs

Not the seconds a restart takes. The pull changed the sources, so the image is built from them again, which on a small home machine is minutes rather than seconds, most of it the interface being compiled, and Docker prints the build as it goes.

The instance keeps answering throughout, from the container still running the previous image. The interruption is the swap at the end: for a few seconds the address answers nothing, which is the new container starting and applying the new migrations before it serves.

The tab that is one visit behind

A browser that already had the instance open is one visit behind it, and now says so. Badlen registers a service worker, so a page load after an update comes from that browser’s own cache and is still the previous build, talking to an updated API. The open tab asks the instance which version it is serving, roughly every half hour and whenever the tab comes back to the foreground; when the answer is not the version the page itself was built from, one line appears at the bottom of the screen offering to reload.

It is an offer and never more than that. It takes no focus, it sits under the dialogs so it cannot land over a form being filled in, and its Later button sends it away for good for that version, in this tab and in the next one. The reload it offers is the one worth taking: it refreshes the service worker first, so the page that comes back is the new build rather than the cached one, and the session and the figures survive it. Ignoring it entirely costs nothing beyond staying on the old interface until the next reload.

Which version is running

Settings → About says so, on every installation. It reads the VERSION file committed in the repository, which the image carries, so it works on a build made from a downloaded source archive with no git history at all. That is the number to quote in a bug report. Between two releases it carries a -dev suffix, meaning a build made from main rather than from a tag; docker compose logs app still names every migration applied on the way up.

That suffix is also the limit of the offer above. The number moves when a release is cut, so two rebuilds from main between two releases carry the same version and an open tab has nothing to compare: it will not offer the reload, and a page load will still be answered out of the browser’s cache for that first visit. Following the tags is what makes an update announce itself; following main means reloading the tab yourself after an update, as before.

The image it replaced

Every update leaves the image it replaced on the machine, untagged, since only the tag moved to the new one, and as big as it is: close to 800 MB apiece. docker image prune takes the untagged ones away and nothing else; no image any container is using is untagged.

When the postgres image itself changes major version, this page is not enough: PostgreSQL major upgrade is the operation that is not a docker compose up.