The Shelf

Self-hosting

The Shelf is one container plus PostgreSQL. A small VM or LXC with Docker is plenty.

Quick start

You need Docker with the Compose plugin. Clone the repository, set a database password and start the stack:

git clone https://github.com/chimericdream/game-inventory.git
cd game-inventory
cp .env.example .env         # set POSTGRES_PASSWORD (and BGG_API_TOKEN if you want lookups)
docker compose -f docker-compose.prod.yml up -d --build
  • The app listens on port 3000. Set APP_PORT to change it.
  • Database migrations run automatically on start.
  • The first visit asks you to create the household and the admin account. There is no default password.
  • Uploaded images live in the app-data volume and the database in db-data.

HTTPS and Tailscale

The Shelf is designed to be reachable over a private network. With Tailscale installed on the host you can serve it over HTTPS on your tailnet:

tailscale serve --bg 3000

Then set COOKIE_SECURE=true so session cookies are only sent over HTTPS.

Leave COOKIE_SECURE at false only while you reach the app over plain HTTP, for example on first setup at localhost.

Automatic updates

Every push to main publishes ghcr.io/chimericdream/game-inventory:latest. The deploy/ folder in the repository is a ready-made stack for a Docker host: the app, PostgreSQL, a Tailscale sidecar that serves HTTPS at https://games.<your-tailnet>.ts.net, and Watchtower, which pulls a new app image every five minutes.

cd deploy
cp .env.example .env     # set TS_AUTHKEY and POSTGRES_PASSWORD
docker compose up -d

Make the GitHub package public after the first publish, or add a registry login for Watchtower. PostgreSQL is never updated automatically.

Backups

scripts/backup.sh dumps the database and the uploaded images. Run it from cron; it keeps the newest 14 backups of each. To restore a database dump:

gunzip -c db-<stamp>.sql.gz | docker compose -f docker-compose.prod.yml exec -T db psql -U games -d games

Upgrading by hand

Pull the latest code and rebuild. Migrations run on start, and they are written to be safe for existing data.

git pull
docker compose -f docker-compose.prod.yml up -d --build

Local development

Want to hack on it? The repository README covers the toolchain (mise, pnpm, Next.js and PostgreSQL in Docker). See also Configuration.