Docker Stack
Docker Compose services for PostgreSQL, Redis, and the observability stack
All shared infrastructure runs through docker-compose.yml under the infra profile. The Docker Compose project name is pinned to tx-agent-kit to allow sharing across multiple git worktrees.
Services
PostgreSQL (application database)
| Property | Value |
|---|---|
| Image | postgres:16 (custom Dockerfile with pgTAP extension) |
| Port | 5432 |
| Database | tx_agent_kit |
| Credentials | postgres / postgres |
| Health check | pg_isready -U postgres -d tx_agent_kit |
The application database stores all domain data. Worktrees use separate PostgreSQL schemas within the same database instance, so a single container serves all parallel branches.
Temporal runtime note
Temporal is no longer part of the local Docker infra profile. Local development uses host Temporal CLI (pnpm temporal:dev:up) and deployed environments use Temporal Cloud via environment-driven settings.
Redis
| Property | Value |
|---|---|
| Image | redis:8.6.0-alpine3.23 |
| Port | 6379 |
| Persistence | Append-only file (AOF) enabled |
| Health check | redis-cli ping |
OpenTelemetry Collector
| Property | Value |
|---|---|
| Image | otel/opentelemetry-collector-contrib:0.146.1 |
| OTLP HTTP port | 4318 (mapped to host 4320) |
| OTLP gRPC port | 4317 (mapped to host 4319) |
| Health check port | 13133 |
| Metrics port | 8888 |
The collector receives all telemetry signals (traces, metrics, logs) from applications via OTLP and routes them to Jaeger, Prometheus, and Loki. The host port mapping (4318 -> 4320) avoids conflicts with Jaeger's native OTLP receiver.
Jaeger
| Property | Value |
|---|---|
| Image | jaegertracing/jaeger:2.15.1 |
| UI port | 16686 |
| OTLP ports | 4317 (gRPC), 4318 (HTTP) |
Jaeger provides distributed trace visualization. In the local stack, both the collector and Jaeger expose OTLP endpoints; the collector is the primary ingestion path.
Prometheus
| Property | Value |
|---|---|
| Image | prom/prometheus:v3.9.1 |
| Port | 9090 |
| Features | OTLP receiver enabled, lifecycle API enabled |
| Config | monitoring/local/prometheus/prometheus.yml |
Prometheus stores metrics and supports both pull-based scraping and push-based OTLP ingestion. Alert rules live in monitoring/local/prometheus/rules/.
Loki
| Property | Value |
|---|---|
| Image | grafana/loki:3.6.6 |
| Port | 3100 |
| Config | monitoring/local/loki/loki-config.yml |
Loki aggregates structured logs. Promtail ships Docker container logs to Loki automatically.
Grafana
| Property | Value |
|---|---|
| Image | grafana/grafana:12.3.3 |
| Port | 3001 (configurable via GRAFANA_PORT) |
| Credentials | admin / admin |
Grafana is pre-provisioned with datasources for Prometheus, Loki, and Jaeger, along with pre-built dashboards. If port 3001 is occupied, the startup script automatically selects the next available port.
Starting and stopping
# Start all infrastructure (idempotent)
pnpm infra:ensure
# Stop and remove volumes
pnpm infra:downThe infra:ensure script checks health of every service before returning. If Docker is not running, it exits with a clear error. Port conflicts with non-infrastructure processes are detected and reported before starting containers.
Compose project name
The Docker Compose project is pinned to tx-agent-kit regardless of which directory the command runs from. This ensures all worktrees share the same infrastructure containers, avoiding duplicate service instances.
# This is set automatically by the startup script
COMPOSE_PROJECT_NAME=tx-agent-kit