Tesria

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:

  • 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. It does nothing until COLLAB_SHARED_SECRET is set.

  • pdf: turns pages into PDF files. PDF export stays off until PDF_SHARED_SECRET is set.

  • 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.

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.

On disk each name starts with tesria_, 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 and every backup on this machine. 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: Make your settings file

Tesria reads its settings from a file called .env in the Tesria folder. Start from the example that comes with it:

Bash / Shell
cp .env.example .env

Open .env in a text editor and set at least these. The example holds placeholders rather than blanks, so a value you forget does not stop Tesria starting: it just stays insecure.

  • POSTGRES_PASSWORD and APP_DB_PASSWORD: two different long random passwords for the database.

  • BACKUP_ENCRYPTION_KEY: a long random passphrase that encrypts the physical backups.

  • DOMAIN and ACME_EMAIL: the address people will open Tesria at, and an email address. localhost is fine to try it on one computer.

This makes a good random value; run it once for each:

Bash / Shell
openssl rand -hex 32

Every setting is explained in the Configuration reference.

Keep a copy of BACKUP_ENCRYPTION_KEY somewhere other than this computer, such as a password manager. The backups it encrypts cannot be restored without it, by anyone.

Step 2: Start everything

Bash / Shell
docker compose up -d --build

--build makes Tesria’s containers from the files in the folder, which takes a few minutes the first time. -d runs them in the background, so you get the terminal back.

While it starts, a few things happen on their own: 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: Check it is running

Bash / Shell
docker compose ps

Every line should say Up. The db, app, backup 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 4: 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

Applies to

Tesria 0.5 and later

Updated

September 24, 2026

Changes

Revised.