Cloud 08 — Docker Compose for the flagship: api, pgvector, Langfuse

What this creates

Three local containers for the flagship: postgres (the pgvector/pgvector image — plain Postgres plus the vector extension), langfuse (self-hosted tracing, pointed at the same Postgres), and api (the flagship's own FastAPI service, built the same way as cloud-01's multi-stage Dockerfile). Nothing here touches AWS or costs anything — it is the local loop you run on every commit, before cloud-09 puts the same shape on Fargate. Pick a startup mode below; the log underneath is a real, measured run on this machine (Docker 28, Compose v2, an Apple-silicon Mac) — not a guess at what would happen.

Preconditions

• cloud-01's multi-stage Dockerfile (with its HEALTHCHECK) for the flagship's own image, built as ./api in the flagship repo.
• docker compose version prints a v2 line — the plugin ships built into Docker Desktop and OrbStack; there is no separate docker-compose v1 binary to install.
• The flagship's ingest milestone reached (pgvector column exists) — this guide wires the container, not the schema; rag-pipeline and project-flagship-1 cover the schema.

Do it

1. compose.yaml — complete; three services, nothing else:

# compose.yaml
services:
  postgres:
    image: pgvector/pgvector:pg16
    restart: unless-stopped
    environment:
      POSTGRES_USER: f1
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set in .env}
      POSTGRES_DB: f1
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U f1 -d f1"]
      interval: 2s
      timeout: 3s
      retries: 10
      start_period: 10s

  langfuse:
    image: langfuse/langfuse:2         # v2 on purpose: the last major that runs on Postgres alone (see note below)
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy       # waits for pg_isready, not just "container exists"
    environment:
      DATABASE_URL: postgresql://f1:${POSTGRES_PASSWORD:?set in .env}@postgres:5432/f1
      NEXTAUTH_SECRET: ${LANGFUSE_NEXTAUTH_SECRET:?set in .env}
      SALT: ${LANGFUSE_SALT:?set in .env}
      NEXTAUTH_URL: http://localhost:3000
    ports:
      - "3000:3000"
    healthcheck:                          # /api/public/health is Langfuse's documented liveness path (v2 and later)
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/api/public/health"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 20s

  api:
    build: ./api
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    # no depends_on: langfuse — the tracing SDK batches and retries in a background
    # thread; a trace call before langfuse answers is queued, not a crash. Gate startup only
    # on what a failed connection actually breaks: the database.
    environment:
      DATABASE_URL: postgresql://f1:${POSTGRES_PASSWORD:?set in .env}@postgres:5432/f1
      LANGFUSE_HOST: http://langfuse:3000
      LANGFUSE_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY:-}
      LANGFUSE_SECRET_KEY: ${LANGFUSE_SECRET_KEY:-}
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request as u; u.urlopen('http://localhost:8000/readyz', timeout=2)"]
      interval: 3s
      timeout: 3s
      retries: 5
      start_period: 10s

volumes:
  pgdata:

2. .env (git-ignored; .env.example in the repo instead):

# .env.example — copy to .env, then fill in real values; .env is git-ignored
POSTGRES_PASSWORD=
LANGFUSE_NEXTAUTH_SECRET=
LANGFUSE_SALT=
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=

3. Makefile — three targets, nothing hidden inside them:

# Makefile
up:
	docker compose up -d --wait   # exits non-zero if any service never reaches healthy

test:
	docker compose ps --format '{{.Service}}: {{.Health}}'
	curl -sf http://localhost:8000/readyz
	curl -sf http://localhost:3000/api/public/health

down:
	docker compose down -v        # -v drops pgdata too — a clean slate, not a pause

Verify

• make up — with --wait, the command itself blocks until every service with a healthcheck reports healthy and fails loudly if one does not within the wait timeout, instead of returning immediately while containers are still starting.
• docker compose ps shows postgres, langfuse and api all Up (healthy) — three, not two: a container with no healthcheck: block just shows Up forever, which is not proof of anything.
• make test passes both curl -f calls (a `-f`-flagged curl exits non-zero on a non-2xx response, so a silent 500 fails the target instead of printing an HTML error page and returning 0).

Teardown

make down
# same as: docker compose down -v
# confirm nothing is left:
docker compose ps -a   # empty
docker volume ls | grep pgdata   # no output — the volume, and every row it held, is gone

After teardown: no container, no volume, no network — pgdata is deliberately dropped with -v so the next make up starts from an empty database, the same as a fresh clone would. Nothing here ever touched AWS, so there is no bill to check.