Security & backups

Keep a network boundary

Native source runs listen on localhost by default. The default Compose service publishes port 4440, so restrict the host firewall to your trusted network before the first start.

Teatro retains HTTP Basic Auth for client compatibility. Plaintext HTTP does not protect credentials or game bytes. Use HTTPS through a reverse proxy or a trusted VPN for access beyond the local boundary. Do not expose port 4440 directly to the Internet.

If a proxy supplies forwarding headers, set TEATRO_TRUSTED_PROXY_IPS only to the exact direct peer IPs of your proxies. Never trust every LAN client. LAN discovery is not authentication.

Use the right account

Administrator

Imports, edits and deletes library content, manages users and changes settings.

Read-only

Browses the catalog and downloads games. Use this role for player devices and other read-only clients.

API token

A revocable credential for automation with read or admin scope. The raw value is shown only at creation.

The browser exchanges your password for a revocable session. By default it is tab-scoped with a 24-hour maximum. Remember me for 30 days persists the session, not the password. Use it only on a trusted device and sign out explicitly when finished.

For a native source checkout, reset an account password with:

cargo run -- users reset-password --username admin

In Docker, use docker compose exec teatro /opt/teatro/teatro followed by the same users reset-password arguments. Password resets invalidate that account's browser sessions.

Back up one consistent set

Stop Teatro before taking a manual filesystem backup. Copy these together:

1. The complete data directory, including SQLite and any WAL/SHM files.
2. Every configured library root, if stored outside that directory.
3. The asset root, if stored elsewhere.
4. The environment and service configuration needed to recreate the instance.

For Docker, use docker compose stop teatro before backing up the named volume and any bind-mounted library or assets. Restart with docker compose start teatro when the copy is complete. Never back up just the SQLite file while the server is writing.

Store the backup separately from the live data and protect access. IGDB and RomM secrets saved through Settings are stored in SQLite. Test restoration into an isolated location, not over the only working copy.

Upgrade and restore safely

Before upgrading, record the source revision or image you are using and take a complete stopped-instance backup. Database migrations apply at startup, and some migrations remove catalog records. Keep the matching old application available.

For rollback, stop the new server, restore the complete pre-upgrade data set and start the matching old application. An older binary is not guaranteed to read a database migrated by a newer one.

Only one server may own a data directory. Do not run a restored clone against the original library root. If you preserve the discovery identity, do not advertise both copies on the same link.

Check before retrying

Cannot connect

Check /healthz on the server, its listener address, port mapping and firewall. Localhost on another device is not your server.

Permission denied

Confirm container UID/GID 10001:10001 can write the mounted data tree. Stop and back up before changing ownership.

Instance locked

Find the other process using the data directory. Stop it normally; deleting a lock file is not a safe way to transfer ownership.

Game missing

Check the import result in Jobs, platform folder layout, required dependencies and skipped-file reasons.

For Docker diagnostics:

docker compose logs --tail=100 teatro
docker compose exec teatro /opt/teatro/teatro report

For a source run, use cargo run -- report. The report omits raw passwords and tokens, but review diagnostic material for private information before sharing it.