Compose services

title: Compose services description: The four services in fathomdx's docker-compose stack, their ports, and their dependencies. Generated from docker-compose.yml. audience: operator quadrant: reference last_verified: 2026-04-25 owners: [docker-compose.yml]

Compose services

The fathomdx stack boots four services. Three are HTTP servers; one is the database they share.

Service	Image	Host port	Container port	Purpose
postgres	`pgvector/pgvector:pg17`	`127.0.0.1:5432:5432`	5432	Lake storage. pgvector/pg17. Cannot run on Dropbox-synced paths.
delta-store	`(built locally)`	`127.0.0.1:4246:8000` `[::1]:4246:8000`	8000	HTTP API over the lake. Write, query, embed, search, engage.
source-runner	`(built locally)`	`127.0.0.1:4260:8000`	8000	Polls external sources (RSS, Mastodon, vault, Home Assistant) and writes deltas.
api	`(built locally)`	`0.0.0.0:8201:8200`	8200	Consumer API + dashboard UI. The public entry point.

Service ordering on boot

Compose's depends_on with condition: service_healthy means dependent services wait for upstream health checks to pass before starting. Cold-boot order:

postgres → delta-store → source-runner
                      → api

First boot can take 60–90 seconds because postgres has to initialize, delta-store has to migrate the schema, and the api has to embed the bootstrap deltas. Subsequent boots are faster (under 10 seconds typical).

Health checks

Every service has a /health endpoint and a compose-level health check.

postgres uses pg_isready -U fathom -d deltas.
delta-store, source-runner, and api each check /health returns 200.

When debugging a stuck stack: docker compose ps shows current health state per service. docker compose logs <service> shows what each one is doing during startup.