Docker Compose Topology
Last updated April 25, 2026
Understand the local Matruno Docker Compose topology, service ports, volumes, worker startup, and docs app isolation.
Product runtime services#
Root docker-compose.yml defines the product runtime and names the project matruno. It publishes frontend, backend, Temporal, Temporal UI, OTLP, collector health, and PostgreSQL ports while keeping Redis and PgBouncer internal to the Compose network.
| Service | Container | Default host port | Responsibility |
| --- | --- | --- |
| PostgreSQL | matruno-postgres | 5433 | Primary transactional store and pgvector |
| PgBouncer | matruno-pgbouncer | internal | Connection pooling |
| Redis | matruno-redis | internal | Cache, coordination, locks, queues |
| OpenTelemetry collector | matruno-otel-collector | 4317, 4318, 13133 | OTLP receive/export and health |
| Temporal | matruno-temporal-server | 7233 | Durable workflow server |
| Temporal UI | matruno-temporal-ui | 8233 | Workflow visibility |
| Backend | matruno-backend | 5678 | FastAPI API |
| Worker | matruno-worker | internal | Temporal workflows and activities |
| PgBouncer exporter | matruno-pgbouncer-exporter | internal | Pool metrics |
| Frontend | matruno-frontend | 3456 | Main Next.js app |
Optional admin control plane#
The admin panel and admin API use admin-panel/docker-compose.admin.yml and expect the root stack's shared network and infrastructure services to exist.
| Service | Container | Default host port | Responsibility |
| --- | --- | --- |
| Admin API | matruno-admin-api | 5680 | Platform-admin FastAPI boundary |
| Admin panel | matruno-admin-panel | 5679 | Platform admin surface |
Volumes#
Compose defines matruno-pg-data, matruno-redis-data, and matruno-storage-data. Back up PostgreSQL and artifact storage together if you need to preserve matter documents and generated artifacts.
Worker startup#
The worker waits for Temporal and backend health, then starts python -m app.temporal.worker. The worker registers task, agent, and email workflow queues and can start optional persistent email workflows depending on START_OPTIONAL_EMAIL_WORKFLOWS.
Documentation app isolation#
The documentation site is a separate Next.js app under docs/ with its own Dockerfile and docker-compose.docs.yml. Run it independently:
cd docs
docker compose -f docker-compose.docs.yml up --build
By default the docs publish on http://localhost:3457.
Compose is the reference topology
Use Compose as the concrete local reference for ports, health checks, and service boundaries. Production deployments should translate these dependencies to your infrastructure rather than assuming a one-click deploy exists.
Was this helpful?