These docs follow the beta image. Until the next stable release after v0.2.181, latest lacks some of the features described here; use uping/boardgametracker:beta to get them.

Upgrading

BoardGameTracker applies its database migrations automatically when the container starts, so an upgrade is normally just pulling the new image. Some releases changed requirements; each note below says which release, so read them before you pull.

Back up first

Everything you need lives in the folders you mounted plus the database.

Stop the application container (leave the database running):
Terminal
```
docker compose stop boardgametracker
```

Dump the database:

docker compose exec db sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > backup-$(date +%F).sql

Copy the mounted folders: images (covers and player photos), manuals (uploaded rulebooks) and, if you want to keep them, logs.

To restore, recreate an empty database, load the dump with psql, put the folders back and start the container.

Release channels

Tag	What you get
`uping/boardgametracker:latest`	The last stable release.
`uping/boardgametracker:x.y` / `:x`	The latest stable release within a minor or major version, for example `0.2` or `0`.
`uping/boardgametracker:x.y.z`	A fixed version, for installs that should not move on their own. Beta builds get their own `x.y.z` tag too.
`uping/boardgametracker:beta`	Every change merged to `master`, published automatically. May contain unfinished features.

Breaking changes

`JWT_SECRET` is required (since v0.2.6)

Authentication is on by default. The container exits at startup with JWT_SECRET is not set unless you either set JWT_SECRET to a random value of at least 32 characters, or set AUTH_ENABLED=false to run without login.

The notes below apply to the next stable release after v0.2.181, and to the beta image today.

The database needs the `vector` extension

The application stores rulebook embeddings for the rules assistant and requires the PostgreSQL vector extension. It checks for it before migrating and refuses to start with a clear error when it is missing.

If your compose file still uses postgres:16, switch the db service to pgvector/pgvector:pg16. It is the same PostgreSQL 16 with the extension pre-installed, so your existing postgres-data folder keeps working:

  db:
    image: postgres:16
    image: pgvector/pgvector:pg16

Then:

docker compose pull
docker compose up -d

If you run your own PostgreSQL server instead, install the pgvector package for your distribution; the application creates the extension itself.

Placeholder secrets are refused

A JWT_SECRET or DATA_PROTECTION_KEY that starts with CHANGEME (any case) stops the application at startup with an error naming the variable. Older compose files and .env.example shipped CHANGEME_GENERATE_AT_LEAST_32_CHARACTERS, which the application used to accept. Replace it with the output of openssl rand -base64 48; a new JWT_SECRET signs everyone out once.

The `manuals` folder

Uploaded rulebooks are stored under /app/manuals. Mount it (./manuals:/app/manuals) or they are lost when the container is recreated.

Everyone signs in once more

Refresh tokens are now stored hashed and kept in an HttpOnly cookie instead of browser storage, and OIDC client secrets are stored encrypted. Sessions that were open before the upgrade stop refreshing, so every user is asked to sign in again once. Scripts that sent the refresh token in the request body to /api/auth/refresh stop working; they have to sign in again instead. Existing OIDC client secrets keep working and are encrypted the next time the provider is saved.

Set `DATA_PROTECTION_KEY`

Installs without DATA_PROTECTION_KEY keep their data protection keys unencrypted in the database, and the application logs a warning at every start. Add a random value of at least 32 characters (openssl rand -base64 48) and restart: the existing keys are encrypted in place and everything you stored keeps working. See Data protection key before you set it.

Reverse proxies must be trusted explicitly

Forwarded headers are only honoured when TRUSTED_PROXIES names your proxy (an IP address or a network such as 172.16.0.0/12). Without it, HTTPS detection and the login limiter use the proxy’s address, and the log shows a warning the first time a forwarded request arrives.

Single sign-on requires HTTPS

Single sign-on only works over HTTPS, localhost excepted. Over plain HTTP on another address the sign-in button disappears and a provider cannot be enabled. Behind a proxy, set TRUSTED_PROXIES and an https Public URL; see Behind a reverse proxy. Local password login keeps working over HTTP.

Single sign-on redirect URIs changed (beta)

This only affects beta images on which single sign-on was already set up. The provider no longer has a short name, so the redirect URIs no longer contain it: register <PUBLIC_URL>/api/auth/oidc/callback and <PUBLIC_URL>/api/auth/oidc/link-callback at your identity provider, in place of the old /api/auth/oidc/<name>/callback and /api/auth/oidc/<name>/link-callback. Settings → Single sign-on → Register at the provider shows both. Until then, signing in through the provider fails with a redirect URI error at the provider. Linked accounts keep working, and old bookmarks to /api/auth/oidc/<name>/login still start the sign-in.

Rolling back

Pin the previous image tag in your compose file and start again. Migrations are forward-only, so restore the database dump you took before upgrading if the previous version fails to start on the newer schema.

A newer version encrypts the stored BoardGameGeek and changedetection.io API keys when it starts, which an older version cannot read. After rolling back, restore the dump or enter those keys again.