Skip to content

Local Development

This guide covers running Pulse on your own machine: the prerequisites, the full port map, the make targets, and the issues you're most likely to hit.

Prerequisites

Tool Why
Docker + Compose plugin Runs the full stack (make up)
GNU Make Wraps every common workflow
uv ≥ 0.4 Python deps for apps/api, apps/worker, apps/docs
Node 24 LTS + pnpm The apps/web Next.js portal
gh (optional) GitHub workflows; gh auth login

Two ways to run the API

  • Full stack (CI parity): make up runs the pulse-api container alongside every dependency.
  • Host-native loop: cd apps/api && uv sync once, then uv run uvicorn azothedge_pulse_api.main:app --reload. Faster iteration; still talks to the Compose Postgres/Kafka/MinIO.

Port map

Port Service Notes
8000 pulse-api REST API; Swagger UI at /docs
3001 pulse-web Next.js portal (container 3000)
3000 Grafana admin / admin
9090 Prometheus
3100 Loki logs
3200 / 4317 / 4318 Tempo query / OTLP gRPC / OTLP HTTP
5432 Postgres make psql
19092 Redpanda external Kafka listener
18081 / 18082 / 9644 Redpanda schema registry / pandaproxy / admin
8080 Redpanda Console
9000 / 9001 MinIO S3 API / console (pulse / pulsepulse)
1025 / 8025 Mailpit SMTP / web UI
9100 / 9101 pulse-worker Prometheus exposition / /healthz

Why the web portal is on 3001

Grafana owns host port 3000, so pulse-web publishes on 3001 → container 3000.

Make targets

make up        # boot the stack (waits up to 90s for health)
make down      # stop containers, keep volumes
make restart   # down + up
make logs      # tail all service logs
make ps        # container status
make psql      # psql into Postgres (user pulse, db azothedge_pulse)
make test      # pytest in apps/api
make lint      # ruff + mypy
make format    # ruff format + --fix
make build     # build the API image
make clean     # down -v (DESTRUCTIVE: wipes volumes)

Docs-site targets (this site):

make docs-install   # uv sync in apps/docs
make docs-openapi    # regenerate docs/api/openapi.json from the live app
make docs-serve      # serve on http://localhost:8001 (strict, hot reload)
make docs-build      # mkdocs build --strict
make docs-pdf        # build with single-page PDF export (ENABLE_PDF_EXPORT=1)

Common issues

  • Port already in use. make down, find the offender with ss -tlnp, then make up.
  • Postgres unhealthy. make logs; if init failed, make clean && make up (this wipes volumes).
  • Grafana datasources empty. Edit infra/compose/grafana/provisioning/ and make restart.
  • make docs-openapi import error. The generator imports the FastAPI app, so it runs under apps/api's environment — cd apps/api && uv sync if you've never synced it.

See also