Tesria
Tesria.com

Upgrading

An upgrade swaps Tesria’s software for a newer version and keeps everything you have written. A short setup step updates the database before the new version starts, so there is nothing to convert by hand. It takes a few minutes, most of them while the old version keeps running.

Before you start

  • Read the Release notes for every version between yours and the new one. They say what changed and anything you need to do.

  • Pick a quiet time. Tesria is unavailable for about a minute, and people with a page open may need to reload it.

Step 1: Take a backup

Choose Admin, then Backups, then Back Up Now, and wait until the page says the backups have finished. If the upgrade goes wrong, this is what you go back to. See Backups and recovery.

Step 2: Get the new version

If you installed Tesria from tesria-deploy.zip, as Quick start does, download the new one and unzip it over your Tesria folder. Your .env, if you have one, is kept: it is not in the zip. In the folder above your Tesria folder, on a Mac or Linux:

Bash / Shell
curl -LO https://github.com/Tesria/Tesria/releases/latest/download/tesria-deploy.zip unzip -o tesria-deploy.zip -d tesria

On Windows, in PowerShell:

powershell
Invoke-WebRequest https://github.com/Tesria/Tesria/releases/latest/download/tesria-deploy.zip -OutFile tesria-deploy.zip Expand-Archive tesria-deploy.zip -DestinationPath tesria -Force

If you cloned the repository to build from source, run git pull in the Tesria folder instead.

Upgrading from a version before 0.8.0? There is nothing extra to do. Keep your .env: its values win, and Tesria stores them for itself from then on. If it still has a change-me value from the old example settings, Tesria starts anyway and warns you; see Security hardening, under Changing a secret.

Upgrade in your Tesria folder, not a new one. A Tesria last started by a version before 0.8.2 does not know its folder yet. The first start of 0.8.2 or later records it, and only a folder that holds its backup-key.txt or its passwords in .env is accepted without asking. If you deleted backup-key.txt after saving the key, the start stops and says so: run docker compose run --rm init use-this-folder in your Tesria folder, then docker compose up -d. To try a new version beside the old one, give the new copy its own name, network and ports first: see A second Tesria on the same computer in Installing with Docker Compose.

Moved Tesria to other ports with a docker-compose.override.yml? Since 0.8.2, TESRIA_HTTP_PORT and TESRIA_HTTPS_PORT in .env do this, and only then do the Trust This Device page, the redirect from http to https, links in email and the Windows real-addresses setup know the ports. Remove the ports lines from the override file, set the two settings to the same numbers, and run docker compose up -d. See Configuration reference.

Step 3: Restart on the new version

In the Tesria folder:

Bash / Shell
docker compose pull docker compose up -d

The new images download while the old version keeps running. Then the setup step (the migrate service) updates the database, each container is replaced, and Tesria is back. Since 0.7.3 migrate keeps running afterwards: it does the same for a restored backup, so it is meant to be there. From a clone, run docker compose up -d --build instead, which builds first.

Some upgrades ask for one more step. The Release notes say when, for example to run docker compose down and then docker compose up -d once. Never add -v to down: that deletes the wiki, its backups, and the generated passwords and keys that open them.

Step 4: Check it

Open Admin, About (Admin is in the top bar; in a narrower window or on a phone it is in the ☰ menu at the left of the top bar, and a tab that does not fit is under ••• at the end of the tabs): it names the version now running (so does /api/health, while you are signed in). docker compose ps should show every service Up.

If something goes wrong

The logs usually say why. The first shows the setup step that updates the database, the second Tesria itself:

Bash / Shell
docker compose logs migrate docker compose logs app

Going back means restoring the backup you took in step 1 with the version you had before. Putting back only the older files is not enough: the database has already been updated, so the older version will not start on it, and docker compose logs migrate says so. (Versions before 0.8.6 started on it anyway, which could go wrong in ways nothing repairs.) Restore the step 1 backup from the command line, as Restoring and undo describes, then run docker compose up -d again. A backup made by a newer Tesria cannot be restored into an older one: it is refused, because the older version would not understand it.


Applies to

Tesria 0.5 and later

Updated

October 2, 2026

Changes

Revised.