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, and most people set them once and forget them.

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.

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.

# Off: the # at the start makes the line a comment
# OFFSITE_RETRY_MINUTES=15

# On
OFFSITE_RETRY_MINUTES=30

A long random value, for a password or a passphrase, is made with:

openssl rand -hex 32

Database

• POSTGRES_PASSWORD: Required. 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.

• POSTGRES_USER: the owner account’s name, and POSTGRES_DB, the database’s name. The example’s values work. The database is created with them on the first start; changing them later renames nothing.

• APP_DB_PASSWORD: Required. 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. Tesria will not start without it. To change it later, change the value and run docker compose up -d.

• APP_DB_USER: optional. That account’s name, 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, unless you set Public address in Admin, Settings.

• ACME_EMAIL: an email address Let’s Encrypt can write to about your certificate.

• 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_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. After changing it, run docker compose down and then docker compose up -d.

Optional features

• COLLAB_SHARED_SECRET: turns on editing a page with several people at once. Any long random value. Empty, one person edits a page at a time.

• PDF_SHARED_SECRET: turns on PDF export. Any long random value. Without it, exporting as HTML still works, and asking for a PDF says to print the HTML export instead.

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.

• BACKUP_ENCRYPTION_KEY: Required. Encrypts the physical backups. They cannot be restored without it.

• BACKUP_INTERVAL_HOURS: how often backups run: 24 in the example.

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