Developer setup¶

This page documents the supported contributor setup and advanced debug workflows.

When to use this page¶

Use this page when setting up a contributor environment, choosing a run mode, or running the local quality gates.

Audience¶

Contributors working on backend/ or frontend/.
Maintainers validating local developer environments before CI.

Prerequisites¶

Tool	Supported version or role
Python	3.12 or 3.14 (CI tests both; containers run 3.14)
uv	Backend dependency and command runner
Node.js	24
npm	Frontend dependencies and scripts
Docker with Compose	Containerized stack

Install dependencies¶

From the repository root:

uv sync --project backend --all-packages --all-groups --frozen
npm --prefix frontend ci

Use uv sync without --frozen only when intentionally updating the backend lock state.

Run modes — choose one intentionally¶

Isolated deployment for reworks¶

Use the local deployment workflow to build and run the current checkout as a complete local application. It uses a compiled frontend, the normal backend services, a separate persistent database, captured email, and local MQTT infrastructure. Its ports, images, and Compose project are separate from the default stack and other previews.

Mode 1: Full stack in containers¶

cp .env.example .env
docker compose up -d --build

Use this mode for parity with documented local operations.

Mode 2: Frontend on the host, backend in containers¶

Start the backend stack with Docker Compose.
Set the host-side frontend API URL to http://localhost:8000.
Start Vite:

npm --prefix frontend run dev

Mode 3: Backend quality loop¶

uv run --project backend ruff check .
uv run --project backend python -m pytest -q

Host versus container expectations¶

Concern	Host runtime	Container runtime
Gateway URL for frontend	`http://localhost:8000`	`http://api-gateway:8000`
Database host	Host-mapped address	Compose service name such as `timescaledb`
Log access	Process standard output	`docker compose logs -f <service>`
Networking	Published ports	Compose service DNS

If requests fail after switching modes, check API_PROXY_TARGET (the Vite dev proxy target) and the configured CORS origins first.

Debug patterns¶

Follow the main backend services:

docker compose logs -f api-gateway tactic-middleware db-sync mqtt-proxy

Run a focused backend test from the root:

uv run --project backend python -m pytest path/to/test_file.py -q

For an IDE debugger, keep its environment aligned with .env, and use Compose service names only from code that runs inside the Compose networks.

Pre-commit and local quality gate¶

uv run --project backend pre-commit install
uv run --project backend pre-commit run --all-files
uv run --project backend ruff check .
uv run --project backend python -m pytest -q
npm --prefix frontend run lint
npm --prefix frontend test
npm --prefix frontend run build

Failure-oriented setup triage¶

Symptom	Likely cause	First action
Frontend cannot call the API in host mode	`API_PROXY_TARGET` still uses container DNS	Set it to `http://localhost:8000`
Gateway restarts during boot	Database schema is not ready	Wait, then inspect `db-sync` and gateway logs
Monitoring endpoints return upstream errors	TACTIC is not ready or cannot reach the Docker API proxy	Check http://localhost:8001/ready and TACTIC logs
Pre-commit fails unexpectedly	Dependencies differ from the lockfiles	Re-run the frozen dependency installs