Tesria
Tesria.com

When the machine is gone

The server is broken, stolen or will not start, and all you have is an offsite copy. This page takes you from there back to a working wiki on another computer. Read it through once before you start, and keep going step by step: nothing here can make things worse, because the offsite copy is only ever read.

What you need

  • The passphrase of the copy you have: OFFSITE_CLOUD_PASSPHRASE, OFFSITE_NAS_PASSPHRASE or OFFSITE_REMOVABLE_PASSPHRASE, from wherever you kept it. Without it the copy cannot be read, and there is no way around that.

  • Access to the copy: the cloud account’s key and secret, or the drive or share itself.

  • The old backup key, BACKUP_ENCRYPTION_KEY, from wherever you kept it. If the old Tesria made its key itself, it is the one the owner saved from backup-key.txt.

  • A computer with Docker and room for the wiki. See Prerequisites.

You get back every page, every attachment and every account. You do not get back .env or the old server’s passwords and keys, which are in no backup: the new Tesria makes its own, except the backup key, which you bring.

Step 1: Look at what the copy holds

The copies are standard restic repositories: restic and the passphrase read them on any computer, with no Tesria involved. Docker runs restic for you. For a drive or share, use the path it is at on this computer:

Bash / Shell
docker run --rm -e RESTIC_PASSWORD=your-passphrase -v /Volumes/your-drive:/t restic/restic -r /t/restic snapshots

For the cloud copy, with your own endpoint, bucket and path:

Bash / Shell
docker run --rm -e RESTIC_PASSWORD=your-passphrase -e AWS_ACCESS_KEY_ID=key -e AWS_SECRET_ACCESS_KEY=secret restic/restic -r s3:https://endpoint/bucket/tesria/files snapshots

Each line it lists is a copy, with its date. The newest is the one to restore.

Step 2: Install an empty Tesria

Get Tesria as in Quick start, but before the first start, make a .env in the Tesria folder with the old backup key in it:

Bash / Shell
BACKUP_ENCRYPTION_KEY=the-old-backup-key

That one line is enough: Tesria makes everything else fresh. Add a DOMAIN line too if you want the same address as before. Do not let the new Tesria make a new backup key, which could not read the old backups. Then start it:

Bash / Shell
docker compose pull docker compose up -d

Wait until docker compose ps shows app as healthy. Do not go through the setup wizard: the restore replaces everything anyway.

Step 3: Take the newest backup out of the copy

This writes it into a folder called restored inside the Tesria folder. For a drive or share:

Bash / Shell
docker run --rm -e RESTIC_PASSWORD=your-passphrase -v "$PWD/restored:/out" -v /Volumes/your-drive:/t restic/restic -r /t/restic restore latest --target /out

For the cloud copy:

Bash / Shell
docker run --rm -e RESTIC_PASSWORD=your-passphrase -e AWS_ACCESS_KEY_ID=key -e AWS_SECRET_ACCESS_KEY=secret -v "$PWD/restored:/out" restic/restic -r s3:https://endpoint/bucket/tesria/files restore latest --target /out

Either way, restored/backups/ now holds the dumps and their attachment archives.

Step 4: Restore it

Copy them into the new Tesria’s backup service, and list them:

Bash / Shell
docker compose cp restored/backups/. backup:/backups/ docker compose exec backup ls /backups

Restore the newest of the dumps you copied in, by its name, then restart Tesria so it picks it up:

Bash / Shell
docker compose exec backup /scripts/restore.sh db-<time>.dump docker compose restart app docker compose restart collab

Use the dump’s real name in place of db-<time>.dump. The script also puts back the attachments archived with it.

Not the newest dump in the list. The new Tesria backed itself up when it first started, so the newest db-<time>.dump in the list is its own empty wiki. Restoring it by name restores nothing you want. Run without a name, restore.sh passes over it and restores the newest dump that holds accounts.

Step 5: Check it

In this order, because each proves something different:

  1. Sign in with your old account.

  2. Open a page with a picture on it. That proves the attachments came back, not only the database.

  3. Under Admin, Backups, check that both backup services are healthy.

Step 6: Before calling it done

  • Take a new backup straight away, and check the retention policy, which came back with the wiki.

  • Set up an offsite copy for the new computer, as in Offsite copies. The copy you restored from belonged to the old one.

  • A week later, check that the restore drill has run on the new computer. Until it has, nothing has proved the new copies can be restored.

  • If people used the local certificate, each device trusts the new server again: see Trusting the local certificate.

To a moment in time, from the cloud

The steps above bring the wiki back as it was at its newest nightly backup. The cloud copy can also go back to a chosen minute, because it holds the database’s record of changes. That needs the original BACKUP_ENCRYPTION_KEY as well as the cloud passphrase, and is a job for someone comfortable with PostgreSQL: the steps are in docs/backup-recovery.md in Tesria’s source code, at github.com/Tesria/Tesria.


Applies to

Tesria 0.5 and later

Updated

September 30, 2026

Changes

Revised.