docker-compose.yml

# CollabHub local development stack (Conventions §11).
#
# Copy .env.example to .env first — every value below comes from there.
# Image versions are pinned from docs/platform/versions.md, which wins over the
# design docs.
#
# The three Redis instances are separate containers, not three databases on one
# instance, because they are not interchangeable (Conventions §6, §7): R1 is the
# cache and token denylist, R2 the Socket.IO backplane, R3 the job streams.
# Running them apart locally is what stops them being conflated in code.

name: collabhub

x-service-common: &service-common
  restart: unless-stopped
  env_file: .env
  environment: &service-env
    APP_ENV: ${APP_ENV}
    LOG_LEVEL: ${LOG_LEVEL}
    AUTH_ISSUER: ${AUTH_ISSUER}
    AUTH_AUDIENCE: ${AUTH_AUDIENCE}
    AUTH_JWKS_URL: ${AUTH_JWKS_URL}
    OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT}

x-http-healthcheck: &http-healthcheck
  healthcheck:
    test:
      [
        "CMD",
        "python",
        "-c",
        "import urllib.request;urllib.request.urlopen('http://localhost:8000/health/live')",
      ]
    interval: 10s
    timeout: 3s
    retries: 5
    start_period: 10s

services:
  # ---------------------------------------------------------------------------
  # Infrastructure
  # ---------------------------------------------------------------------------
  postgres:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_USER}
    volumes:
      # Postgres 18 stores data in a major-version subdirectory, so the mount
      # goes at /var/lib/postgresql — not /var/lib/postgresql/data as it did
      # before 18. Mounting the old path makes the image refuse to start.
      - postgres-data:/var/lib/postgresql
      - ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/10-databases.sql:ro
    ports:
      - "${POSTGRES_PORT}:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 5s
      timeout: 3s
      retries: 10

  redis-cache: # R1 — cache and token denylist
    image: redis:8
    restart: unless-stopped
    volumes:
      - redis-cache-data:/data
    healthcheck: &redis-healthcheck
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

  redis-rt: # R2 — Socket.IO backplane. Ephemeral by nature; no volume.
    image: redis:8
    restart: unless-stopped
    healthcheck: *redis-healthcheck

  redis-streams: # R3 — async job streams. Persisted: unacked jobs are work.
    image: redis:8
    restart: unless-stopped
    volumes:
      - redis-streams-data:/data
    healthcheck: *redis-healthcheck

  garage:
    image: dxflrs/garage:v2.3.0
    restart: unless-stopped
    volumes:
      - ./docker/garage/garage.toml:/etc/garage.toml:ro
      - garage-meta:/var/lib/garage/meta
      - garage-data:/var/lib/garage/data
    ports:
      - "3900:3900" # S3 API
      - "3903:3903" # admin API

  garage-bootstrap:
    # One-shot: gives a fresh Garage its layout, the bucket, the app's key and the
    # bucket's CORS rules, then exits. Garage serves no S3 traffic until a layout
    # is assigned, and the image has no shell to run its own CLI from, so the same
    # stdlib script the test stack, k3d and testkit run does it over the admin API.
    # Every step checks before it acts, so it is safe on every `up`. `asset` waits
    # for it to complete.
    image: python:3.12-slim
    restart: "no"
    command: ["python", "/bootstrap/garage-bootstrap.py"]
    volumes:
      - ./charts/collabhub-deps/files/garage-bootstrap.py:/bootstrap/garage-bootstrap.py:ro
    environment:
      GARAGE_ADMIN_URL: http://garage:3903
      GARAGE_ADMIN_TOKEN: ${GARAGE_ADMIN_TOKEN}
      GARAGE_BUCKET: ${OBJECT_STORE_BUCKET}
      GARAGE_ACCESS_KEY_ID: ${OBJECT_STORE_ACCESS_KEY}
      GARAGE_SECRET_ACCESS_KEY: ${OBJECT_STORE_SECRET_KEY}
      GARAGE_CAPACITY_BYTES: "1073741824"
      GARAGE_CORS_ORIGINS: ${GARAGE_CORS_ORIGINS}
    depends_on:
      garage: {condition: service_started}

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.4.3
    restart: unless-stopped
    environment:
      discovery.type: single-node
      xpack.security.enabled: "false"
      ES_JAVA_OPTS: -Xms512m -Xmx512m
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data
    ports:
      - "9200:9200"
    healthcheck:
      test: ["CMD-SHELL", "curl -fs http://localhost:9200/_cluster/health || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 20
      start_period: 30s

  dex:
    # The upstream identity provider (register D5). CollabHub's Auth service
    # federates to this; it is never an OIDC provider itself.
    image: ghcr.io/dexidp/dex:v2.45.1
    restart: unless-stopped
    command: ["dex", "serve", "/etc/dex/config.yaml"]
    environment:
      # Referenced by `hashFromEnv` in the config. Dex expands environment
      # variables only in its storage, signer and connector blocks, and only
      # behind a feature flag, so this indirection is how a password hash gets
      # in — and it keeps a string starting `$2b$` out of a file that might one
      # day be expanded.
      DEX_PASSWORD_HASH: ${DEX_PASSWORD_HASH}
    volumes:
      - ./docker/dex/config.yaml:/etc/dex/config.yaml:ro
    ports:
      # The host port must match the port inside the issuer URL. An OIDC issuer
      # is an identity, not an address: it is what Dex puts in `iss` and what
      # Auth checks the id_token against, so the browser and the token have to
      # agree on it. Changing DEX_PORT means changing `issuer` in
      # docker/dex/config.yaml too.
      - "${DEX_PORT}:5556"
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:5558/healthz"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 5s

  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.156.0
    restart: unless-stopped
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./docker/otel-collector/config.yaml:/etc/otel/config.yaml:ro
    ports:
      - "4317:4317" # OTLP gRPC
      - "4318:4318" # OTLP HTTP

  # ---------------------------------------------------------------------------
  # Services
  # ---------------------------------------------------------------------------
  auth:
    <<: [*service-common, *http-healthcheck]
    build:
      context: .
      dockerfile: docker/auth/Dockerfile
    environment:
      <<: *service-env
      # .env namespaces the DSNs per service; each container sees only its own,
      # under the name Conventions §8 specifies.
      POSTGRES_DSN: ${AUTH_POSTGRES_DSN}
      REDIS_CACHE_URL: ${REDIS_CACHE_URL}
      OIDC_PROVIDERS: ${OIDC_PROVIDERS}
      SPA_REDIRECT_URI: ${SPA_REDIRECT_URI}
      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS}
    ports:
      - "${AUTH_PORT}:8000"
    depends_on:
      postgres: {condition: service_healthy}
      redis-cache: {condition: service_healthy}
      dex: {condition: service_healthy}

  messaging:
    <<: [*service-common, *http-healthcheck]
    build:
      context: .
      dockerfile: docker/messaging/Dockerfile
    environment:
      <<: *service-env
      POSTGRES_DSN: ${MESSAGING_POSTGRES_DSN}
      REDIS_CACHE_URL: ${REDIS_CACHE_URL}
      REDIS_REALTIME_URL: ${REDIS_REALTIME_URL}
      REDIS_STREAMS_URL: ${REDIS_STREAMS_URL}
      # Read-only, for GET /search/messages. Deliberately not in depends_on: an
      # Elasticsearch outage degrades search, it does not stop chat starting.
      ELASTICSEARCH_URL: ${ELASTICSEARCH_URL}
      # The SPA is a separate origin locally, so the browser will not call this
      # service at all without it (Conventions §5.6).
      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS}
      # Claiming a send's attachments: Asset's internal API, called with this
      # service's own token from Auth (Conventions §5.5).
      SERVICE_TOKEN_URL: ${SERVICE_TOKEN_URL}
      ASSET_INTERNAL_URL: ${ASSET_INTERNAL_URL}
      MESSAGING_SERVICE_CLIENT_ID: ${MESSAGING_SERVICE_CLIENT_ID}
      MESSAGING_SERVICE_CLIENT_SECRET: ${MESSAGING_SERVICE_CLIENT_SECRET}
    ports:
      - "${MESSAGING_PORT}:8000"
    depends_on:
      postgres: {condition: service_healthy}
      redis-cache: {condition: service_healthy}
      redis-rt: {condition: service_healthy}
      redis-streams: {condition: service_healthy}
      # Not a readiness dependency (a send with no files never calls Asset), but
      # it should be there when the first attachment is sent.
      asset: {condition: service_started}

  canvas:
    <<: [*service-common, *http-healthcheck]
    build:
      context: .
      dockerfile: docker/canvas/Dockerfile
    environment:
      <<: *service-env
      POSTGRES_DSN: ${CANVAS_POSTGRES_DSN}
      REDIS_CACHE_URL: ${REDIS_CACHE_URL}
      REDIS_REALTIME_URL: ${REDIS_REALTIME_URL}
    ports:
      - "${CANVAS_PORT}:8000"
    depends_on:
      postgres: {condition: service_healthy}
      redis-cache: {condition: service_healthy}
      redis-rt: {condition: service_healthy}

  asset:
    <<: [*service-common, *http-healthcheck]
    build:
      context: .
      dockerfile: docker/asset/Dockerfile
    environment:
      <<: *service-env
      POSTGRES_DSN: ${ASSET_POSTGRES_DSN}
      # R1 for the token denylist (`require_user`), R3 for thumbnail jobs.
      REDIS_CACHE_URL: ${REDIS_CACHE_URL}
      REDIS_STREAMS_URL: ${REDIS_STREAMS_URL}
      # The SPA calls `upload-url` and `confirm` directly, from another origin.
      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS}
      OBJECT_STORE_ENDPOINT: ${OBJECT_STORE_ENDPOINT}
      OBJECT_STORE_PUBLIC_ENDPOINT: ${OBJECT_STORE_PUBLIC_ENDPOINT}
      OBJECT_STORE_ACCESS_KEY: ${OBJECT_STORE_ACCESS_KEY}
      OBJECT_STORE_SECRET_KEY: ${OBJECT_STORE_SECRET_KEY}
      OBJECT_STORE_BUCKET: ${OBJECT_STORE_BUCKET}
      OBJECT_STORE_PRESIGN_TTL_SECONDS: ${OBJECT_STORE_PRESIGN_TTL_SECONDS}
      ASSET_MAX_UPLOAD_BYTES: ${ASSET_MAX_UPLOAD_BYTES}
    ports:
      - "${ASSET_PORT}:8000"
    depends_on:
      postgres: {condition: service_healthy}
      redis-cache: {condition: service_healthy}
      redis-streams: {condition: service_healthy}
      # Garage serves nothing until the bootstrap has run.
      garage-bootstrap: {condition: service_completed_successfully}

  worker:
    <<: [*service-common, *http-healthcheck]
    build:
      context: .
      dockerfile: docker/worker/Dockerfile
    environment:
      <<: *service-env
      REDIS_STREAMS_URL: ${REDIS_STREAMS_URL}
      ELASTICSEARCH_URL: ${ELASTICSEARCH_URL}
      OBJECT_STORE_ENDPOINT: ${OBJECT_STORE_ENDPOINT}
      OBJECT_STORE_ACCESS_KEY: ${OBJECT_STORE_ACCESS_KEY}
      OBJECT_STORE_SECRET_KEY: ${OBJECT_STORE_SECRET_KEY}
      OBJECT_STORE_BUCKET: ${OBJECT_STORE_BUCKET}
      SERVICE_TOKEN_URL: ${SERVICE_TOKEN_URL}
      ASSET_INTERNAL_URL: ${ASSET_INTERNAL_URL}
    ports:
      - "${WORKER_PORT}:8000" # health only; the Worker exposes no API
    depends_on:
      redis-streams: {condition: service_healthy}
      elasticsearch: {condition: service_healthy}

  frontend:
    restart: unless-stopped
    build:
      context: .
      dockerfile: docker/frontend/Dockerfile
      # Only VITE_-prefixed vars reach the bundle, and they are baked at build
      # time — never put a secret here.
      args:
        VITE_AUTH_URL: ${VITE_AUTH_URL}
        VITE_MESSAGING_URL: ${VITE_MESSAGING_URL}
        VITE_CANVAS_URL: ${VITE_CANVAS_URL}
        VITE_ASSET_URL: ${VITE_ASSET_URL}
    ports:
      - "${FRONTEND_PORT}:8080"
    healthcheck:
      # Nginx serving static files has no /health endpoint, so this probes `/` —
      # the same path the chart's liveness and readiness probes use. Without it
      # `up --wait` treats "running" as ready, and `scripts/test.sh e2e` would
      # race the browser against a server still starting. 127.0.0.1, not
      # localhost: Nginx listens on IPv4 only, and busybox wget may try ::1.
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8080/"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 5s

volumes:
  postgres-data:
  redis-cache-data:
  redis-streams-data:
  garage-meta:
  garage-data:
  elasticsearch-data: