Backups & upgrades

The controller is deliberately simple to operate: one binary, one database, one data directory. But two things are irreplaceable — the encryption key and the SSH proxy host key — so read this page before going to production.

What to back up

What	Where (VM install)	Why
Encryption keys	/etc/tessera/tessera.secret (containers: the TESSERA_ENC_KEY / TESSERA_JWT_SECRET values)	TESSERA_ENC_KEY encrypts every stored credential — losing it makes them all permanently unrecoverable
PostgreSQL	your database server (pg_dump)	targets, encrypted credentials, users, grants, the audit log
Data directory	/var/lib/tessera (containers: the data volume)	session recordings and the SSH proxy host key
Config	/etc/tessera/tessera.conf (containers: your compose/values files)	quick to recreate, but back it up anyway

Store the tessera.secret backup somewhere safe and separate from the database backup — together they decrypt every credential.

Never regenerate the SSH proxy host key

Clients pin the controller’s SSH host key on first use (TOFU). If you wipe /var/lib/tessera or the container data volume and a new key is generated, every client’s pin breaks. Back the key up with the data directory and restore it as-is.

Upgrading

An upgrade restarts the controller, and sessions live in memory — so active SSH/RDP sessions drop. Upgrades are therefore a planned action: pick a maintenance window and tell your users. Database and Kubernetes tunnels are re-established by the desktop app on relaunch; SSH and RDP sessions are not.

VM (apt)

The package is deliberately excluded from unattended-upgrades — it never restarts behind your back:

sudo apt update && sudo apt install --only-upgrade tessera-controller

tessera.conf, tessera.secret and /var/lib/tessera are preserved. The latest config template is written next to yours as /etc/tessera/tessera.conf.example for comparison, and the database schema migrates automatically on start.

Docker Compose / Kubernetes

Bump the image tag (Compose) or chart version (Helm) and redeploy — the exact commands are in Docker Compose and Kubernetes. The controller is a single replica by design, so the rollout is a restart, not a rolling update.

Restoring

1. Restore PostgreSQL from your dump.
2. Put tessera.secret (or the key env vars) and /var/lib/tessera back in place — the same keys that encrypted the data, and the same SSH host key clients have pinned.
3. Install the same (or newer) controller version and start it. Migrations are applied automatically and are safe to re-run.

If the encryption key you restore doesn’t match the database, the controller starts but stored credentials fail to decrypt — see Troubleshooting.