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

Live routes fly to the home of the source that recorded them (see Multi-source setup); with a single source that is the app server’s own location, discovered at startup through ipify and looked up in the local GeoLite2 database. MAP_HOME_LATITUDE and MAP_HOME_LONGITUDE override that default home, MAP_HOME_LOCATIONS overrides per source, and MAP_AUTO_DETECT_HOME=false disables the outbound lookup. The map’s Route effects control can also hide the animation; that preference is kept in browser storage.

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.