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
Open
.envin a plain text editor. If there is none yet, make it: copy.env.exampleto.env(every line in it is commented out, so it changes nothing by itself), or start an empty file with that name.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#.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=30On 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.
# 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:
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 tobackup-key.txtin the Tesria folder for you to save somewhere else, anddocker compose run --rm init show-backup-keyprints 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 initsays 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, andPOSTGRES_DB, the database’s name. Both aretesriaunless 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_appunless you set another.
Address and HTTPS
See HTTPS and domains for which to choose.
DOMAIN: the name people reach Tesria by, such aswiki.example.com, orlocalhostto 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, withTESRIA_HTTPS_PORTwhen 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 todeploy/Caddyfile.publicwhen 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 as10.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: andTESRIA_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:18080and18443for 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.250unless you set another; Tesria believes the visitor address Tailscale passes on only from there. Change it only together withTESRIA_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/24unless 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, rundocker compose downand thendocker compose up -d.TESRIA_HTTP_PORT: optional. The port Tesria answers plain HTTP on,80unless you set another.TESRIA_HTTPS_PORT: optional. The port Tesria answers HTTPS on,443unless 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 ashttps://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:tesriaunless 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:tesriaunless 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 tofalseonly 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:b2for Backblaze B2, ors3for any other storage that speaks the S3 protocol. Empty turns the cloud copy off.OFFSITE_CLOUD_ENDPOINT: the storage service’s address, such ass3.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:hostfor Backblaze and AWS,pathfor MinIO and most self-hosted storage. The first thing to change if backups fail with a DNS or 404 error.OFFSITE_CLOUD_KEY: andOFFSITE_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. |