Development Setup

Development Setup

Prerequisites

Requirement	Version
JDK	25+
Maven	3.9+ (or use included mvnw wrapper)
Docker	Optional, for local/production deployment
gh CLI	For GitHub PR workflow
Playwright Chromium	For team card generation and E2E tests

Playwright Setup

Team card generation and E2E tests require a local Chromium browser managed by Playwright.

Install Chromium (all platforms)

./mvnw exec:java -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install chromium"

The Chromium binary is downloaded to the platform-specific cache:

Platform	Cache Location
macOS	~/Library/Caches/ms-playwright/
Linux	~/.cache/ms-playwright/
Windows	%LOCALAPPDATA%\ms-playwright\

Linux: Additional OS Dependencies

On Linux (Debian/Ubuntu), Chromium requires native shared libraries. Install them via Playwright or manually:

# Via Playwright (recommended — installs exactly what's needed)
./mvnw exec:java -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install-deps chromium"

# Or manually (Debian/Ubuntu)
sudo apt-get install -y libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 \
    libgbm1 libpango-1.0-0 libcairo2 libasound2t64 libxshmfence1

macOS and Windows include these libraries natively — no extra setup needed.

Docker

The Dockerfile installs Chromium automatically during the image build. No manual setup required.

Running the Application

Development (H2 in-memory database)

./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Starts on http://localhost:9090 with an empty H2 database.

Development with Demo Data

./mvnw spring-boot:run -Dspring-boot.run.profiles=dev,demo

Same as dev, but auto-imports all GT7 cars and tracks (with images) at startup for manual testing.

Local with MariaDB

./mvnw spring-boot:run -Dspring-boot.run.profiles=local

Requires a running MariaDB instance on localhost. Starts on port 9091.

Docker Compose (App + MariaDB)

docker compose up --build -d    # Start
docker compose down              # Stop

Starts on http://localhost:8080 with MariaDB on port 3307.

Running Tests

./mvnw verify

Runs all unit tests, integration tests, and verification checks.

Git Workflow

Branch Strategy

• Default branch: master
• Feature branches: feature/<short-description>
• Fix branches: fix/<short-description>
• Always branch from master

Pull Request Flow

1. Create a feature branch:

   git switch -c feature/my-feature master

2. Implement changes, then run tests:

   ./mvnw verify

3. Commit with a descriptive German commit message:

   git add <files>
   git commit -m "Beschreibung der Aenderung"

4. Push and create a PR:

   git push -u origin feature/my-feature
   gh pr create --assignee jegr78

5. After CI passes, merge with squash:

   gh pr merge --squash

6. Clean up:

   git switch master && git pull && git branch -d feature/my-feature

CI Checks

After creating a PR, verify the CI build:

gh run list --branch feature/my-feature
gh run view <run-id>
gh run view --log-failed    # If CI fails

PRs must have a green CI build before merging.

Documentation Updates

When adding a new feature, update all relevant documentation:

1. CLAUDE.md -- Project instructions for AI-assisted development
2. README.md -- User-facing project overview
3. Wiki -- Detailed documentation pages (this wiki)