Installation¶

Tracker Tracker runs in Docker. Use Docker Compose to get it up and running.

Prerequisites¶

Docker 24+
Docker Compose v2 (the docker compose plugin, not the legacy docker-compose binary)

That's it. Nothing else to install.

Architecture support

We build for linux/amd64 and linux/arm64, so you're covered on x86-64 servers, Raspberry Pi 4/5, and Apple Silicon in Linux VMs. Docker grabs the right one automatically.

Step 1. Create a working directory¶

mkdir tracker-tracker && cd tracker-tracker

Step 2. Download the compose file and env template¶

curl -LO https://raw.githubusercontent.com/jordanlambrecht/tracker-tracker/main/docker-compose.yml
curl -L https://raw.githubusercontent.com/jordanlambrecht/tracker-tracker/main/.env.example -o .env

Or create them manually by copying the examples below.

Step 3. Generate secrets¶

Generate two secrets and paste them into .env:

openssl rand -base64 24   # → POSTGRES_PASSWORD
openssl rand -base64 48   # → SESSION_SECRET

Then open .env and add them:

.env

SESSION_SECRET=<output of openssl rand -base64 48>
POSTGRES_PASSWORD=<output of openssl rand -base64 24>
POSTGRES_USER=postgres
TZ=America/Chicago

Fresh secrets every time

Generate new ones each time. SESSION_SECRET protects your cookies, POSTGRES_PASSWORD protects your database. Don't copy the .env.example placeholder.

Step 4. Start the stack¶

Docker Compose (recommended)

docker compose up -d

The app waits for the database to be ready, then sets up the schema automatically. First boot takes about 15-20 seconds. Peek at the logs if you want to watch:

docker compose logs -f tracker-tracker-app

Docker Run (standalone)

Running Postgres elsewhere? Start the app container:

docker run -d \
    --name tracker-tracker-app \
    --restart unless-stopped \
    -p 3000:3000 \
    -v ./data:/data \
    -e DATABASE_URL="postgresql://postgres:yourpassword@your-postgres-host:5432/tracker_tracker" \
    -e SESSION_SECRET="your-session-secret-minimum-32-chars" \
    -e TZ="America/Chicago" \
    ghcr.io/jordanlambrecht/tracker-tracker:latest

Point DATABASE_URL to your Postgres instance. The app will create its schema on startup if needed.

Step 5. Verify it's running¶

docker compose ps

Both containers should be running:

NAME                    STATUS
tracker-tracker-app     running
tracker-tracker-db      running (healthy)

Or test the health endpoint:

curl -s http://localhost:3000/api/health

A 200 OK means the app is up and talking to the database.

Step 6. Open the app¶

Go to http://localhost:3000.

On first visit you'll be redirected to /setup to create your account. See First Setup for what to do next.

Image registries¶

Both registries have the same image. Use whichever you prefer:

Registry	Image
GitHub Container Registry	`ghcr.io/jordanlambrecht/tracker-tracker:latest`
Docker Hub	`jordyjordy/tracker-tracker:latest`

Pin a specific version if you want predictable updates:

ghcr.io/jordanlambrecht/tracker-tracker:2.1.1

Check the CHANGELOG before upgrading.

Using an external database¶

Using an external Postgres instance? Remove the tracker-tracker-db service and depends_on from docker-compose.yml, then set DATABASE_URL:

.env

DATABASE_URL=postgresql://myuser:mypassword@192.168.1.10:5432/tracker_tracker
SESSION_SECRET=...
TZ=America/Chicago

Tip

Create the database name ahead of time. The app handles the rest on startup, with no SQL scripts needed.