Docker

The compose file below runs the application and a PostgreSQL (pgvector) database. Images are published for linux/amd64 and linux/arm64 (a 64-bit Raspberry Pi works; 32-bit boards do not).

What every install needs

• The database image must provide the vector extension. Use pgvector/pgvector:pg16 (a drop-in PostgreSQL 16 image); plain postgres:16 does not work and the application refuses to start against it.
• JWT_SECRET must be a random value of at least 32 characters, for example the output of openssl rand -base64 48. It is only optional with AUTH_ENABLED=false. The application refuses to start while it is empty or starts with CHANGEME.
• DATA_PROTECTION_KEY should be a second, different random value of at least 32 characters. See Data protection key for what it protects and why it must stay stable.

Docker Compose

Fill in JWT_SECRET and DATA_PROTECTION_KEY, each with its own output of openssl rand -base64 48, and replace both CHANGEME database passwords with the same password of your own.

docker-compose.yml

services:
  boardgametracker:
    image: uping/boardgametracker:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./images:/app/images
      - ./logs:/app/logs
      - ./manuals:/app/manuals
    ports:
      - "5444:5444"
    environment:
      - DB_HOST=db
      - DB_USER=dbuser
      - DB_PASSWORD=CHANGEME
      - DB_NAME=boardgametracker
      - DB_PORT=5432
      - JWT_SECRET=
      - DATA_PROTECTION_KEY=
      - TZ=UTC

  db:
    image: pgvector/pgvector:pg16
    restart: unless-stopped
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=boardgametracker
      - POSTGRES_USER=dbuser
      - POSTGRES_PASSWORD=CHANGEME
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dbuser -d boardgametracker"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

The docker-compose.yml in the repository, used by the quick start, runs the same stack plus the optional rules assistant, and reads an optional .env file next to it: every variable from the environment variables page can live there instead of in the compose file. That env_file entry needs Docker Compose 2.24 or newer; older versions, including the Compose bundled with some NAS container managers, stop with env_file.0 must be a string. Check with docker compose version, and on an older version use the file above or delete the three env_file lines.

Docker run

This command starts the BoardGameTracker container on its own and needs a PostgreSQL server with the vector extension that the container can reach. Set DB_HOST to that server’s host name or address, or attach the container to the database’s Docker network with --network <name>. Fill in JWT_SECRET and DATA_PROTECTION_KEY as above.

Terminal

docker run -d \
    --name boardgametracker \
    --restart unless-stopped \
    -p 5444:5444 \
    -v ./images:/app/images \
    -v ./logs:/app/logs \
    -v ./manuals:/app/manuals \
    -e DB_HOST=<your-postgres-host> \
    -e DB_USER=dbuser \
    -e DB_PASSWORD=CHANGEME \
    -e DB_NAME=boardgametracker \
    -e DB_PORT=5432 \
    -e JWT_SECRET= \
    -e DATA_PROTECTION_KEY= \
    -e TZ=UTC \
    uping/boardgametracker:latest

Ports, health check and file ownership

• The container listens on port 5444. To publish it on another host port, change the left side of 5444:5444, for example 8080:5444.
• The container answers GET /api/health for health checks; the image already has a Docker health check on it.
• The mounted folders are owned by user and group 1654 inside the container; see PUID / PGID to match your host user.

See Upgrading before moving to a new release.