README.md

BoardGameTracker

A self-hosted board game statistics tracker for analyzing your collection and gaming sessions

---

Overview

BoardGameTracker is a self-hosted application designed for board game enthusiasts who want to:

• Track spending on their collection
• Analyze game statistics and identify favorites
• Monitor player performance and win rates
• Visualize gaming trends over time

Integration with BoardGameGeek (BGG) is under review because of authentication on their API.

⚠️ Note: This project is under active development. Breaking changes may occur between releases.

---

Installation

Prerequisites

• Docker installed on your system
• PostgreSQL database (can be run via Docker Compose)

Quick Start with Docker Compose (Recommended)

1. Download the docker-compose.yml file or create one with the following content:

services:
  boardgametracker:
    image: uping/boardgametracker:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./images:/app/images
      - ./logs:/app/logs
    ports:
      - "5444:5444"
    environment:
      - DB_HOST=db
      - DB_USER=dbuser
      - DB_PASSWORD=CHANGEME
      - DB_NAME=boardgametracker
      - DB_PORT=5432
      - TZ=UTC
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5444/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres:16
    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

2. Update the placeholder values:

   • Set the correct file paths
   • Change CHANGEME passwords to secure values
   • Adjust timezone (TZ) to your location

3. Start the containers:

docker-compose up -d

1. Access the application at http://localhost:5444

Docker Run Command

If you prefer using Docker CLI or have an existing PostgreSQL instance:

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

---

Configuration

Environment Variables

Variable	Default	Required	Description
DB_HOST	-	✅	PostgreSQL hostname
DB_PORT	5432	❌	PostgreSQL port
DB_USER	-	✅	PostgreSQL username
DB_PASSWORD	-	✅	PostgreSQL password
DB_NAME	boardgametracker	❌	PostgreSQL database name
STATISTICS	0	❌	Enable/disable Sentry logging (0=off, 1=on)
DATE_FORMAT	yyyy-MM-dd	❌	Date format (date-fns format)
TIME_FORMAT	HH:mm	❌	Time format (date-fns format)
TZ	Utc	❌	Timezone (e.g., America/New_York, Asia/Tokyo)
CURRENCY	€	❌	Currency symbol for collection value tracking

---

Screenshots

Click to view screenshots

Game Collection

Game Details & Statistics

Player Statistics

Session Recording

---

Technology Stack

Backend

• .NET 8.0
• Entity Framework Core
• PostgreSQL
• Serilog for logging

Frontend

• React 18
• TypeScript
• TanStack Router & Query
• Tailwind CSS
• Radix UI
• Vite

Infrastructure

• Docker & Docker Compose
• GitHub Actions CI/CD
• SonarCloud code quality analysis

---

Development

Building from Source

1. Clone the repository:

git clone https://github.com/mregni/BoardGameTracker.git
cd BoardGameTracker

2. Run with Docker Compose:

docker-compose -f docker-compose.build.yml up --build

Running Tests

Backend:

dotnet test

Frontend:

cd boardgametracker.client
npm test

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

Support

If you encounter any issues or have questions:

• Open an issue
• Check existing discussions

---

Acknowledgments

• Tested with BrowserStack
• Translations managed with Crowdin
• Game data from BoardGameGeek