Local Development

Docker Compose Quick Start#

Run these commands from the repository root:

cp .env.example .env
cp .env.example backend/.env
docker compose up --build -d
docker compose ps

The root Compose file starts PostgreSQL, PgBouncer, Redis, the OpenTelemetry collector, Temporal, Temporal UI, the FastAPI backend, the Temporal worker, the PgBouncer exporter, and the product Next.js frontend.

Optional Admin Control Plane#

The admin panel and admin API use a separate Compose file. Start the root stack first so the shared matruno-network, PostgreSQL, PgBouncer, and Redis services exist, then run:

docker compose -f admin-panel/docker-compose.admin.yml up -d --build admin-api admin-panel

The admin compose path reads local bootstrap variables such as ADMIN_LOCAL_DEV_*. Set your own local values and do not publish credentials in docs, logs, screenshots, or shared environments.

Health Checks#

curl -fsS http://localhost:5678/health
curl -fsS http://localhost:5678/health/aggregate
curl -N http://localhost:5678/health/stream

Use docker compose logs backend, docker compose logs worker, and docker compose logs temporal when a health check fails.

Hybrid Local Development#

Use this mode when you want Docker-managed infrastructure but local app processes. The root Compose file publishes PostgreSQL and Temporal to the host, but Redis is internal-only by default. Before running host processes, point backend/.env at reachable PostgreSQL, Redis, and Temporal endpoints; run Redis locally or expose it with a local Compose override if you need Redis-backed cache/session behavior.

docker compose up -d postgres temporal temporal-ui

Then run the backend:

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --host 0.0.0.0 --port 5678

Run the Temporal worker from another shell:

cd backend
source .venv/bin/activate
python -m app.temporal.worker

Run the frontend from another shell:

cd frontend
npm install
npm run dev

Documentation App#

The docs app has its own package under docs/:

cd docs
npm run dev

The docs server listens on http://localhost:3457. Docker-only docs operation is also available through docs/docker-compose.docs.yml.

Stop the Stack#

docker compose down

Use named volumes carefully. PostgreSQL, Redis, and generated artifacts use Compose-managed volumes, so removing volumes also removes local data.