Docker Compose

The recommended way to run Tracearr. This sets up three containers — Tracearr, TimescaleDB, and Redis — using our ready-to-use compose file .

Quick Start

# Download the recommended compose file
curl -O https://raw.githubusercontent.com/connorgallopo/Tracearr/main/docker/examples/docker-compose.pg18.yml
 
# Generate required secrets
echo "JWT_SECRET=$(openssl rand -hex 32)" > .env
echo "COOKIE_SECRET=$(openssl rand -hex 32)" >> .env
 
# Start Tracearr
docker compose -f docker-compose.pg18.yml up -d

# Download the recommended compose file
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/connorgallopo/Tracearr/main/docker/examples/docker-compose.pg18.yml" -OutFile "docker-compose.pg18.yml"
 
# Generate required secrets
"JWT_SECRET=$(-join (1..16 | %{'{0:x2}' -f (Get-Random -Max 256)}))" | Out-File -Encoding ascii .env
"COOKIE_SECRET=$(-join (1..16 | %{'{0:x2}' -f (Get-Random -Max 256)}))" | Out-File -Encoding ascii -Append .env
 
# Start Tracearr
docker compose -f docker-compose.pg18.yml up -d

Tracearr will be available at http://localhost:3000.

Generating Secrets Without the CLI

Tracearr requires two secrets: JWT_SECRET and COOKIE_SECRET. Both need to be 64-character hexadecimal strings (a 256-bit key). These are used internally for signing authentication tokens and encrypting session cookies — they just need to be long, random, and unique to your installation.

If you’re deploying through a Docker UI or another tool where you need to provide the secrets yourself, here’s how to generate them.

Terminal

openssl rand -hex 32

-join (1..16 | %{'{0:x2}' -f (Get-Random -Max 256)})

Run the command twice — once for JWT_SECRET and once for COOKIE_SECRET. Copy each output into your environment variable configuration.

Online generator

If you don’t have terminal access, you can use randomkeygen.com/random-string :

1. Set Length to 64 Characters
2. Set Character Set to Hexadecimal (0-9, a-f)
3. Click Generate
4. Copy the result

Do this twice — you need one value for JWT_SECRET and a different one for COOKIE_SECRET. Don’t reuse the same value for both.

Other Platforms

Docker Volumes & Backups

You’ll notice the compose file uses named Docker volumes (like timescale_data and redis_data) rather than bind mounts (like ./data:/var/lib/postgresql/data). This is deliberate, and it matters more than you might expect.

Why not bind mounts?

PostgreSQL requires its data directory to be owned by the postgres user with 0700 permissions (owner-only read/write/execute). If the permissions are wrong, PostgreSQL refuses to start. This is a security measure, not a quirk.

With bind mounts, the directory lives on your host filesystem, and ownership depends on how your host maps UIDs. If the UID of the postgres user inside the container doesn’t match the owner of the directory on the host, you get a permissions mismatch and a database that won’t boot. This is especially common on systems with FUSE-based filesystems (like Unraid’s array), where permission mapping can be unreliable.

Named volumes sidestep this entirely. Docker manages the volume’s filesystem directly, so ownership and permissions are set correctly when the container first creates them — no manual setup needed.

There’s also a performance angle. Named volumes use Docker’s storage driver, which on Linux typically means native filesystem access. Bind mounts through FUSE-based filesystems (common on NAS platforms) add an abstraction layer that introduces latency — not ideal for a database doing thousands of small reads and writes per second.

Backing up your database

This is the most common reason people reach for bind mounts — they want to see the database files on the host so they can copy them with their existing backup tool. It’s a reasonable instinct, but it’s the wrong approach for PostgreSQL.

PostgreSQL data files are not safe to copy while the database is running. PostgreSQL uses a Write-Ahead Log (WAL) system where changes are written to the WAL before they’re applied to the actual data files. At any given moment, the on-disk data files are in an inconsistent state — committed changes may only exist in memory (in “dirty pages” within shared buffers) and haven’t been flushed to disk yet. If you copy those files while PostgreSQL is running, you get a snapshot where some tables reflect recent transactions and others don’t. That backup looks fine sitting on disk, but it may fail or produce corrupt data when you try to restore it.

TimescaleDB makes this problem worse. Each hypertable chunk is stored as a separate PostgreSQL table with its own data files, indexes, and internal catalog entries. A single hypertable can have hundreds of chunks. If the catalog metadata and the data files are captured at different points in time (which is almost guaranteed during a file copy), you end up with an irrecoverable inconsistency.

Even if you stop the database first, it has to be a clean shutdown. If PostgreSQL is killed (OOM, Docker timeout, power loss), the data files are left in a crash state and require WAL replay to recover. A file-level backup of a dirty shutdown is not a valid backup.

The right tool is pg_dump. It uses PostgreSQL’s MVCC (Multi-Version Concurrency Control) system to take a consistent, point-in-time logical snapshot of your entire database — while it’s still running. No downtime, no file permission headaches, no risk of partial writes. The output is a portable file that can be restored to any compatible PostgreSQL version, which also means you can migrate between major versions (e.g., PG16 to PG18) without worrying about binary format changes.

# Back up the database (compressed custom format, recommended)
docker exec tracearr-db pg_dump -U tracearr -d tracearr -Fc > tracearr_backup.dump
 
# Back up to plain SQL (human-readable, larger file)
docker exec tracearr-db pg_dump -U tracearr -d tracearr > tracearr_backup.sql
 
# Restore from custom format
docker exec -i tracearr-db pg_restore -U tracearr -d tracearr --clean --if-exists < tracearr_backup.dump
 
# Restore from plain SQL
docker exec -i tracearr-db psql -U tracearr -d tracearr < tracearr_backup.sql

You can schedule this with a cron job, or run it manually whenever you want a snapshot. The -Fc (custom format) option compresses the output and supports selective restoration of individual tables if you ever need it.

# Stop Tracearr first, then:
docker exec tracearr-db psql -U tracearr -d postgres -c "DROP DATABASE tracearr;"
docker exec tracearr-db psql -U tracearr -d postgres -c "CREATE DATABASE tracearr OWNER tracearr;"
docker exec -i tracearr-db pg_restore -U tracearr -d tracearr < tracearr_backup.dump

Next Steps

Once Tracearr is running, connect your first media server.