Tesria
Tesria.com

Configuration reference

Tesria has two kinds of settings. The ones on this page live in the .env file in the Tesria folder: passwords, the address, backups. They are read when the containers start. Every one of them is optional: Tesria runs without a .env at all, and makes its own passwords and keys. The file is only for what you want to change.

Everything else, such as the wiki’s name, who can sign up and the email server, is changed in the browser, under Admin. See Settings (administration).

Changing a setting

  1. Open .env in a plain text editor. If there is none yet, make it: copy .env.example to .env (every line in it is commented out, so it changes nothing by itself), or start an empty file with that name.

  2. Change the line. Each is NAME=value, with no spaces around the =. A line that starts with # is a comment and is ignored, so to turn on a setting the example has commented out, delete the #.

  3. Save the file, and run docker compose up -d. It restarts the services whose settings changed and leaves the rest alone.

Bash / Shell
# Off: the # at the start makes the line a comment # OFFSITE_RETRY_MINUTES=15 # On OFFSITE_RETRY_MINUTES=30

On Windows, write a folder without quotes, or with forward slashes. Inside double quotes, a backslash starts a special character: in "C:\tesria\usb" the \t becomes a tab, and the folder is not the one you meant. Tesria refuses to start with a path like that and says which setting it is.

Bash / Shell
# Either of these OFFSITE_REMOVABLE_PATH=E:\TesriaBackups OFFSITE_REMOVABLE_PATH=E:/TesriaBackups # Not this: the \t becomes a tab OFFSITE_REMOVABLE_PATH="C:\tesria\backups"

If you choose a password or a passphrase yourself, make a long random one with:

Bash / Shell
openssl rand -hex 32

.env holds every secret you put in it. Never share it or put it in version control. Keep a copy of the backup key and passphrases somewhere that is not this machine: without them, the backups cannot be read.

Generated for you

Tesria makes these five on its first start, unless you set them, and keeps each one in its own Docker volume, given only to the services that need it: Tesria itself never has the database owner’s password or the backup key. A value set in .env always wins over the stored one. To change one later, see Security hardening, under Changing a secret.

  • POSTGRES_PASSWORD: the password of the database’s owner account. Only two things hold it: a short setup step that updates the database each time Tesria starts and then stops, and the backup services, which use it for backups and restores. Tesria itself never has it.

  • APP_DB_PASSWORD: the password of the restricted account Tesria runs as day to day, which cannot change or delete the audit log. Tesria creates that account itself, and when you change this setting, gives the account the new password by itself.

  • BACKUP_ENCRYPTION_KEY: encrypts the physical backups. They cannot be restored without it. When Tesria makes it, it also writes it to backup-key.txt in the Tesria folder for you to save somewhere else, and docker compose run --rm init show-backup-key prints it at any time. Set it yourself to restore backups from another machine with their key: see When the machine is gone. A key that does not open the backups already on this computer is refused, and Tesria does not start until it is corrected: docker compose logs init says so.

  • COLLAB_SHARED_SECRET: lets the service for editing a page with several people at once trust Tesria.

  • PDF_SHARED_SECRET: lets the service that makes PDF files trust Tesria.

Database

  • POSTGRES_USER: the owner account’s name, and POSTGRES_DB, the database’s name. Both are tesria unless you set others. The database is created with them on the first start; changing them later renames nothing.

  • APP_DB_USER: optional. The name of the restricted account Tesria runs as, tesria_app unless you set another.

Address and HTTPS

See HTTPS and domains for which to choose.

  • DOMAIN: the name people reach Tesria by, such as wiki.example.com, or localhost to try it on one computer. A real domain gets a free certificate from Let’s Encrypt; anything else uses a certificate Tesria makes itself. Links in emails use this address too, with TESRIA_HTTPS_PORT when it is not 443, unless you set Public Address in Admin, Settings.

  • ACME_EMAIL: optional. An email address Let’s Encrypt can write to about your certificate. Let’s Encrypt works without one.

  • CADDYFILE: which web server configuration to use. Leave it out on a private network. Set it to deploy/Caddyfile.public when the server can be reached from the internet.

  • PROXY_TRUSTED_NETWORKS: only if you put a proxy of your own in front of Tesria: that proxy’s address, such as 10.0.0.5/32. Tesria then believes the visitor addresses it passes on.

  • COMPOSE_FILE: set by the Docker Desktop setup in Real visitor addresses with Docker Desktop, which adds its own file to the list. Leave it alone otherwise.

  • PROXY_PROTOCOL_FROM: optional, and set by that same setup: which addresses Tesria’s web server believes when they attach a visitor’s real address. Left out, nothing is believed, which is right for every other install.

  • TESRIA_LOOPBACK_HTTP_PORT: and TESRIA_LOOPBACK_HTTPS_PORT: set by the Windows setup in that same page. The ports, reachable only from this computer, where Tesria’s web server waits for visitors handed on with their real addresses: 18080 and 18443 for a Tesria on 80 and 443, and 20000 above its own ports for any other. Leave them alone unless the setup says those are taken.

  • TESRIA_TAILSCALE_ADDRESS: optional. The fixed address of the Tailscale container, 10.203.0.250 unless you set another; Tesria believes the visitor address Tailscale passes on only from there. Change it only together with TESRIA_SUBNET, to an address inside it.

  • TESRIA_SUBNET: optional. The private network Tesria’s own services talk to each other on, 10.203.0.0/24 unless you set another. Change it only if that range is already used by a VPN or your own network, or for a second Tesria on the same computer. After changing it, run docker compose down and then docker compose up -d.

  • TESRIA_HTTP_PORT: optional. The port Tesria answers plain HTTP on, 80 unless you set another.

  • TESRIA_HTTPS_PORT: optional. The port Tesria answers HTTPS on, 443 unless you set another. Change these two only for a second Tesria on the same computer, or when something else already uses the ports. Links in emails include an HTTPS port other than 443, such as https://localhost:8443, unless Public Address in Admin, Settings says otherwise: set it there if people reach this Tesria through a proxy of your own on another port.

  • COMPOSE_PROJECT_NAME: optional. The name Docker Compose knows this Tesria by, and the start of its volumes’ names: tesria unless you set another. Set it only for a second Tesria on the same computer, before that Tesria’s first start: changing it on an existing Tesria makes a new, empty one, and the wiki stays in the volumes of the old name. See Installing with Docker Compose, under A second Tesria on the same computer.

Tailscale

Optional, and used only when the Tailscale service is started. Reaching Tesria from anywhere with Tailscale walks through it.

  • TS_AUTHKEY: an auth key from your Tailscale admin console, so Tesria can join your tailnet. Needed only for the first start: after that the device remembers who it is.

  • TS_HOSTNAME: the name Tesria takes on your tailnet, and so the first part of its address: tesria unless you set another.

Single sign-on (beta)

All optional, and off while OIDC_AUTHORITY is empty. Single sign-on (OIDC) walks through them.

  • OIDC_AUTHORITY: your identity provider’s address.

  • OIDC_CLIENT_ID: the client ID you registered there.

  • OIDC_CLIENT_SECRET: its secret.

  • OIDC_DISPLAY_NAME: the words on the sign-in button, such as Company SSO.

  • OIDC_REQUIRE_HTTPS_METADATA: leave it out. Set it to false only for a test provider on plain HTTP on the same machine.

Backups on this machine

See How backups work. The key that encrypts them, BACKUP_ENCRYPTION_KEY, is under Generated for you, above.

  • BACKUP_INTERVAL_HOURS: how often backups run. 24 unless set.

  • BACKUP_FULL_EVERY_DAYS: a new full physical backup once the newest is this many days old, with smaller ones in between. 7 unless set.

  • BACKUP_RETENTION_DAYS: only the starting point for how long backups are kept, read on the first start. After that, retention is set in the browser (see Retention) and this is ignored.

Offsite backups

Three places to keep a copy, each optional, each with its own passphrase. Offsite copies explains how to set each one up.

Cloud storage

  • OFFSITE_CLOUD_TYPE: b2 for Backblaze B2, or s3 for any other storage that speaks the S3 protocol. Empty turns the cloud copy off.

  • OFFSITE_CLOUD_ENDPOINT: the storage service’s address, such as s3.us-west-000.backblazeb2.com.

  • OFFSITE_CLOUD_BUCKET: the bucket to use.

  • OFFSITE_CLOUD_REGION: the bucket’s region.

  • OFFSITE_CLOUD_PATH: a folder inside the bucket, such as /tesria.

  • OFFSITE_CLOUD_URI_STYLE: host for Backblaze and AWS, path for MinIO and most self-hosted storage. The first thing to change if backups fail with a DNS or 404 error.

  • OFFSITE_CLOUD_KEY: and OFFSITE_CLOUD_SECRET: the access key and its secret.

  • OFFSITE_CLOUD_PASSPHRASE: encrypts the cloud copy. Different from every other passphrase here.

  • OFFSITE_CLOUD_RETENTION_FULL: how many full backups the cloud keeps. 4 unless set.

  • OFFSITE_CLOUD_BACKUP_EVERY_DAYS: how often a full backup goes to the cloud. 7 unless set. Changes stream there continuously in between.

  • OFFSITE_CLOUD_BUDGET_GB: optional. How much you mean the cloud copy to hold. See Testing a target and the cloud budget.

  • OFFSITE_CLOUD_VERIFY_TLS: only for testing against storage on this computer. Never set it for a real provider.

  • OFFSITE_ARCHIVE_QUEUE_MAX: how much unsent change history may pile up while the cloud cannot be reached, before it is dropped. 16GiB unless set. Keep it well under the free disk space.

Network drive

  • OFFSITE_NAS_PATH: a network share, already connected to this computer, to copy to.

  • OFFSITE_NAS_PASSPHRASE: encrypts the copy on the share.

Removable drive

  • OFFSITE_REMOVABLE_PATH: where the drive appears when it is plugged in.

  • OFFSITE_REMOVABLE_PASSPHRASE: encrypts the copy on the drive.

All offsite copies

  • OFFSITE_RETRY_MINUTES: how long to wait before trying again when a copy could not reach its target. 15 unless set.

  • OFFSITE_DRILL_DAYS: how often each offsite copy is restored for real, as a test. 30 unless set. See Restore drills.

Not in .env

The largest upload is set in the web server’s configuration file (deploy/Caddyfile) rather than here: 100 MB for a file added to a page, and 500 MB for importing a wiki pack.


Applies to

Tesria 0.5 and later

Updated

September 30, 2026

Changes

Revised.