compose.yaml

# MINT on a laptop. `docker compose up` starts the whole platform.
#
# It holds the whole stack: Postgres, the Tapis auth webhook, Hasura, the
# one-shot migration service, the one-shot catalog fixture load,
# model-catalog-api, Redis, Ensemble Manager and ui-react.
#
# `compose/README.md` is the guide. Read it first.
#
# Ports on the host: ui-react 3000, Ensemble Manager 3001, model-catalog-api
# 3002, Hasura 8082, svo-adapter 8090, semantic-search 8091, Redis 6380.
# Postgres and the auth webhook publish no port. The other services reach them
# on the compose network.
#
# `ui-react` is behind the `ui` profile, because the default way to run it is on
# the host with Vite. `docker compose --profile ui up` starts the container way
# instead. Both serve port 3000.
#
# Every credential here is a development default. Override it in a `.env` file
# beside this one, or in the shell.

name: mint

x-postgres-env: &postgres-env
  POSTGRES_USER: ${POSTGRES_USER:-mint}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-mint}
  POSTGRES_DB: ${POSTGRES_DB:-mint}

services:
  # ---------------------------------------------------------------------------
  # Postgres. PostGIS is required: the init migration declares columns of type
  # `public.geometry` and functions that call `ST_Contains`. No migration
  # creates the extension, so the image must. `postgis/postgis` runs
  # `CREATE EXTENSION postgis` in POSTGRES_DB on first start.
  #
  # The image publishes amd64 only, so `platform` is not optional on Apple
  # Silicon. Without it the pull fails with "no matching manifest".
  # ---------------------------------------------------------------------------
  postgres:
    build:
      context: ./docker/postgres-pgvector
    image: mint/postgres-pgvector:dev
    platform: linux/amd64
    environment: *postgres-env
    # Postgres is consumed by the Compose services over the internal network;
    # no host mapping is required.
    ports: []
    volumes:
      # The volume name carries the major version. Postgres refuses a data
      # directory from another major version, and the container then exits 1
      # with "database files are incompatible with server". A new major version
      # must take a new volume name, so the old data stays on disk and the
      # stack still starts.
      - postgres-data-16:/var/lib/postgresql/data
    healthcheck:
      # -h 127.0.0.1 forces a TCP check. Without it `pg_isready` uses the unix
      # socket and reports ready during initdb, while the entrypoint's temporary
      # server is still refusing TCP. Hasura then starts too early and exits.
      test:
        - CMD-SHELL
        - pg_isready -h 127.0.0.1 -U ${POSTGRES_USER:-mint} -d ${POSTGRES_DB:-mint}
      interval: 5s
      timeout: 5s
      retries: 30
      start_period: 20s

  # ---------------------------------------------------------------------------
  # The Tapis auth webhook. Hasura calls it once per request.
  #
  # It answers 200 with role `anonymous` when the request carries no token, and
  # 401 when the token is invalid. This is how anonymous browsing works.
  # `HASURA_GRAPHQL_UNAUTHORIZED_ROLE` does nothing in webhook mode, so it is
  # absent below on purpose. See issue #187.
  #
  # Both Tapis variables must be set. The image bakes the `tacc` tenant into its
  # own defaults, not `portals`.
  #
  # The image carries its own HEALTHCHECK on GET /health, so none is repeated
  # here. It publishes amd64 only.
  # ---------------------------------------------------------------------------
  auth-webhook:
    image: ghcr.io/in-for-disaster-analytics/hasura-tapis-auth-webhook:1.0.0
    platform: linux/amd64
    environment:
      TAPIS_JWKS_URI: ${TAPIS_JWKS_URI:-https://portals.tapis.io/v3/tenants/portals}
      TAPIS_TOKEN_ISSUER: ${TAPIS_TOKEN_ISSUER:-https://portals.tapis.io/v3/tokens}
      PORT: "3000"
    expose:
      - "3000"

  # ---------------------------------------------------------------------------
  # Hasura. Built from `graphql_engine/`, never pulled from ghcr.io.
  #
  # AUTH_HOOK_MODE must be POST. The webhook has no GET route, and Hasura
  # defaults to GET.
  #
  # CORS lists every browser origin in this stack. `ui-react` on 3000 is the one
  # that matters today.
  # ---------------------------------------------------------------------------
  hasura:
    build:
      context: ./graphql_engine
    image: mint/graphql-engine:dev
    depends_on:
      postgres:
        condition: service_healthy
      auth-webhook:
        condition: service_healthy
    environment:
      HASURA_GRAPHQL_DATABASE_URL: postgres://${POSTGRES_USER:-mint}:${POSTGRES_PASSWORD:-mint}@postgres:5432/${POSTGRES_DB:-mint}
      HASURA_GRAPHQL_ADMIN_SECRET: ${HASURA_GRAPHQL_ADMIN_SECRET:-mint}
      HASURA_GRAPHQL_AUTH_HOOK: http://auth-webhook:3000/auth-webhook
      HASURA_GRAPHQL_AUTH_HOOK_MODE: POST
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      HASURA_GRAPHQL_DEV_MODE: "true"
      SVO_SEMANTIC_SEARCH_WEBHOOK_URL: http://semantic-search:8091/events/catalog
      HASURA_GRAPHQL_CORS_DOMAIN: "http://localhost:3000, http://localhost:3001, http://localhost:3002"
      HASURA_GRAPHQL_ENABLED_LOG_TYPES: "startup, http-log, webhook-log, websocket-log"
    # Expose Hasura for the local React UI; services still use the internal URL.
    ports:
      - "8082:8080"
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8080/healthz || exit 1"]
      interval: 5s
      timeout: 5s
      retries: 30
      start_period: 20s

  # ---------------------------------------------------------------------------
  # The schema. A one-shot service that exits.
  #
  # It runs on every `up`, unlike the MINT chart, which runs this work in a
  # `post-install` hook and therefore skips it on every upgrade.
  #
  # It waits for Hasura, not for Postgres. The Hasura CLI speaks to the Hasura
  # server, not to the database.
  #
  # `hasura seeds apply` is not idempotent. No file in `graphql_engine/seeds/`
  # uses ON CONFLICT, and `public.region` has a primary key, so a second run
  # fails on a duplicate key. The guard below counts the rows first. Migrations
  # and metadata are idempotent and run every time.
  #
  # The count comes from Hasura's own `run_sql` endpoint. The image has curl but
  # no `psql`: its Dockerfile installs postgresql-client-common, which ships no
  # client binary.
  #
  # `graphql_engine/` is bind-mounted, so an edit to a migration needs no
  # rebuild.
  # ---------------------------------------------------------------------------
  hasura-init:
    build:
      context: ./graphql_engine
    image: mint/graphql-engine:dev
    depends_on:
      hasura:
        condition: service_healthy
    environment:
      HASURA_GRAPHQL_ENDPOINT: http://hasura:8080
      HASURA_GRAPHQL_ADMIN_SECRET: ${HASURA_GRAPHQL_ADMIN_SECRET:-mint}
    working_dir: /hasura
    volumes:
      - ./graphql_engine:/hasura
    restart: "no"
    entrypoint: ["/bin/sh", "-c"]
    command:
      - |
        set -e
        hasura migrate apply --skip-update-check
        hasura metadata apply --skip-update-check
        rows=$$(curl -fsS \
          -H "x-hasura-admin-secret: $$HASURA_GRAPHQL_ADMIN_SECRET" \
          -H "Content-Type: application/json" \
          -d '{"type":"run_sql","args":{"source":"default","sql":"SELECT count(*) FROM public.region"}}' \
          "$$HASURA_GRAPHQL_ENDPOINT/v2/query")
        case "$$rows" in
          *'["0"]'*)
            echo "region is empty, applying seeds"
            hasura seeds apply --skip-update-check
            ;;
          *)
            echo "region already holds rows, skipping seeds"
            ;;
        esac
        echo "schema ready"

  # ---------------------------------------------------------------------------
  # The catalog data. A one-shot service that exits.
  #
  # `hasura-init` makes the tables. This fills the `modelcatalog_*` ones from
  # `graphql_engine/fixtures/modelcatalog.sql`, a subset of the production
  # catalog with the whole controlled vocabulary. See issues #189 and #190.
  #
  # It runs on every `up`. There is no profile and no opt-out flag. The fixture
  # itself is idempotent: every INSERT carries ON CONFLICT DO NOTHING, and it
  # sets `session_replication_role = replica`, so the table order does not
  # matter. A second run adds no row.
  #
  # The image is the Postgres image, not the Hasura one. The Hasura image has no
  # `psql`: its Dockerfile installs postgresql-client-common, which ships no
  # client binary.
  #
  # ON_ERROR_STOP=1 makes a broken fixture fail the service instead of logging
  # and exiting 0.
  # ---------------------------------------------------------------------------
  fixture-load:
    image: postgis/postgis:14-3.3
    platform: linux/amd64
    depends_on:
      # Postgres is reached directly, so wait for it as well as for the schema.
      postgres:
        condition: service_healthy
      hasura-init:
        condition: service_completed_successfully
    environment:
      PGHOST: postgres
      PGPORT: "5432"
      PGUSER: ${POSTGRES_USER:-mint}
      PGPASSWORD: ${POSTGRES_PASSWORD:-mint}
      PGDATABASE: ${POSTGRES_DB:-mint}
    volumes:
      - ./graphql_engine/fixtures:/fixtures:ro
    restart: "no"
    entrypoint: ["/bin/sh", "-c"]
    command:
      - |
        set -e
        psql -v ON_ERROR_STOP=1 -q -f /fixtures/modelcatalog.sql
        echo "catalog fixture loaded"

  # ---------------------------------------------------------------------------
  # model-catalog-api. The REST face of the catalog, v2.0.0.
  #
  # `target: builder` is deliberate. The final stage of the Dockerfile runs
  # `npm ci --production`, which drops `tsx`, so `npm run dev` cannot start
  # there. The builder stage keeps every dependency, so watch mode works.
  #
  # PORT must be set. The Dockerfile bakes `ENV PORT=3000` and the code falls
  # back to 3000 as well. Decision 9 of the map gives this service 3002.
  #
  # It reads Hasura with the admin secret. It forwards a user bearer token on a
  # write. See `model-catalog-api/src/hasura/client.ts`.
  # ---------------------------------------------------------------------------
  model-catalog-api:
    build:
      context: ./model-catalog-api
      target: builder
    image: mint/model-catalog-api:dev
    depends_on:
      hasura:
        condition: service_healthy
      hasura-init:
        condition: service_completed_successfully
    environment:
      HASURA_GRAPHQL_URL: http://hasura:8080/v1/graphql
      HASURA_ADMIN_SECRET: ${HASURA_GRAPHQL_ADMIN_SECRET:-mint}
      PORT: "3002"
      LOG_LEVEL: ${LOG_LEVEL:-info}
    command: ["npm", "run", "dev"]
    ports:
      - "3002:3002"
    volumes:
      - ./model-catalog-api/src:/app/src
      - ./model-catalog-api/openapi.yaml:/app/openapi.yaml
    healthcheck:
      # /health queries Hasura and answers 503 when it cannot reach it, so this
      # check covers the link as well as the process.
      #
      # 127.0.0.1, not localhost. Fastify binds IPv4 only, `localhost` resolves
      # to ::1 first, and busybox wget does not fall back to the A record.
      test: ["CMD-SHELL", "wget -q -O- http://127.0.0.1:3002/health || exit 1"]
      interval: 5s
      timeout: 5s
      retries: 30
      start_period: 30s

  # ---------------------------------------------------------------------------
  # Redis. Ensemble Manager builds its Bull queues at import time, so Redis must
  # answer before Ensemble Manager starts.
  # ---------------------------------------------------------------------------
  redis:
    image: redis:7-alpine
    platform: linux/arm64
    ports:
      # Keep the container port at 6379; 6380 avoids colliding with a local
      # Redis/Homebrew service that may already be running on the host.
      - "6380:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 30

  # ---------------------------------------------------------------------------
  # Ensemble Manager. Threads, executions and the Tapis adapter.
  #
  # It listens on 3000 inside the container and cannot be told otherwise:
  # `src/config/app.ts` exports `PORT = 3000` as a constant, and nothing reads an
  # environment variable. So the port is remapped here, 3001 on the host.
  #
  # All other settings come from one JSON file, bind-mounted read-only. The
  # admin secret is not in that file. `getConfiguration()` copies
  # HASURA_GRAPHQL_ADMIN_SECRET into `graphql.secret` when the file omits it, so
  # the secret stays in the environment and takes an override from `.env`.
  #
  # Only `src` is bind-mounted. Mounting the whole directory would hide
  # `node_modules` and `dist`, which the image builds.
  # ---------------------------------------------------------------------------
  ensemble-manager:
    build:
      context: ./mint-ensemble-manager
    image: mint/ensemble-manager:dev
    depends_on:
      redis:
        condition: service_healthy
      hasura:
        condition: service_healthy
      hasura-init:
        condition: service_completed_successfully
    environment:
      ENSEMBLE_MANAGER_CONFIG_FILE: /home/node/app/compose-config.json
      HASURA_GRAPHQL_ADMIN_SECRET: ${HASURA_GRAPHQL_ADMIN_SECRET:-mint}
      REDIS_URL: redis://redis:6379
      NODE_OPTIONS: --openssl-legacy-provider
    command: ["npm", "run", "start:watch"]
    ports:
      - "3001:3000"
    volumes:
      - ./mint-ensemble-manager/src:/home/node/app/src
      - ./compose/ensemble-manager.json:/home/node/app/compose-config.json:ro
    healthcheck:
      # The Swagger UI is the only unauthenticated route. Every /v1 resource
      # route answers 401 without a bearer token.
      test: ["CMD-SHELL", "wget -q -O- http://127.0.0.1:3000/v1/ui/ || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 60
      start_period: 120s

  # ---------------------------------------------------------------------------
  # ui-react, the container way. It is behind the `ui` profile, so a plain
  # `docker compose up` does not start it:
  #
  #   docker compose --profile ui up
  #
  # The host way is the default and needs no profile. Copy `compose/ui-react.env`
  # to `ui-react/.env`, run `npm run config:local`, then `npm run dev`. Both ways
  # serve port 3000, so only one runs at a time. The port is not free to change:
  # Tapis allows one callback for each client, and `mint-localhost-3000` is
  # registered for http://localhost:3000/oauth2/callback.
  #
  # Every URL below is a HOST url. The browser resolves them, so a compose
  # service name would not resolve. This is why the service publishes no
  # dependency on hasura or ensemble-manager: it never speaks to them itself.
  #
  # nginx serves the bundle. The entrypoint writes `env-config.js` into the web
  # root at startup from these variables, using the same generator that
  # `npm run config:local` runs. So the two ways read one configuration shape.
  # ---------------------------------------------------------------------------
  ui-react:
    build:
      context: ./ui-react
    image: mint/ui-react:dev
    profiles:
      - ui
    environment:
      HASURA_ENDPOINT: ${HASURA_ENDPOINT:-http://localhost:8082/v1/graphql}
      AUTH_SERVER: ${AUTH_SERVER:-https://portals.tapis.io}
      AUTH_CLIENT_ID: ${AUTH_CLIENT_ID:-mint-ui-dev-wm}
      AUTH_CALLBACK_ORIGIN: ${AUTH_CALLBACK_ORIGIN:-http://localhost:3000}
      AUTH_PROVIDER: ${AUTH_PROVIDER:-tapis}
      ENSEMBLE_MANAGER_API: ${ENSEMBLE_MANAGER_API:-http://localhost:3001/v1}
      EXECUTION_ENGINE: ${EXECUTION_ENGINE:-tapis}
      DATA_CATALOG_API: ${DATA_CATALOG_API:-https://ckan.tacc.utexas.edu}
      DATA_CATALOG_BROWSE_URL: ${DATA_CATALOG_BROWSE_URL:-https://ckan.tacc.utexas.edu}
      # The generator defaults this to 'none', which is right for a deployment
      # and wrong here: the committed public/env-config.js sets 'tacc', so
      # without this line the container and host mode show different chrome.
      BRANDING: ${BRANDING:-tacc}
    ports:
      - "3000:80"
    healthcheck:
      # nginx.conf answers /healthz with a literal 200. The alpine image has
      # busybox wget, and no curl.
      test: ["CMD-SHELL", "wget -q -O- http://127.0.0.1/healthz || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 30
      start_period: 10s

  # ---------------------------------------------------------------------------
  # SVO Adapter. It shares Hasura with the catalog and exposes semantic planning
  # plus the bundled adapter UI on the host for local development.
  # ---------------------------------------------------------------------------
  svo-adapter:
    build:
      context: ./svo-adapter-service
    image: mint/svo-adapter:dev
    depends_on:
      hasura:
        condition: service_healthy
      hasura-init:
        condition: service_completed_successfully
    environment:
      SVO_ADAPTER_HASURA_GRAPHQL_URL: http://hasura:8080/v1/graphql
      SVO_ADAPTER_HASURA_ADMIN_SECRET: ${HASURA_GRAPHQL_ADMIN_SECRET:-mint}
    # The image runs `uvicorn --port 8090`, so the container port is 8090, not
    # 8000. A mapping to 8000 publishes a closed port and the healthcheck never
    # passes.
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8090/health')"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 20s

  semantic-search:
    build:
      context: ./semantic-search-service
    image: mint/semantic-search:dev
    depends_on:
      postgres:
        condition: service_healthy
      # The schema, then the catalog rows. The service queries
      # `modelcatalog_standard_variable` as it starts, so both one-shot
      # services must finish first.
      hasura-init:
        condition: service_completed_successfully
      fixture-load:
        condition: service_completed_successfully
    environment:
      DATABASE_URL: postgresql://mint:mint@postgres:5432/mint
      SVO_EMBEDDING_REFRESH_SECONDS: ${SVO_EMBEDDING_REFRESH_SECONDS:-60}
      SVO_CORS_ORIGINS: ${SVO_CORS_ORIGINS:-http://localhost:3000}
    ports:
      - "8091:8091"
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8091/health')"]
      interval: 15s
      timeout: 5s
      retries: 20
      start_period: 30s

volumes:
  postgres-data-16: