docker-compose.yml

# Open Content's three services (EN-205) share one image and environment.
x-open-content: &open-content
  image: unlocked-open-content:dev
  build:
    # Built straight from GitHub (OPEN_CONTENT_REF, default main), so no
    # checkout is needed. Set OPEN_CONTENT_DIR to your checkout to build your
    # own changes instead.
    context: ${OPEN_CONTENT_DIR:-https://github.com/UnlockedLabs/unlocked-open-content.git#${OPEN_CONTENT_REF:-main}}
    args:
      APP_VERSION: dev
      GIT_COMMIT: ${OPEN_CONTENT_GIT_COMMIT:-unknown}
      GIT_BRANCH: ${OPEN_CONTENT_GIT_BRANCH:-unknown}
  networks:
    - intranet
  environment:
    APP_DSN: postgres://unlocked:dev@postgres:5432/unlocked
    APP_ENV: dev
    APP_URL: http://server:8080
    KRATOS_PUBLIC_URL: http://kratos:4433
    LOG_LEVEL: debug
    NATS_URL: nats:4222
    NATS_USER: unlocked
    NATS_PASSWORD: dev
    KIWIX_SERVER_URL: https://kiwix.dev.unlockedlabs.xyz
    MIDDLEWARE_CRON_SCHEDULE: 0 22 * * *
    PROXY_SCHEME_OVERRIDE: "false"
    # The secret core asks Open Content's questions with; the server's matches.
    OPEN_CONTENT_TOKEN: dev-open-content-token

# Provider Platforms' three services (EN-206) share one image and environment.
x-provider-platforms: &provider-platforms
  image: unlocked-provider-platforms:dev
  build:
    # Built straight from GitHub (PROVIDER_PLATFORMS_REF, default main), so no
    # checkout is needed. Set PROVIDER_PLATFORMS_DIR to your checkout to build
    # your own changes instead.
    context: ${PROVIDER_PLATFORMS_DIR:-https://github.com/UnlockedLabs/unlocked-provider-platforms.git#${PROVIDER_PLATFORMS_REF:-main}}
    args:
      APP_VERSION: dev
      GIT_COMMIT: ${PROVIDER_PLATFORMS_GIT_COMMIT:-unknown}
      GIT_BRANCH: ${PROVIDER_PLATFORMS_GIT_BRANCH:-unknown}
  networks:
    - intranet
  environment: &provider-platforms-env
    APP_DSN: postgres://unlocked:dev@postgres:5432/unlocked
    APP_ENV: dev
    APP_KEY: base64:NTQxODNmNDMyM2YzNzdiNzM3NDMzYTFlOTgyMjllYWQwZmRjNjg2ZjkzYmFiMDU3ZWNiNjEyZGFhOTQwMDJiNSAgLQo=
    LOG_LEVEL: debug
    NATS_URL: nats:4222
    NATS_USER: unlocked
    NATS_PASSWORD: dev

# Programs' three services share one image and environment.
x-programs: &programs
  image: unlocked-programs:dev
  build:
    # Built straight from GitHub (PROGRAMS_REF, default main), so no checkout
    # is needed. Set PROGRAMS_DIR to your checkout to build your own changes
    # instead.
    context: ${PROGRAMS_DIR:-https://github.com/UnlockedLabs/unlocked-programs.git#${PROGRAMS_REF:-main}}
    args:
      APP_VERSION: dev
      GIT_COMMIT: ${PROGRAMS_GIT_COMMIT:-unknown}
      GIT_BRANCH: ${PROGRAMS_GIT_BRANCH:-unknown}
  networks:
    - intranet
  environment: &programs-env
    APP_DSN: postgres://unlocked:dev@postgres:5432/unlocked
    APP_ENV: dev
    LOG_LEVEL: debug

# Learning Record's two services (EN-208) share one image and environment.
x-learning-record: &learning-record
  image: unlocked-learning-record:dev
  build:
    # Built straight from GitHub (LEARNING_RECORD_REF, default main), so no
    # checkout is needed. Set LEARNING_RECORD_DIR to your checkout to build
    # your own changes instead.
    context: ${LEARNING_RECORD_DIR:-https://github.com/UnlockedLabs/unlocked-learning-record.git#${LEARNING_RECORD_REF:-main}}
    args:
      APP_VERSION: dev
      GIT_COMMIT: ${LEARNING_RECORD_GIT_COMMIT:-unknown}
      GIT_BRANCH: ${LEARNING_RECORD_GIT_BRANCH:-unknown}
  networks:
    - intranet
  environment:
    APP_DSN: postgres://unlocked:dev@postgres:5432/unlocked
    APP_ENV: dev
    # Core, which says who a user is and whether learning_record is on at
    # their facility.
    APP_URL: http://server:8080
    KRATOS_PUBLIC_URL: http://kratos:4433
    LOG_LEVEL: debug

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: unlocked
      POSTGRES_USER: unlocked
      POSTGRES_PASSWORD: dev
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./config/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U unlocked"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - intranet

  frontend:
    build:
      context: frontend
      dockerfile: dev.Dockerfile
    volumes:
      - ./frontend:/app
      - node_modules:/app/node_modules
    networks:
      - intranet
    environment:
      - VITE_PUBLIC_POSTHOG_KEY=${VITE_PUBLIC_POSTHOG_KEY}
      - VITE_PUBLIC_POSTHOG_HOST=${VITE_PUBLIC_POSTHOG_HOST}
      - VITE_DEPLOYMENT=${VITE_DEPLOYMENT}
      - VITE_STATE=${VITE_STATE}

  rev_proxy:
    image: nginx:1.21.3-alpine
    ports:
      - 80:80
    volumes:
      - ./config/dev.nginx.conf:/etc/nginx/conf.d/default.conf
      - logs:/var/log/nginx/
    networks:
      - intranet
    restart: unless-stopped
    depends_on:
      kratos-migrate:
        condition: service_completed_successfully
      # tutor-service is intentionally NOT a dependency here: nginx resolves it
      # lazily per-request (see the `resolver` directive in dev.nginx.conf), so
      # rev_proxy comes up fine even if tutor-service is slow, missing, or its
      # image can't be pulled (e.g. a fork without registry access).

  # One-shot: migrates the database before `server` starts (EN-177), mirroring kratos-migrate.
  server-migrate:
    build:
      context: ./
      dockerfile: backend/dev.Dockerfile
    volumes:
      - ./:/app
    networks:
      - intranet
    environment:
      - &app-dsn APP_DSN=postgres://unlocked:dev@postgres:5432/unlocked
    command: ["go", "run", "./backend/migrations", "-dir", "backend/migrations"]
    depends_on:
      postgres:
        condition: service_healthy

  # backend API
  server:
    build:
      context: ./
      dockerfile: backend/dev.Dockerfile
    ports:
      - 8080:8080
      - 40000:40000
    networks:
      - intranet
    volumes:
      - ./:/app
      - ./frontend/public/thumbnails:/imgs
      - ./csvs/jaspertmp/:/jaspertmp
    environment:
      - *app-dsn
      - APP_ENV=dev
      - LOG_LEVEL=debug
      - APP_URL=http://127.0.0.1
      - APP_KEY=base64:NTQxODNmNDMyM2YzNzdiNzM3NDMzYTFlOTgyMjllYWQwZmRjNjg2ZjkzYmFiMDU3ZWNiNjEyZGFhOTQwMDJiNSAgLQo=
      - OPEN_CONTENT_URL=http://open-content:8080
      - OPEN_CONTENT_TOKEN=dev-open-content-token
      # The Provider Platforms service (EN-206) and the secret they share.
      - PROVIDER_PLATFORMS_URL=http://providerplatforms:8080
      - &provider-platforms-token PROVIDER_PLATFORMS_TOKEN=dev-provider-platforms-token
      # The Programs service and the secret they share.
      - PROGRAMS_URL=http://programs:8080
      - PROGRAMS_TOKEN=dev-programs-token
      - HYDRA_ADMIN_URL=http://hydra:4445
      - HYDRA_PUBLIC_URL=http://hydra:4444
      - KRATOS_ADMIN_URL=http://kratos:4434
      - KRATOS_PUBLIC_URL=http://kratos:4433
      - MIDDLEWARE_CRON_SCHEDULE=0 22 * * *
      # CWD here is /app (the whole repo), not / like the production image --
      # the relative default ("migrations") would miss; InitDB's
      # WaitForMigrations reads migration files to know the target version.
      - MIGRATION_DIR=backend/migrations
      # The scheduler service below runs the background jobs (EN-191).
      - RUN_SCHEDULER=false
      - ORY_TOKEN=eyJvZmZzZXQiOiItMjUwIiwidmo8iV*@
      - NATS_URL=nats:4222
      - NATS_USER=unlocked
      - NATS_PASSWORD=dev
      - IMG_FILEPATH=/imgs
      - CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1,https://kiwix.dev.unlockedlabs.xyz
      - JASPER_TEMP_DIR=/jaspertmp
      - JASPER_TEMPLATE_DIR=/app/backend/src/templates
      - GIT_COMMIT=${GIT_COMMIT:-unknown}
      - GIT_BRANCH=${GIT_BRANCH:-unknown}
      - APP_VERSION=${APP_VERSION:-dev}
    depends_on:
      kratos:
        condition: service_started
      postgres:
        condition: service_healthy
      server-migrate:
        condition: service_completed_successfully

  # Background jobs (EN-191): the server's own code, run as `backend scheduler`.
  # It runs each module's jobs on their schedules, publishing to NATS the ones
  # a module's worker runs. It doesn't migrate: it waits until server-migrate
  # has applied every migration.
  # No hot reload: restart it after changing job code.
  scheduler:
    build:
      context: ./
      dockerfile: backend/dev.Dockerfile
    command: ["go", "run", "./backend/cmd/main.go", "scheduler"]
    networks:
      - intranet
    volumes:
      - ./:/app
    environment:
      - APP_DSN=postgres://unlocked:dev@postgres:5432/unlocked
      - APP_ENV=dev
      - LOG_LEVEL=debug
      - MIDDLEWARE_CRON_SCHEDULE=0 22 * * *
      # Where it reads the migration files it waits for server-migrate to apply.
      - MIGRATION_DIR=backend/migrations
      - NATS_URL=nats:4222
      - NATS_USER=unlocked
      - NATS_PASSWORD=dev
      # It unlinks deleted users from Provider Platforms (EN-206).
      - PROVIDER_PLATFORMS_URL=http://providerplatforms:8080
      - *provider-platforms-token
    restart: unless-stopped
    depends_on: [server]

  # Open Content (EN-205) runs as its own service, built from GitHub, or from
  # your checkout when OPEN_CONTENT_DIR is set (see x-open-content). No hot
  # reload: `make dev` rebuilds it.
  open-content-migrate:
    <<: *open-content
    command: ["migrate"]
    depends_on:
      server-migrate:
        condition: service_completed_successfully

  # Open Content's API. The rev_proxy sends its paths here, and the server
  # asks it questions (.env.example points a server run outside compose at
  # port 8082).
  open-content:
    <<: *open-content
    command: ["serve"]
    ports:
      - 8082:8080
    restart: unless-stopped
    depends_on:
      open-content-migrate:
        condition: service_completed_successfully

  # Open Content's worker: it seeds a new database once the server has created
  # its first facility, then runs the Kiwix scrape and the video jobs.
  open-content-worker:
    <<: *open-content
    command: ["worker"]
    volumes:
      - ./frontend/public/videos:/videos
    restart: unless-stopped
    depends_on:
      open-content-migrate:
        condition: service_completed_successfully

  # Provider Platforms (EN-206) runs as its own service, built from GitHub, or
  # from your checkout when PROVIDER_PLATFORMS_DIR is set (see
  # x-provider-platforms). No hot reload: `make dev` rebuilds it. Its
  # migrations run after core's, because the first one moves the tables core
  # created into the provider schema.
  providerplatforms-migrate:
    <<: *provider-platforms
    command: ["migrate"]
    depends_on:
      server-migrate:
        condition: service_completed_successfully

  # The API core forwards Provider Platforms' routes to, and the job scheduler
  # (.env.example points a server run outside compose at port 8083).
  providerplatforms:
    <<: *provider-platforms
    command: ["serve"]
    ports:
      - 8083:8080
    environment:
      <<: *provider-platforms-env
      PROVIDER_PLATFORMS_TOKEN: dev-provider-platforms-token
      APP_URL: http://127.0.0.1
      CORE_URL: http://server:8080
      HYDRA_ADMIN_URL: http://hydra:4445
      HYDRA_PUBLIC_URL: http://hydra:4444
      ORY_TOKEN: eyJvZmZzZXQiOiItMjUwIiwidmo8iV*@
      MIDDLEWARE_CRON_SCHEDULE: 0 22 * * *
      PROVIDER_SERVICE_URL: http://providerplatforms-worker:8081
    restart: unless-stopped
    depends_on:
      providerplatforms-migrate:
        condition: service_completed_successfully

  # The LMS jobs: the Canvas, Brightspace and Kolibri syncs. It also serves the
  # provider user lists the API asks for.
  providerplatforms-worker:
    <<: *provider-platforms
    command: ["worker"]
    ports:
      - 8081:8081
    volumes:
      - csvs:/csvs
    environment:
      <<: *provider-platforms-env
      APP_URL: http://server:8080
      # Kolibri's own database, which the Kolibri sync reads.
      DB_HOST: postgres
      DB_PORT: "5432"
      KOLIBRI_DB_PASSWORD: dev
      BRIGHTSPACE_TEMP_DIR: /csvs
    restart: unless-stopped
    depends_on:
      providerplatforms-migrate:
        condition: service_completed_successfully

  # Programs runs as its own service, built from GitHub, or from your checkout
  # when PROGRAMS_DIR is set (see x-programs). No hot reload: `make dev`
  # rebuilds it. Its migrations run after core's, because the first one moves
  # the tables core created into the programs schema.
  programs-migrate:
    <<: *programs
    command: ["migrate"]
    depends_on:
      server-migrate:
        condition: service_completed_successfully

  # Learning Record (EN-208) runs as its own service, built from GitHub, or
  # from your checkout when LEARNING_RECORD_DIR is set (see x-learning-record).
  # No hot reload: `make dev` rebuilds it. Its migration runs after core's,
  # because it moves the table core created into the learning_record schema.
  learning-record-migrate:
    <<: *learning-record
    command: ["migrate"]
    depends_on:
      server-migrate:
        condition: service_completed_successfully

  # Programs' API. The rev_proxy sends its paths here, and the server asks it
  # questions (.env.example points a server run outside compose at port 8084).
  programs:
    <<: *programs
    command: ["serve"]
    ports:
      - 8084:8080
    environment:
      <<: *programs-env
      APP_URL: http://server:8080
      KRATOS_PUBLIC_URL: http://kratos:4433
      NATS_URL: nats:4222
      NATS_USER: unlocked
      NATS_PASSWORD: dev
      PROGRAMS_TOKEN: dev-programs-token
      PROVIDER_PLATFORMS_URL: http://providerplatforms:8080
      PROVIDER_PLATFORMS_TOKEN: dev-provider-platforms-token
    restart: unless-stopped
    depends_on:
      programs-migrate:
        condition: service_completed_successfully

  # Programs' worker: class activation, every morning at 5.
  programs-worker:
    <<: *programs
    command: ["worker"]
    restart: unless-stopped
    depends_on:
      programs-migrate:
        condition: service_completed_successfully

  # Learning Record's API. The rev_proxy sends /api/learning-record here.
  learning-record:
    <<: *learning-record
    command: ["serve"]
    ports:
      - 8085:8080
    restart: unless-stopped
    depends_on:
      learning-record-migrate:
        condition: service_completed_successfully

  # AI tutor sidecar (served under basePath /tutor; see tutor-integration.md)
  tutor-service:
    # Default: build from the sibling tutor checkout (../ai/unlocked-hiset-ai) — for
    # engineers working ON the tutor. CI also publishes this exact image to GHCR, so
    # `make dev-registry` pulls it instead and no tutor checkout is needed. Override the
    # tag with TUTOR_IMAGE_TAG (branch name, or a vX.Y.Z release tag).
    image: ghcr.io/unlockedlabs/unlocked-smart-tutor:${TUTOR_IMAGE_TAG:-main}
    build:
      context: ${TUTOR_DIR:-../ai/unlocked-hiset-ai}
      # Bakes the sibling checkout's actual git state into the image so
      # `curl 127.0.0.1/tutor/api/version` answers "which build is this"
      # instead of relying on memory of which branch was checked out when
      # `make dev` built it. Set by the Makefile; "unknown" outside `make`.
      args:
        GIT_COMMIT: ${TUTOR_GIT_COMMIT:-unknown}
        GIT_BRANCH: ${TUTOR_GIT_BRANCH:-unknown}
    networks:
      - intranet
    environment:
      - AUTH_MODE=unlocked
      - DATABASE_URL=postgres://unlocked:dev@postgres:5432/unlocked
      - KRATOS_PUBLIC_URL=http://kratos:4433
      # Auto-provision the tutor.* schema on start so devs skip a manual db:push.
      - RUN_MIGRATIONS=true
      - TUTOR_FEATURE_FLAG=ai_tutor
      # Bedrock is the production provider. Passed through rather than pinned on:
      # USE_BEDROCK=true with no AWS credentials fails on the first model call,
      # which would break the tutor for every engineer who does not have them.
      # Set USE_BEDROCK and the AWS_* vars in .env to run this stack on Bedrock;
      # leave them unset and it falls back to AI_PROVIDER below.
      #
      # Model ids live in the tutor's lib/ai/client.ts (DEFAULT_MODELS.bedrock)
      # and are cross-region inference profiles — the bare in-region form is not
      # a valid id. Override per role with AI_MODEL_TUTOR / _FAST / _REASONING.
      - USE_BEDROCK=${USE_BEDROCK:-}
      - AWS_REGION=${AWS_REGION:-}
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
      - AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN:-}
      - AI_MODEL_TUTOR=${AI_MODEL_TUTOR:-}
      - AI_MODEL_FAST=${AI_MODEL_FAST:-}
      - AI_MODEL_REASONING=${AI_MODEL_REASONING:-}
      # Fallback provider, used only when USE_BEDROCK is unset.
      - AI_PROVIDER=${TUTOR_AI_PROVIDER:-anthropic}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
      - GEMINI_API_KEY=${GEMINI_API_KEY:-}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      # Layer-2 guardrail classifier. 'model' keeps learner text inside the
      # deployment's own provider boundary, which is what a DOC install needs.
      - GUARDRAIL_LLM=${GUARDRAIL_LLM:-model}
    depends_on:
      postgres:
        condition: service_healthy
      kratos:
        condition: service_started

  nats:
    image: nats:latest
    networks:
      - intranet
    ports:
      - 8222:8222
      - 4222:4222
    command: --js -c /config/nats-server.conf
    restart: on-failure
    volumes:
      - config:/config
      - nats_data:/data

  kratos-migrate:
    image: oryd/kratos:v1.1.0
    environment:
      - DSN=postgres://kratos:ChangeMe!@postgres:5432/kratos?sslmode=disable&max_conns=20&max_idle_conns=4
    volumes:
      - type: bind
        source: ./config/kratos
        target: /etc/config/kratos
    command: -c /etc/config/kratos/kratos.yml migrate sql -e --yes
    networks:
      - intranet
    depends_on:
      postgres:
        condition: service_healthy

  kratos:
    depends_on:
      - kratos-migrate
    image: oryd/kratos:v1.1.0
    ports:
      - "4433:4433" # public
      - "4434:4434" # admin
    environment:
      - DSN=postgres://kratos:ChangeMe!@postgres:5432/kratos?sslmode=prefer&max_conns=20&max_idle_conns=4
      - LOG_LEVEL=info
    command: serve -c /etc/config/kratos/kratos.yml --dev --watch-courier
    volumes:
      - type: bind
        source: ./config/kratos
        target: /etc/config/kratos
    networks:
      - intranet

  hydra:
    image: oryd/hydra:v2.2.0
    ports:
      - "4444:4444"
      - "4445:4445"
      - "5555:5555"
    command: serve -c /etc/config/hydra/hydra.yml all --dev
    volumes:
      - type: bind
        source: ./config/hydra
        target: /etc/config/hydra
    environment:
      - LOG_LEVEL=info
      - OAUTH2_EXPOSE_INTERNAL_ERRORS=1
      - SERVE_PUBLIC_CORS_ENABLED=true
      - SERVE_PUBLIC_CORS_ALLOWED_METHODS=POST,GET,PUT,DELETE
      - SERVE_ADMIN_CORS_ENABLED=true
      - SERVE_ADMIN_CORS_ALLOWED_METHODS=POST,GET,PUT,DELETE
      - DSN=postgres://hydra:ChangeMe!@postgres:5432/hydra?sslmode=prefer&max_conns=20&max_idle_conns=4
    restart: unless-stopped
    depends_on:
      - hydra-migrate
    networks:
      - intranet

  hydra-migrate:
    image: oryd/hydra:v2.2.0
    environment:
      - DSN=postgres://hydra:ChangeMe!@postgres:5432/hydra?sslmode=prefer&max_conns=20&max_idle_conns=4
      - LOG_LEVEL=info
    command: migrate -c /etc/config/hydra/hydra.yml sql -e --yes
    volumes:
      - type: bind
        source: ./config/hydra
        target: /etc/config/hydra
    networks:
      - intranet
    depends_on:
      postgres:
        condition: service_healthy

networks:
  intranet:
    driver: bridge

volumes:
  nats_data:
  postgres_data:
  config:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./config
  csvs:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./csvs
  logs:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./logs
  node_modules: