Configuration

The controller is configured with environment variables; most runtime settings (OIDC, SCIM, notifications, branding, policy) are managed in the web console and stored in Postgres.

Environment variables

Variable	Required	Default	Description
`TESSERA_DATABASE_URL`	yes (prod)	`postgres://tessera:tessera@localhost:5432/tessera?sslmode=disable`	Postgres connection string. A dev default is used if unset; effectively required in production.
`TESSERA_ENC_KEY`	yes (prod)	ephemeral	32-byte hex key for AES-GCM credential encryption.
`TESSERA_JWT_SECRET`	yes (prod)	ephemeral	32-byte hex secret for signing session JWTs.
`TESSERA_PUBLIC_URL`	recommended	`https://localhost:8443`	External URL of the controller — used for OIDC redirects and notification links.
`TESSERA_HTTP_ADDR`	no	`:8443`	Address the controller listens on.
`TESSERA_TLS_CERT`	no	—	Path to TLS certificate file. If the cert/key are unset, the controller generates an in-memory self-signed cert in any mode — terminate real TLS at a reverse proxy.
`TESSERA_TLS_KEY`	no	—	Path to TLS private key file.
`TESSERA_HOST_KEY`	no	`./dev-data/ssh_host_ed25519_key`	Path to the SSH host key used by the SSH proxy. Generated if absent in dev mode.
`TESSERA_DEV`	no	`true` locally	Dev mode: ephemeral keys, relaxed checks. Only affects locally built binaries — released/customer builds force it off, so the variable has no effect there.
`TESSERA_METRICS_TOKEN`	no	—	Bearer token to protect the Prometheus `/metrics` endpoint. Unset = unauthenticated.
`TESSERA_LICENSE`	no	—	Per-org license token from your portal. Also accepts `@/path/to/file`. Changing it and restarting installs the new licence; ignored while the controller is linked to the portal, which renews itself.
`TESSERA_LICENSE_PUBKEY`	no	— (empty)	Per-org Ed25519 public key pasted from the portal, used on the legacy/dev self-verify path. Release builds verify the license against a build-time-baked master key, so this is not used there.
`TESSERA_PASSWORD_LOGIN`	no	`false`	Break-glass: force-enable password login even when SSO-only is configured. Unset after recovery.
`TESSERA_RECORDINGS_DIR`	no	`./dev-data/recordings`	Directory for session `.cast` recordings.
`TESSERA_AUDIT_RETENTION_DAYS`	no	`0` (keep forever)	Delete audit-log entries older than N days. A daily background job purges them, in whole sealed blocks so the integrity chain stays continuous; `0` disables purging.
`TESSERA_AUDIT_SIGN_KEY`	recommended	unset	32 bytes of hex. Signs each sealed audit block with a key that is not in the database, so the chain cannot be rebuilt by somebody who can write to it. Unset means the chain still links and still catches careless tampering, but not an attacker who recomputes it. Generate with `openssl rand -hex 32`, keep it with your other secrets, and back it up: losing it does not harm the data but makes old signatures unverifiable. Can be set at any time: blocks sealed before it keep no signature and are not reported as a problem.
`TESSERA_LOGIN_TTL`	no	`12h`	How long a sign-in lasts without “remember me”. Accepts Go durations (`8h`, `45m`) and whole days (`14d`).
`TESSERA_REMEMBER_TTL`	no	`30d`	How long a sign-in lasts with remember me ticked. The default was ninety days and is now thirty; an installation with a session policy should set its own. The token is revocable at any time: changing or resetting a password ends every session that account holds, immediately.
`TESSERA_IDLE_TIMEOUT`	no	unset (off)	End a session that has not been used for this long, e.g. `45m` or `8h`. Off by default so an upgrade does not start signing people out. Personal access tokens are exempt: they exist for headless work, which is idle between runs by definition.
`TESSERA_AUDIT_VERIFY_AT`	no	`03:17`	When the daily full verification of the audit chain runs, as `HH:MM` in the controller’s local time, or `off`. A full pass reads every block and every row it covers, so it is scheduled for the quiet part of the night; set `off` only if you run it yourself against `GET /api/audit/verify`. See Prometheus metrics.
`TESSERA_TRUSTED_PROXIES`	behind a proxy	unset	Comma-separated addresses or CIDRs whose `X-Forwarded-For` may be believed, which decides what the audit log records as the source of an event. Loopback is trusted without configuration, so a reverse proxy on the same host needs nothing. Behind Docker or an ingress the controller sees that hop’s address instead, and the startup log names the address to trust. Set it to that address or its subnet, never a whole private range: anything you trust here can choose its own address in your audit log.
`TESSERA_RECORDING_RETENTION_DAYS`	no	`0` (keep forever)	Delete session replays (`.cast` files + their metadata) older than N days. `0` disables purging.
`TESSERA_SESSION_TTL`	no	`60`	One-time session token TTL in seconds.
`TESSERA_OIDC_PROVIDERS`	no	—	JSON array of OIDC provider configs (alternative to web console). See OIDC guide.

Clock

Keep the controller’s clock synchronised, with systemd-timesyncd, chrony or whatever your platform uses. Nothing enforces this and nothing will warn you.

It matters more here than on an ordinary server. Audit entries are timestamped by the database, and the question an auditor asks is “show me everything on the twelfth of March”: an answer from a machine whose clock drifted is not evidence, it is a guess. ISO/IEC 27001:2022 lists clock synchronisation as its own control (A.8.17) for exactly that reason, next to the logging control it exists to support. Session recordings and the integrity chain carry the same timestamps.

Generate secrets with openssl rand -hex 32.

Console-managed settings

Configured under Settings (admin only) and persisted in the database:

Authentication — OIDC providers, SCIM.
Integrations — Telegram notifications, audit export, database query audit.
Policy — read-only command lists, Kubernetes & database policies.
Import — bulk import / export of infrastructure.
License — install or refresh your edition license.
Appearance — branding (name, subtitle, logo).

Endpoints

/ — web console (embedded SPA).
/api/* — REST API (Bearer JWT).
/connect — WSS tunnel (one-time session token).
/oidc/* — OIDC login flow.
/scim/v2/* — SCIM provisioning (Bearer token).
/metrics — Prometheus metrics (optionally tokened).
/healthz — health check.