Installation

Start with a source checkout and local storage. Docker is the main delivery path; running directly with Cargo is also available.

Before you start

Public source publication is still pending. The commands below assume you already have a Teatro source checkout and are running from its repository root. There is no registry image to pull.

For Docker, use a 64-bit Linux host with Docker Engine, BuildKit and the Compose plugin.
For a native source run, install Rust 1.88 or newer and the platform's compiler/linker tools. Node.js is only needed for browser tests.
Use local storage with room for your games, database, uploads and temporary ZIP downloads.

Run with Docker

The checkout includes a Dockerfile and docker-compose.yml. Build your own image and start the service:

docker compose up --build -d

The default Compose service publishes port 4440 and mounts the persistent teatro-data volume at /data. The build needs network access to download its pinned inputs.

Open http://SERVER_IP:4440/setup on your trusted LAN, replacing SERVER_IP with your host's address. Create the administrator, then open / for the library or /admin for management.

For terminal-only account creation:

docker compose exec teatro /opt/teatro/teatro \
  users create-admin --username admin

The password prompt hides your input. Do not put a permanent administrator password into Compose configuration.

Run directly from source

Create the first administrator before opening a listener:

cargo run -- users create-admin --username admin
cargo run -- serve

Enter a password at the hidden prompt. The server listens on 127.0.0.1:4440 by default, so only this machine can reach it. Open http://127.0.0.1:4440/ and sign in.

To listen beyond localhost, explicitly set TEATRO_BIND_ADDR to a suitable interface, then restrict access to your trusted LAN, VPN or HTTPS proxy. Read the network boundary before changing it.

Check the first start

For either setup on the server machine, check health and authentication:

curl http://127.0.0.1:4440/healthz
curl -u admin http://127.0.0.1:4440/api/users/me

The second command prompts for your password and should return your administrator identity. An empty player library is expected until you add a game.

For Docker, inspect startup status and recent logs:

docker compose ps
docker compose logs --tail=100 teatro

Know where your data lives

Docker: /data/teatro.sqlite3, /data/roms and /data/assets inside the persistent volume.
Native defaults: data/teatro.sqlite3, data/roms and data/assets, relative to the working directory.

Keep SQLite on a local filesystem, not NFS or SMB. Run only one Teatro server against a data set. For a host bind mount, the container's UID/GID 10001:10001 needs read and write access.

Teatro reads TEATRO_* environment variables; it does not load .env files itself. Compose does load a local .env for interpolation. Its container paths differ from native defaults, so do not copy the source-development example unchanged.

Before replacing a container or upgrading a checkout, read backup and restore. Never remove a data volume as a troubleshooting shortcut.