Tesria
Tesria.com

Installing with Docker Compose

Tesria is not one program but several that work together: the wiki itself, a database, a web server, and a few helpers. Docker runs each of them in its own container, a sealed box holding everything that program needs, so nothing else on the computer can clash with it. Docker Compose starts the whole set together, from one file called docker-compose.yml in the Tesria folder.

This page explains what each part does and where your data is kept, then walks through the first start. Quick start is the short version of the same steps.

What runs

When Tesria is running, docker compose ps lists these services:

  • init: makes and keeps Tesria’s passwords and keys on the first start, then stops; everything else waits for it.

  • app: Tesria itself, the pages you see and the API behind them.

  • db: PostgreSQL 18, the database. It holds pages, comments, accounts and settings: everything except uploaded files.

  • caddy: the web server in front. It looks after HTTPS (the padlock in the address bar) and is the only part other computers can reach, on ports 80 and 443.

  • collab: lets several people edit the same page at once.

  • pdf: turns pages into PDF files.

  • backup: copies the database and every attachment on a schedule, and sends copies offsite if you set that up.

  • pgbackrest: keeps physical backups of the database and a running record of every change, which is what lets you restore to any moment.

  • backup-nas and backup-removable: copy the backups to a network drive or a removable drive, if you set those up. Each drive has a service of its own, so a drive that is missing stops only its own service, never the backups on this computer.

Where your data lives

Containers are thrown away and made again on every upgrade, so your data is not kept in them. It is kept in Docker volumes, storage areas Docker looks after separately, which survive stopping, restarting and rebuilding:

  • pgdata: the database.

  • uploads: attachments, meaning the images, files and videos added to pages.

  • backups: the database dumps and attachment archives the backup service takes.

  • pgbackrest: the physical backups and the record of changes, encrypted.

  • caddy_data: the HTTPS certificates, including the certificate authority behind the local certificate.

  • secret_postgres_password, secret_app_db_password, secret_backup_key, secret_collab and secret_pdf: the passwords and keys init made or stored, one in each. The database and the backups cannot be opened without them.

On disk each name starts with the Compose project’s name, tesria unless you set COMPOSE_PROJECT_NAME, so the database’s volume is tesria_pgdata.

One command deletes all of them: docker compose down -v. The -v means “and the volumes”, which is the wiki, every backup on this machine, and the generated passwords and keys that open the database and the backups. Never run it. Plain docker compose down is safe. See Uninstalling and moving.

Before you start

  • Docker with Compose on the computer that will run Tesria. See Prerequisites and System requirements.

  • The Tesria folder, with docker-compose.yml in it. Quick start shows how to get it.

  • A terminal open in that folder. Every command on these pages is run from there.

Step 1: Choose your address, if you have one

There is no settings file to fill in: Tesria makes its own passwords and keys. Its settings live in an optional file called .env in the Tesria folder, and only for what you want to change. Without one, the address is localhost, which is fine to try Tesria on one computer or to run it on your own network (see HTTPS and domains).

If a web address such as wiki.example.com points at this computer, tell Tesria before the first start, so it can get a certificate for it. On a Mac or Linux:

Bash / Shell
echo DOMAIN=wiki.example.com > .env

On Windows: Set-Content .env 'DOMAIN=wiki.example.com'. Every other setting is optional, and explained in the Configuration reference.

Step 2: Start everything

Bash / Shell
docker compose pull docker compose up -d

pull downloads Tesria’s ready-made images for this release, which takes a few minutes the first time. -d runs them in the background, so you get the terminal back. If you cloned the repository to build from source instead, run docker compose up -d --build in place of both.

While it starts, a few things happen on their own: the init service makes Tesria’s passwords and keys and stops, the database starts, the pgbackrest service prepares its backup store, Tesria creates its tables and a restricted database account for itself, and Caddy makes a certificate for your address.

Start the whole set, not only the database. On a new install, docker compose up -d db on its own makes the database restart every few seconds, because it waits for the pgbackrest service to prepare the backup store. If you ever need the database without the rest, start the two together: docker compose up -d db pgbackrest.

Step 3: Save Your Backup Key

Tesria has written the key that encrypts your backups to a file called backup-key.txt in the Tesria folder, next to docker-compose.yml. Open it, and copy the key into your password manager, or anywhere that is not this computer.

Without this key, the continuous backup cannot be restored, by anyone. Once it is saved somewhere else, you may delete the file. While the computer is running, this prints the key again:

Bash / Shell
docker compose run --rm init show-backup-key

The setup wizard asks about the key too, and Administration keeps reminding you until someone says it is saved. If you chose the key yourself, as BACKUP_ENCRYPTION_KEY in .env, no file is written and nothing asks: you already have it.

Step 4: Check it is running

Bash / Shell
docker compose ps

Every line should say Up. The db, app, backup, backup-nas, backup-removable and pgbackrest lines add (healthy) once their own checks pass, which can take a couple of minutes for the backup services. Health checks and monitoring has more ways to check.

Step 5: Open it and create the owner

On this page, your-server stands for your server’s address: whatever you type into the browser to open Tesria, without https://. For example, if you open Tesria at https://wiki-server.local, then https://your-server/api/health means https://wiki-server.local/api/health.

Open https://your-server in a browser. A new Tesria has no accounts yet, so it opens the setup wizard: it creates the owner, the one account that owns this Tesria, then asks for its name, who can join, and how long to keep backups. See First-run setup wizard.

On your own network, the browser may warn that the connection is not private. Nothing is wrong: Trusting the local certificate explains why, and makes the warning go away.

Everyday commands

Run from the Tesria folder:

Command

What it does

docker compose ps

Lists the services and whether they are healthy

docker compose logs app

Shows Tesria’s log; add -f to follow it

docker compose restart app

Restarts Tesria

docker compose stop

Stops everything and keeps your data

docker compose up -d

Starts everything, with any change to .env

A second Tesria on the same computer

Docker Compose knows each Tesria by a project name, which is tesria for every Tesria folder unless its .env says otherwise. Two folders with the same name are one Tesria, not two: the second would take over the first one’s containers and data, and removing “the test copy” with docker compose down -v would delete the real wiki. Since 0.8.2 Tesria refuses to start a Tesria from a folder other than the one it was installed from, and says what to do.

For a second, separate Tesria, for example to try a new version beside the real one, unzip it into a folder of its own and, before its first start, give it its own name, network and ports in that folder’s .env:

Bash / Shell
COMPOSE_PROJECT_NAME=tesria2 TESRIA_SUBNET=10.204.0.0/24 TESRIA_HTTP_PORT=8080 TESRIA_HTTPS_PORT=8443

Then start it as above, and open it at https://localhost:8443. It has its own volumes (tesria2_pgdata and the rest), its own passwords, its own backup key and its own certificate authority, so a device that trusts the first one trusts this one separately, from its own guide at http://localhost:8080/trust. Links in its emails, such as password resets, carry its port too, so they open this Tesria and not the first. All four settings are in the Configuration reference.


Applies to

Tesria 0.5 and later

Updated

October 2, 2026

Changes

Revised.