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 first, with whichever of the two in Taking backups you use. 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.

The cost of the second command

The pull changed the sources, so the image is built from them again. On a small home machine that takes minutes rather than seconds, mostly to compile the interface, and Docker prints the build as it goes.

The instance keeps answering throughout, from the container still running the previous image. The only interruption is the swap at the end: for a few seconds the address answers nothing, while the new container starts and applies the new migrations.

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.

The line takes no focus, and it sits under the dialogs so it cannot cover a form being filled in. Its Later button dismisses it for good for that version, in this tab and in the next one. The reload it offers is 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.

The running version

Settings → About shows it, 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.

Today that is every update. The repository carries no tag and nothing has been released yet, so building from main is the only way to update, and you have to reload the tab yourself afterwards. The offer above starts working at the first released version, which is also when following the tags becomes an option.

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 just as big: close to 800 MB apiece. docker image prune removes the untagged ones and nothing else; no image a container is using is untagged.