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.
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), make sure the PostgreSQL Data path points to a cache-backed location — for example /mnt/cache/appdata/tracearr/postgres or /mnt/appdata/tracearr/postgres if you have a dedicated appdata share. Paths under /mnt/user go through Unraid’s FUSE layer, which adds significant latency to every database read and write. On a typical setup this can make PostgreSQL checkpoints take 50–100x longer than they should, even on NVMe drives.
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.