Development

The local environment runs on .NET Aspire: one AppHost starts the pgvector database, Ollama, the API and the Vite dev server. CONTRIBUTING.md lists the checks that run on every pull request and the conventions used in the code base.

Prerequisites

• .NET 10 SDK
• Node.js 22 — enable pnpm with corepack enable
• Docker Desktop (Aspire starts the pgvector database as a container; it must be running)
• Git

Running locally with Aspire

1. Clone the repository and install the dependencies:

   Terminal

   git clone https://github.com/mregni/BoardGameTracker.git
   cd BoardGameTracker
   dotnet restore
   corepack enable
   cd boardgametracker.client
   pnpm install

2. Optionally configure SMTP. Without your own SMTP settings Aspire points at smtp.example.com: the email features show up but sending fails. To test email, put your provider’s settings, or those of a local catcher such as smtp4dev or Mailpit, in the AppHost’s user-secrets store so they stay out of source control (the Smtp section in BoardGameTracker.AppHost/appsettings.Development.json lists every key):

   Terminal

   dotnet user-secrets set "Smtp:Host" "smtp.your-provider.com" --project BoardGameTracker.AppHost
   dotnet user-secrets set "Smtp:Username" "<your-smtp-user>" --project BoardGameTracker.AppHost
   dotnet user-secrets set "Smtp:FromAddress" "noreply@your-domain.com" --project BoardGameTracker.AppHost
   dotnet user-secrets set "Parameters:smtp-password" "<your-smtp-password>" --project BoardGameTracker.AppHost

3. Start the whole stack:

   Terminal

   dotnet run --project BoardGameTracker.AppHost --launch-profile http

   This launches the Aspire dashboard and, as separate resources, the database, Ollama, the API and the UI. All backend configuration (database, auth, SMTP, AI/RAG, …) is defined in BoardGameTracker.AppHost/AppHost.cs; the http and https launch profiles are in BoardGameTracker.AppHost/Properties/launchSettings.json, and the Host project has no launchSettings.json.

4. Once the resources are healthy, open:

   • UI — http://localhost:5443
   • API & Swagger — http://localhost:6554/swagger
   • Aspire dashboard — the URL printed in the console at startup

   The database is created and migrated automatically on first run, and its data persists in a Docker volume across restarts.

AI rules assistant (RAG)

The optional rules assistant runs locally: Aspire starts an Ollama resource, and the required models are pulled when the API starts (a few GB the first time, then cached in a Docker volume). GPU acceleration is on by default; set Ollama__UseGpu=false to run Ollama on CPU if your host has no GPU with container passthrough. To use a hosted chat model instead, set Ai:Provider to openai plus Ai:BaseUrl and Ai:ChatModel in the AppHost user-secrets, and the key with dotnet user-secrets set "Parameters:ai-api-key" "<key>" --project BoardGameTracker.AppHost; Aspire then no longer waits for Ollama before starting the API.

HTTPS dashboard

The http launch profile serves the Aspire dashboard over plain HTTP. To use the https profile instead, trust the local dev certificate once with dotnet dev-certs https --trust.

Tests

Terminal

dotnet test
cd boardgametracker.client
pnpm test:run

The integration tests start a PostgreSQL container, so Docker must be running.

Production uses Docker

Aspire is a development-only tool and is never deployed. Production runs from the published container via Docker Compose; see the quick start.