Installation

System requirements

Hardware

• A 64-bit AMD64 or ARM64 machine running Linux.
• Local storage with enough free space for the game library, SQLite database, covers, uploads and temporary ZIP downloads. Source builds also need temporary space for compiler and Docker build output.
• No fixed runtime CPU or memory minimum has been qualified. A source build is the heavier path; 4 GB RAM is recommended when compiling on a Raspberry Pi or another small system.
• A reliable wired or wireless network connection. Teatro listens on TCP port 4440.

Software

Direct source build

Git, Rust and Cargo 1.93 or newer, a C/C++ compiler toolchain, libclang and zlib development headers. On Debian: apt-get install build-essential pkg-config libclang-dev zlib1g-dev.

Docker source build

Git, Docker Engine with BuildKit, and Docker Compose v2.

Official image

Docker Engine. Docker pulls the Linux amd64 or arm64 image automatically.

Node.js is only needed for browser tests. Keep Teatro's data on a local filesystem, not NFS or SMB.

Run directly from source

git clone https://github.com/lodilorenzo/teatro.git
cd teatro
cargo build --release --locked
./target/release/teatro users create-admin --username admin
TEATRO_BIND_ADDR=0.0.0.0:4440 ./target/release/teatro serve

The account command prompts for a password without echoing it. Runtime data is stored under ./data. Open http://SERVER_IP:4440/ and sign in.

Node.js is not needed to run Teatro. Ordinary Cargo builds use the bundled SQLite; review the native-build security notes before deployment. The executable does not include the optional GOG extractor.

Build from source with Docker

git clone https://github.com/lodilorenzo/teatro.git
cd teatro
docker compose up --build -d

Compose builds teatro:local, publishes port 4440 and stores data in the persistent teatro-data volume. Open http://SERVER_IP:4440/setup immediately and create the administrator.

Run the official 0.22.1 image

The signed beta image supports Linux amd64 and arm64. There is no latest tag. See the 0.22.1 changelog for what changed. Review the known findings and scoped security exceptions before deploying.

docker volume create teatro-data

docker run -d \
  --name teatro \
  --restart unless-stopped \
  -p 4440:4440 \
  -v teatro-data:/data \
  ghcr.io/lodilorenzo/teatro:0.22.1

Docker pulls the image automatically if it is not already present. Open http://SERVER_IP:4440/setup immediately and create the administrator. Docker stores the database, ROMs and cached assets in the teatro-data volume.

For immutable pinning and signature verification, use the digest and Cosign commands in the full Docker guide.

Check the first start

For any 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 the source-built Docker deployment, inspect status and logs with:

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

For the official image, use:

docker ps --filter name=teatro
docker 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 can load a local .env for interpolation, while docker run accepts settings through --env or --env-file. Container paths differ from native defaults, so do not copy the source-development example unchanged.

This release adds collection tables and removes stored age classifications at startup while preserving other metadata and game files. Before replacing a container or upgrading a checkout, read backup and restore. Never remove a data volume as a troubleshooting shortcut.