Supervised
The supervised image bundles PostgreSQL, Redis, and Tracearr into a single container using supervisord. It was built for environments where running separate database containers isn’t practical.
This image is designed for Unraid and other bare-metal Docker hosts. Running it on VMs or nested container environments is unsupported. If you can run separate containers, use the standard Docker Compose setup instead — it’s more flexible, uses less memory, and runs a newer version of PostgreSQL.
Requirements
- 3GB RAM minimum — the container runs PostgreSQL, Redis, and Node.js simultaneously. Below 3GB, the container will be killed by the OOM killer (exit code 137).
- Docker with Compose V2
Quick Start
# Download the supervised compose file
curl -O https://raw.githubusercontent.com/connorgallopo/Tracearr/main/docker/examples/docker-compose.supervised-example.yml
# Start Tracearr
docker compose -f docker-compose.supervised-example.yml up -dThat’s it. No .env file needed — secrets are generated automatically on first boot and persisted across restarts.
Tracearr will be available at http://localhost:3000.
You can set optional environment variables like TZ, PORT, and LOG_LEVEL by uncommenting them
in the compose file. See the comments in
docker-compose.supervised-example.yml
for details.
How It Differs from Standard
| Standard (Docker Compose) | Supervised | |
|---|---|---|
| Containers | 3 (Tracearr, TimescaleDB, Redis) | 1 (all bundled) |
| PostgreSQL | 18 (TimescaleDB HA) | 15 (TimescaleDB) |
| Minimum RAM | ~1GB | 3GB |
| Secrets | Manual (.env file) | Auto-generated on first boot |
| Volumes | timescale_data, redis_data | tracearr_postgres, tracearr_redis, tracearr_data |
The supervised image runs PostgreSQL 15, while the standard compose uses PostgreSQL 18. The
on-disk binary format is incompatible between major versions — you cannot switch between these
setups and reuse the same data volumes. If you try, PostgreSQL will refuse to start. Always back
up with pg_dump before switching.
Why Named Volumes Matter Here
The supervised image runs three processes as three different system users — postgres, redis, and tracearr — each writing to its own data directory. On every startup, the entrypoint script runs chown and chmod across all three directories to ensure correct ownership before supervisord launches each process. PostgreSQL in particular requires 0700 permissions on its data directory and will refuse to start otherwise.
The poster cache sits inside the tracearr_data volume, so it survives restarts and updates with no extra configuration.
Named volumes are backed by Docker’s storage driver (typically ext4 or xfs), so these permission fixes work reliably every time. FUSE-based filesystems — like Unraid’s array — may silently fail to apply chown or chmod, which means PostgreSQL sees the wrong permissions and won’t start. supervisord will restart it in a loop, and the container will never become healthy.
If you need bind mounts, use the standard Docker Compose setup instead — it runs each service in its own container with a single user, which is far more forgiving with host filesystem permissions. We don’t recommend bind mounts in any case (see Why not bind mounts?), but if you must use them, the standard setup is the only one we provide support for.
If you install via the Unraid Community Apps template (which uses bind mounts), point the
PostgreSQL Data path at the pool directly, for example /mnt/cache/appdata/tracearr/postgres
(use your pool’s name in place of cache). Paths under /mnt/user go through Unraid’s FUSE
layer, which adds overhead to every database read and write, even on NVMe drives. Tracearr checks
this on each start and shows the owner a banner with the exact path to set. Only switch an
existing install once every file is on the pool, or Tracearr starts with a new, empty database.
See Pages are slow to load on Unraid for the steps.
Backing Up Your Database
Tracearr has a built-in Backup & Restore system that creates consistent database snapshots, supports scheduled backups with retention, and handles restoring with automatic rollback. You can manage everything from the web UI under Settings → Backup.
You can also create backups via the CLI:
docker exec tracearr node apps/server/scripts/backup.tsTo copy a backup from the Docker volume to your host filesystem:
docker cp tracearr:/data/backup ./tracearr-backupsSee Backup & Restore for full documentation.
For an explanation of why named volumes are used and why copying raw database files isn’t safe, see Docker Volumes & Backups on the Docker Compose page.
Next Steps
Once Tracearr is running, connect your first media server.