Development

pip install uv
uv venv
uv sync --all-extras --dev
bun install

Run the dev database, then the app:

docker compose -f docker-compose.dev.yml up -d timescale_db
uv run litestar --app geometrikks.server.core:create_app run --debug

docker-compose.dev.yml also has a dev profile that builds and hot-reloads the whole stack in Docker via Dockerfile.dev, if you would rather not run the app bare-metal:

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

To inspect the live route animation without generating log traffic, open the map with the development-only demo harness. It uses fixed worldwide origins, turns Live mode on, and does not connect to the live-feed WebSocket:

http://localhost:8000/map?demoTraffic=1       # steady traffic
http://localhost:8000/map?demoTraffic=burst   # overlapping bursts

Testing

uv run pytest                    # unit tests, no docker needed

Integration tests need the compose TimescaleDB and are marked integration. When the database is unreachable they are skipped, so the plain run above stays green.

docker compose -f docker-compose.dev.yml up -d timescale_db
uv run pytest -m integration     # the real-database suite

The integration suite creates a scratch database geometrikks_it on the compose server (migrated to alembic head plus timescale objects) and drops it at session end; it never touches the geometrikks dev database. Connection overrides: IT_DB_HOST, IT_DB_PORT, IT_DB_USER, IT_DB_PASSWORD.