Keeping Tandem up to date¶
Tandem does not update itself. This page covers how you find out a new version exists, how to apply it, how to undo it if it goes wrong, and the two other pieces — the transcription worker and the Android app — that can drift out of step with the server.
Where releases come from¶
Every Tandem release is a tagged commit with a GitHub Release built from it:
github.com/jlafuenti/Book-Sync/releases. The
release notes are the version's section of CHANGELOG.md, so they say exactly what changed,
what (if anything) an operator has to do, and whether a database migration is involved. A commit
landing on main is not a release — only a published, tagged version shows up here or anywhere
else Tandem looks for updates.
Know when there is one¶
System → Updates, on the admin System page. The first time an admin opens it, it asks plainly: "Check for updates automatically?" — with Enable and No thanks. Nothing is checked before you answer, because the check means the server calling out to GitHub, and Tandem does not make an outbound call nobody asked for.
Turn it on and the server asks GitHub for the latest published release every few hours. GitHub sees the server's own address and nothing else — no library contents, no usage, no user data. When what GitHub reports is newer than the version you are running, the card says so:
Tandem 0.6.0 is available — you're running 0.5.1. [Release notes]
That is as far as it goes. There is no "update now" button — applying it is always a step you take by hand, which is what the rest of this page covers. You can turn the check off again from the same card at any time.
Upgrade the server¶
Take a backup first, from System → Backups. It costs a minute and it is what makes every other step in this page reversible; skip it and a rollback is guesswork instead of a restore.
Two ways to move to a new version, depending on how you run the stack:
Build from source at the tag, if your compose file builds the images itself:
git fetch --tags
git checkout v0.6.0
docker compose up -d --build
Pull the published image, if your compose file names one instead of building it (image:
rather than build:):
docker compose pull
docker compose up -d
Pin an actual version tag rather than latest on a server you depend on — latest tracks
whatever was published most recently, which is fine for trying Tandem out but not for something
you rely on.
Either route, the server applies its own database migrations as it starts up, before it begins serving requests — there is no separate migration step. If a migration fails, the server deliberately stops rather than run against a half-migrated database; check the log first if that happens. The one exception, covered in the operations reference below, is a very old install that predates Tandem's migration tooling: it needs a one-time stamp before its first migrated upgrade.
Roll back¶
If nothing has gone right, undo it. When the release you are backing out of ran no migration, this is the whole procedure:
git checkout v0.5.1 # the tag you were on before
docker compose up -d --build
When it did run a migration, the schema is now ahead of the older code: check out the tag first, then either downgrade the schema to the revision that code expects, or restore the backup you took before upgrading. A restored backup already carries the schema it was taken at, so do not migrate it again afterward. The full decision tree is in the operations and release docs below.
Keep the worker in step¶
If you run a separate transcription worker (a Jetson Orin Nano or similar), it has its own version and does not upgrade when the server does. The server asks the worker what it is running and, when the worker has fallen behind, the same System → Updates card says so:
The transcription worker is on 0.5.1 — this server is 0.6.0.
Upgrade it the way you deployed it in the first place: on the worker's own host, check out the matching tag and rebuild.
git fetch --tags && git checkout v0.6.0
docker compose up -d --build
A worker briefly ahead of the server is normal mid-upgrade and is not flagged — it is the server's turn to catch up, not a problem with the worker.
The apps¶
The Android app updates on Google Play's own schedule, independent of your server — there is nothing to do on your side for it. The web app is served by your server directly, so it is already current the moment you finish upgrading the server stack; there is no separate web deployment step.
Because the two update independently, an app and a server can briefly disagree about the API they speak. Both sides report a version number, and when they are far enough apart to matter, whichever one is behind shows a banner saying so — "update the app from Play," or "ask your server admin to upgrade." Most of the API keeps working either way; it is a warning, not a wall, and it clears itself once both sides catch up.