Install settings and profiles

A self-hosted Tenvara install keeps its settings in one file, .env, in the install folder beside the compose file. The installer writes it, an update keeps what you set, and most installs never need to open it. This guide covers the handful of settings an administrator does meet, and how the install sizes itself for its server.

On a hosted instance none of this applies: we size and run the install for you.

Note: After changing .env, run docker compose up -d in the install folder so the change takes effect, or let the next update apply it.

The settings you meet#

Every setting of Tenvara's own starts with TENVARA_.

Two settings you may meet have no prefix:

• OUTBOUND_ALLOW_HOSTS: Tenvara refuses to fetch from internal and metadata addresses on your behalf. If something it must reach is on your own network (an old system you are migrating from, for example), list its host here, comma separated.
• QUEUE_MAX_PROCESSES: the cap on background worker processes. Left empty, it is worked out from the server's memory.

Installing self-hosted covers the address, TLS and relay settings in context.

When TLS ends somewhere else#

Agents refuse a server whose certificate key is not one the install vouches for, so nothing in the middle can stand in for it. Normally the install reads the key from its own front door and you set nothing.

• Behind a load balancer or CDN that ends TLS, set TENVARA_AGENT_TLS_PROBE=public, so the server reads the key at its public name, which is what agents meet.
• To add a key by hand (another proxy in front, or the next key ahead of a planned change), list it in TENVARA_AGENT_TLS_PINS as sha256/<base64>, comma separated.

A key the front door has presented stays trusted for 14 days after it was last seen, so a normal renewal needs nothing from you.

Device web pages and their ports#

Device web pages open a device's own web interface (a NAS, a printer, a switch or a UPS) through an agent on its network. Each session is served at an address of its own, so the device's links, cookies and redirects keep working. TENVARA_WEB_PROXY_MODE chooses how: auto (the default) decides from what the install can do, wildcard or ports.

• Wildcard (best): each session gets an address under *. and your install's name. It needs a DNS record for *. and your install's name pointing at the install, and a certificate that covers it. With the built-in front door each name gets its certificate when it is first opened.
• Ports: each session gets a port on your install's own name from TENVARA_WEB_PROXY_PORTS, 28100 to 28199 unless you choose another range. Allow this range through your firewall to the server. Keep a range of your own below the ports Linux hands out for outgoing connections (32768 upwards on most servers), or the front door may not be able to start.

To check what the install can use, run docker compose exec core php artisan web-proxy:check in the install folder. It says what to change when something is missing; run it again after changing DNS or the certificate. A changed port range needs docker compose up -d caddy core.

In ports mode, give the session ports a name of their own: add a DNS record webpages. and your install's name, pointing at the same address, and run the update. Sessions then open on that name, apart from the app's own. Behind another proxy that ends TLS, pass the wildcard name and the port range on to the install, and set TENVARA_WEB_PROXY_HOST yourself. When your install's site address is plain HTTP behind a TLS proxy of your own, the session ports are plain HTTP too, and an update keeps it that way.

See Opening device web pages.

Renaming older settings before an update#

An install made by an older installer has settings with an older prefix. Tenvara now reads only the TENVARA_ names, and it does not rewrite your file for you. When you update such an install, the update stops before it changes anything and names each setting it needs, so the install keeps running on the version it had.

Every setting keeps the rest of its name; only the prefix changes. On the server, in the install folder, with Tenvara still on its old version:

old=$(sed -n -E 's/^([A-Z]+)_REMOTE_INTERNAL_TOKEN=.*/\1/p' .env | head -n1); echo "old prefix: $old"
cp .env .env.before-rename
sed -i -E "s/^(#[[:space:]]*)?${old}_/\1TENVARA_/" .env
grep -c "^${old}_" .env    # 0 when every line is renamed

Stop if the first line prints no prefix, or prints TENVARA: the file has already been renamed. Then run the update as usual.

• If you keep an override file, a service unit or a backup script of your own that names one of these settings, rename it there too.
• Going back to the older version needs the old names again: put .env.before-rename back.
• Install commands for agents carry TENVARA_SERVER and TENVARA_TOKEN. A command copied before the rename installs the agent without enrolling it, so copy install commands again from Devices > Enrolment rather than reusing old ones.

See Updates for everything else an update checks.

Install profiles#

The installer and every update pick one of three profiles from the server's CPUs and memory. The database, the event store, the queue workers and backups all size themselves from it, so a small server is not asked for more than it has and a large one is put to use.

A server with 2 vCPUs and 16 GB is still Small: CPUs are what such a server runs out of first.

The profile is picked again on every update, so a server you have resized gets its new profile by itself. The update says which profile is in force and why.

Choose your own#

1. Open .env in the install folder.
2. Set TENVARA_INSTALL_PROFILE=small, standard or large.
3. Run the update, or docker compose up -d.

Updates keep a value you set. Remove the line to have the profile picked from the server again. A value that is not one of the three stops the update before anything changes, naming the line.

Check it#

Settings > System status has an Install profile section: the profile in use and whether it was picked or set by you, the server's CPUs and memory, how many devices the install looks after, how the database is sized, and the sizing table with your row marked.

It warns when the install looks after more devices than its profile is sized for (move to the next size up, and the next update picks the larger profile), when a profile set by hand is larger than the server, and when the database is still on its stock settings. See System status.

Memory for the backup service#

The backup service runs with a memory limit, 2 GB unless TENVARA_BACKUP_MEMORY says otherwise. It sizes its own work from that limit: how many Microsoft 365 tenants, mailboxes, drives and sites it backs up at once. More memory makes more run at once; it never makes one backup need more.

Leave the rest of Tenvara its share: on a busy server the other services together want at least 4 GB.

To raise it, set the value in .env and run docker compose up -d backup, or let the next update apply it. A value of your own is never changed by an update.

When memory is short, nothing fails: a part of a backup waits, and its job log says it is waiting for memory on the backup server. Settings > System status shows Backup service memory with how many tenants run at once, and Settings > Backup warns, with the value to set, when you ask for more tenants at once than the memory safely allows. See The first backups queue.

Related#

• Installing self-hosted
• Updates
• System status
• Licence and updates