Yamtrack/docs/development.md

Development

This page covers working on Yamtrack from source.

Prerequisites

• uv
• tailwindcss CLI (install with npm install -g tailwindcss @tailwindcss/cli)
• Docker
• Redis

General setup

Clone the repository

git clone https://github.com/FuzzyGrim/Yamtrack.git
cd Yamtrack

Start Redis

If you do not already have Redis running locally, start it with Docker:

docker run -d --name redis -p 6379:6379 --restart unless-stopped redis:8-alpine

Install dependencies

uv manages the Python environment and dependencies:

uv sync
uv run pre-commit install

Installing the development dependencies includes pre-commit. After uv run pre-commit install, the hooks run automatically before each commit. You can also run the full hook set manually:

uv run pre-commit run --all-files

Configure environment values

Create a .env file in the repository root:

TMDB_API=API_KEY
MAL_API=API_KEY
IGDB_ID=IGDB_ID
IGDB_SECRET=IGDB_SECRET
STEAM_API_KEY=STEAM_API_SECRET
BGG_API_TOKEN=BGG_API_TOKEN
SECRET=SECRET
DEBUG=True

See Environment Variables for the full list of supported settings.

Prepare the database

cd src
uv run manage.py migrate

Run the app

Run the Django development server:

cd src
uv run manage.py runserver

Run the Celery worker with the scheduler in another terminal:

cd src
uv run celery -A config worker --beat --scheduler django --loglevel DEBUG

Run Tailwind in another terminal:

cd src
tailwindcss -i ./static/css/input.css -o ./static/css/tailwind.css --watch

Open the development server at:

http://localhost:8000

Documentation

Install the docs dependency group, then serve the docs from the current checkout:

uv sync --group docs
uv run zensical serve

Testing

Install Playwright browsers before running integration tests:

uv run playwright install

Run the Django test suite from the src directory:

cd src
uv run manage.py test --parallel

To run tests for a specific app or test module, pass the test label after test:

cd src
uv run manage.py test app.tests --parallel