fadenstack 0.4.2__py3-none-any.whl

faden_cli/bundle/shared/docker-compose.yaml

@@ -0,0 +1,998 @@
+# Secrets: this file has no fallback for any password, key or token. Each one
+# is ${NAME:?...}, and compose stops naming the first that .env lacks.
+# `faden deploy` writes them all at random; `faden upgrade` adds what a
+# release introduces. Started by hand, set them yourself (Help: Installing,
+# Secrets in .env). The services refuse the development values that are
+# published with the source code.
+#
+# The project name decides the volume names (fadenstack_pg_data, ...).
+# Fixed, so an install keeps its data whichever directory it runs from: a
+# source checkout's shared, or the directory `faden deploy`
+# unpacks the release into (~/fadenstack by default).
+name: fadenstack
+
+services:
+  # -----------------------------
+  # Platform base image (build-only, no runtime container)
+  # -----------------------------
+  faden-base:
+    image: ${REGISTRY:-ghcr.io/fadenstack}/base:${VERSION:-latest}
+    build:
+      context: ./base
+      dockerfile: Dockerfile
+    profiles: ["_build"]
+
+  # -----------------------------
+  # Reverse proxy — single public entrypoint
+  # -----------------------------
+  nginx:
+    image: nginx:1-alpine
+    container_name: faden-nginx
+    restart: unless-stopped
+    ports:
+      - "${FADEN_HTTP_PORT:-80}:80"
+      # Served once ./tls holds a certificate and key (nginx/select-config.sh);
+      # until then nothing listens here.
+      - "${FADEN_HTTPS_PORT:-443}:443"
+    environment:
+      FADEN_HTTPS_PORT: ${FADEN_HTTPS_PORT:-443}
+      # Strict-Transport-Security max-age sent over HTTPS. Opt-in: 0 (off) by
+      # default, which also tells browsers to forget it. With a self-signed
+      # certificate or a private CA, HSTS leaves a browser that does not trust
+      # it yet no way past the warning (nginx-tls.conf, Help: HTTPS).
+      FADEN_HSTS_MAX_AGE: ${FADEN_HSTS_MAX_AGE:-0}
+    # select-config.sh installs the plain-HTTP or the HTTPS server config,
+    # then nginx runs as usual (the image's own entrypoint still runs first).
+    command: ["/bin/sh", "-c", "sh /etc/nginx/faden/select-config.sh && exec nginx -g 'daemon off;'"]
+    volumes:
+      - ./nginx:/etc/nginx/faden:ro
+      # The edge certificate and key: written by the backend's TLS admin API
+      # (/api/admin/tls), or copied in by the operator. See tls/README.md.
+      - ./tls:/etc/faden/tls:ro
+    depends_on:
+      faden-backend:
+        condition: service_healthy
+      faden-frontend:
+        condition: service_started
+    healthcheck:
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://127.0.0.1:80/healthz || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 10s
+
+  # -----------------------------
+  # Database for RAG + Langfuse state
+  # -----------------------------
+  postgres:
+    image: pgvector/pgvector:pg17
+    container_name: faden-postgres
+    restart: unless-stopped
+    # Parallel index builds (pgvector HNSW) work in shared memory; Docker's
+    # default 64 MB /dev/shm fails them ("could not resize shared memory
+    # segment"). pgvector's README asks for more.
+    shm_size: 1g
+    # Every worker of every service keeps its own pool, and they all share this
+    # server: with PII, MCP and skills an install from this file alone can open
+    # about 130 connections at its peak, past Postgres' default of 100 (see
+    # docs/help/pages/operate/requirements.md, The server). A connection is a
+    # process of about 6 MB, so 250 at once is about 1.5 GB.
+    command: ["postgres", "-c", "max_connections=${POSTGRES_MAX_CONNECTIONS:-250}"]
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-postgres}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      POSTGRES_DB: ${POSTGRES_DB:-postgres}
+      TZ: UTC
+      PGTZ: UTC
+    ports:
+      - "127.0.0.1:5432:5432"
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+      - ./initdb:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
+      interval: 3s
+      timeout: 3s
+      retries: 15
+      start_period: 120s
+
+  # -----------------------------
+  # Langfuse (v3) dependencies
+  # -----------------------------
+  clickhouse:
+    # Pinned: tags >= ~25.11 require AVX2. On QEMU/emulated CPUs that
+    # expose only SSE4.2 the binary crashes with "Illegal instruction"
+    # (SIGILL) and the container crash-loops. Override via .env:
+    # CLICKHOUSE_IMAGE=clickhouse/clickhouse-server:<tag>
+    image: ${CLICKHOUSE_IMAGE:-clickhouse/clickhouse-server:25.10}
+    container_name: faden-clickhouse
+    restart: unless-stopped
+    user: "101:101"
+    environment:
+      CLICKHOUSE_DB: default
+      CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+    ports:
+      - "127.0.0.1:8123:8123"
+      - "127.0.0.1:9000:9000"
+    volumes:
+      - ch_data:/var/lib/clickhouse
+      - ch_logs:/var/log/clickhouse-server
+      # Its own diagnostic logs off or capped: trace_log alone filled a
+      # 98 GB disk in two weeks. See the file.
+      - ./clickhouse/config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro
+    healthcheck:
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 2s
+
+  redis:
+    image: redis:7.2
+    container_name: faden-redis
+    restart: unless-stopped
+    command: >
+      --requirepass ${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)} --maxmemory-policy noeviction
+    ports:
+      - "127.0.0.1:6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "-a", "${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}", "ping"]
+      interval: 3s
+      timeout: 10s
+      retries: 10
+
+  minio:
+    image: cgr.dev/chainguard/minio:latest
+    container_name: faden-minio
+    restart: unless-stopped
+    entrypoint: sh
+    command: -c 'mkdir -p /data/langfuse && minio server --address ":9000" --console-address ":9001" /data'
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-minio}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+    ports:
+      - "127.0.0.1:9090:9000"
+      - "127.0.0.1:9091:9001"
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 2s
+      timeout: 5s
+      retries: 10
+      start_period: 2s
+
+  # -----------------------------
+  # Langfuse v3 (web + worker)
+  # -----------------------------
+  langfuse-worker:
+    image: docker.io/langfuse/langfuse-worker:3
+    container_name: faden-worker
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      clickhouse:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:3030:3030"
+    environment:
+      NEXTAUTH_URL: ${LANGFUSE_NEXTAUTH_URL:-http://localhost:3000}
+      DATABASE_URL: ${LANGFUSE_DATABASE_URL:-postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}@postgres:5432/langfuse}
+      SALT: ${LANGFUSE_SALT:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      ENCRYPTION_KEY: ${LANGFUSE_ENCRYPTION_KEY:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      # Off: Langfuse reports usage to its makers unless told not to.
+      TELEMETRY_ENABLED: ${LANGFUSE_TELEMETRY_ENABLED:-false}
+
+      CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
+      CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
+      CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      CLICKHOUSE_CLUSTER_ENABLED: "false"
+
+      REDIS_HOST: redis
+      REDIS_PORT: 6379
+      REDIS_AUTH: ${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+
+      # S3-compatible storage (MinIO)
+      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
+      LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
+      LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: ${MINIO_ROOT_USER:-minio}
+      LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: ${LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT:-http://minio:9000}
+      LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
+      LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
+
+      LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: ${LANGFUSE_S3_MEDIA_UPLOAD_BUCKET:-langfuse}
+      LANGFUSE_S3_MEDIA_UPLOAD_REGION: ${LANGFUSE_S3_MEDIA_UPLOAD_REGION:-auto}
+      LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: ${MINIO_ROOT_USER:-minio}
+      LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: ${LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT:-http://minio:9000}
+      LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: "true"
+      LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
+
+  langfuse-web:
+    image: docker.io/langfuse/langfuse:3
+    container_name: faden-web
+    restart: unless-stopped
+    ports:
+      # LLM observability UI (traces / evals / datasets), plain HTTP: on this
+      # machine only by default, so a password typed into it never crosses the
+      # network in the clear (reach it through an SSH tunnel). Its sign-in
+      # also expects http://localhost (LANGFUSE_NEXTAUTH_URL).
+      # LANGFUSE_BIND=0.0.0.0 publishes it on the network.
+      - "${LANGFUSE_BIND:-127.0.0.1}:3002:3000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      clickhouse:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    environment:
+      NEXTAUTH_URL: ${LANGFUSE_NEXTAUTH_URL:-http://localhost:3000}
+      NEXTAUTH_SECRET: ${LANGFUSE_NEXTAUTH_SECRET:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      DATABASE_URL: ${LANGFUSE_DATABASE_URL:-postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}@postgres:5432/langfuse}
+      SALT: ${LANGFUSE_SALT:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      ENCRYPTION_KEY: ${LANGFUSE_ENCRYPTION_KEY:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      # Off: Langfuse reports usage to its makers unless told not to.
+      TELEMETRY_ENABLED: ${LANGFUSE_TELEMETRY_ENABLED:-false}
+
+      CLICKHOUSE_MIGRATION_URL: ${CLICKHOUSE_MIGRATION_URL:-clickhouse://clickhouse:9000}
+      CLICKHOUSE_URL: ${CLICKHOUSE_URL:-http://clickhouse:8123}
+      CLICKHOUSE_USER: ${CLICKHOUSE_USER:-clickhouse}
+      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      CLICKHOUSE_CLUSTER_ENABLED: "false"
+
+      REDIS_HOST: redis
+      REDIS_PORT: 6379
+      REDIS_AUTH: ${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+
+      LANGFUSE_S3_EVENT_UPLOAD_BUCKET: ${LANGFUSE_S3_EVENT_UPLOAD_BUCKET:-langfuse}
+      LANGFUSE_S3_EVENT_UPLOAD_REGION: ${LANGFUSE_S3_EVENT_UPLOAD_REGION:-auto}
+      LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: ${MINIO_ROOT_USER:-minio}
+      LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: ${LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT:-http://minio:9000}
+      LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
+      LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
+
+      LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: ${LANGFUSE_S3_MEDIA_UPLOAD_BUCKET:-langfuse}
+      LANGFUSE_S3_MEDIA_UPLOAD_REGION: ${LANGFUSE_S3_MEDIA_UPLOAD_REGION:-auto}
+      LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: ${MINIO_ROOT_USER:-minio}
+      LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: ${LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT:-http://minio:9000}
+      LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: "true"
+      LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
+
+      # Initial admin user seeding (set by faden deploy)
+      LANGFUSE_INIT_USER_EMAIL: ${LANGFUSE_INIT_USER_EMAIL:-}
+      LANGFUSE_INIT_USER_PASSWORD: ${LANGFUSE_INIT_USER_PASSWORD:-}
+      LANGFUSE_INIT_USER_NAME: ${LANGFUSE_INIT_USER_NAME:-Admin}
+      LANGFUSE_INIT_ORG_ID: ${LANGFUSE_INIT_ORG_ID:-faden-org}
+      LANGFUSE_INIT_ORG_NAME: ${LANGFUSE_INIT_ORG_NAME:-fadenstack}
+      LANGFUSE_INIT_PROJECT_ID: ${LANGFUSE_INIT_PROJECT_ID:-faden-project}
+      LANGFUSE_INIT_PROJECT_NAME: ${LANGFUSE_INIT_PROJECT_NAME:-fadenstack}
+      LANGFUSE_INIT_PROJECT_PUBLIC_KEY: ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY:-}
+      LANGFUSE_INIT_PROJECT_SECRET_KEY: ${LANGFUSE_INIT_PROJECT_SECRET_KEY:-}
+
+  # -----------------------------
+  # Shared RabbitMQ broker (API + RAG + local backend dev)
+  # -----------------------------
+  faden-rmq:
+    image: rabbitmq:4.2.1-management-alpine
+    container_name: faden-rmq
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:5672:5672"
+      - "127.0.0.1:15672:15672"
+    environment:
+      # Management/admin account — used for console login and as
+      # fallback when definitions.json is absent (dev mode).
+      RABBITMQ_DEFAULT_USER: ${RABBITMQ_ADMIN_USER:-admin}
+      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_ADMIN_PASS:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      RABBITMQ_DEFAULT_VHOST: "/"
+      # Limit Erlang schedulers and disable busy-wait to avoid CPU spin at idle.
+      # -S 2:2  — 2 online schedulers (enough for a message broker)
+      # +sbwt/+sbwtdcpu/+sbwtdio none — disable scheduler busy-waiting
+      RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS: "+S 2:2 +sbwt none +sbwtdcpu none +sbwtdio none"
+    volumes:
+      # Per-service user definitions (generated by faden deploy).
+      # In dev mode these files may not exist — RabbitMQ falls back
+      # to RABBITMQ_DEFAULT_USER/PASS.
+      - ./rabbitmq/10-faden.conf:/etc/rabbitmq/conf.d/10-faden.conf:ro
+      - ./rabbitmq/definitions.json:/etc/rabbitmq/definitions.json:ro
+    deploy:
+      resources:
+        limits:
+          cpus: "1"
+          memory: 512M
+    healthcheck:
+      test: rabbitmq-diagnostics check_running -q
+      interval: 3s
+      timeout: 3s
+      retries: 50
+
+  faden-gateway-migrator:
+    image: ${REGISTRY:-ghcr.io/fadenstack}/gateway:${VERSION:-latest}
+    container_name: faden-gateway-migrator
+    restart: on-failure:5
+    command: ["sh", "-c", "sleep 5 && alembic upgrade head"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      FADEN_GATEWAY_DB_HOST: postgres
+      FADEN_GATEWAY_DB_PORT: 5432
+      FADEN_GATEWAY_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_GATEWAY_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_GATEWAY_DB_BASE: faden_gateway
+
+  # -----------------------------
+  # faden_gateway (OpenAI-compatible endpoint gateway)
+  # -----------------------------
+  faden-gateway:
+    image: ${REGISTRY:-ghcr.io/fadenstack}/gateway:${VERSION:-latest}
+    build:
+      context: ../gateway
+      dockerfile: Dockerfile
+      target: prod
+      args:
+        BASE_IMAGE: ${REGISTRY:-ghcr.io/fadenstack}/base:${VERSION:-latest}
+    container_name: faden-gateway
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      faden-rmq:
+        condition: service_healthy
+      faden-gateway-migrator:
+        condition: service_completed_successfully
+    ports:
+      - "127.0.0.1:8001:8000"
+    environment:
+      FADEN_GATEWAY_HOST: 0.0.0.0
+      FADEN_GATEWAY_PORT: 8000
+      # Behind nginx, which sets X-Forwarded-Proto/For; uvicorn honours them
+      # only from these addresses (its default is 127.0.0.1, which nginx is
+      # not here). Every peer is on the compose network; the host port above
+      # is loopback-only.
+      FORWARDED_ALLOW_IPS: "*"
+      FADEN_GATEWAY_RELOAD: "false"
+      FADEN_GATEWAY_ENVIRONMENT: ${FADEN_GATEWAY_ENVIRONMENT:-production}
+      # JWT secret is read from backend DB at startup (faden_gateway.jwt_secret system setting).
+      # These two env vars enable that path; no static JWT_SECRET env var is needed.
+      FADEN_GATEWAY_BACKEND_DB_BASE: faden_backend
+      FADEN_GATEWAY_SETTINGS_MASTER_KEY: ${FADEN_BACKEND_SETTINGS_MASTER_KEY:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      # An install that has stored data under the published development key may
+      # keep it, with a warning at every start, until it is changed (Help:
+      # Installing, Secrets in .env). Outside development the service refuses it otherwise.
+      FADEN_GATEWAY_ALLOW_PUBLISHED_KEYS: ${FADEN_ALLOW_PUBLISHED_KEYS:-false}
+      # The key chats are encrypted with at rest: messages, titles, memory, a
+      # reply's events in Redis. `faden deploy` writes one into .env; it never
+      # reached the gateway, and every install stored its chats in plain text
+      # (2026-10-02). Empty still stores plain text. Rows from before stay
+      # readable. Without this key the encrypted chats cannot be read: .env
+      # belongs in every backup (`faden backup` takes it; --db-only does not).
+      FADEN_GATEWAY_ENCRYPTION_KEY: ${FADEN_GATEWAY_ENCRYPTION_KEY:-}
+      FADEN_GATEWAY_JWT_ALGORITHM: HS256
+      FADEN_GATEWAY_DB_HOST: postgres
+      FADEN_GATEWAY_DB_PORT: 5432
+      FADEN_GATEWAY_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_GATEWAY_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_GATEWAY_DB_BASE: faden_gateway
+      FADEN_GATEWAY_REDIS_HOST: redis
+      FADEN_GATEWAY_REDIS_PORT: 6379
+      FADEN_GATEWAY_REDIS_PASS: ${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_GATEWAY_REDIS_BASE: 1
+      FADEN_GATEWAY_RABBIT_HOST: faden-rmq
+      FADEN_GATEWAY_RABBIT_PORT: 5672
+      FADEN_GATEWAY_RABBIT_USER: faden-gateway
+      FADEN_GATEWAY_RABBIT_PASS: ${RABBITMQ_API_PASS:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_GATEWAY_RABBIT_VHOST: /
+      FADEN_GATEWAY_LANGFUSE_ENABLED: ${FADEN_GATEWAY_LANGFUSE_ENABLED:-false}
+      FADEN_GATEWAY_LANGFUSE_HOST: ${FADEN_GATEWAY_LANGFUSE_HOST:-http://langfuse-web:3000}
+      FADEN_GATEWAY_LANGFUSE_PUBLIC_KEY: ${FADEN_GATEWAY_LANGFUSE_PUBLIC_KEY:-}
+      FADEN_GATEWAY_LANGFUSE_SECRET_KEY: ${FADEN_GATEWAY_LANGFUSE_SECRET_KEY:-}
+      # PII module integration (set via .env or COMPOSE_PROFILES)
+      FADEN_GATEWAY_PII_ENABLED: ${FADEN_GATEWAY_PII_ENABLED:-false}
+      FADEN_GATEWAY_PII_SERVICE_URL: ${FADEN_GATEWAY_PII_SERVICE_URL:-http://faden-pii:8000}
+      # MCP tool registry integration (set via .env or COMPOSE_PROFILES)
+      FADEN_GATEWAY_MCP_ENABLED: ${FADEN_GATEWAY_MCP_ENABLED:-false}
+      FADEN_GATEWAY_MCP_SERVICE_URL: ${FADEN_GATEWAY_MCP_SERVICE_URL:-http://faden-mcp:8000}
+      FADEN_GATEWAY_MCP_SERVICE_TOKEN: ${FADEN_GATEWAY_MCP_SERVICE_TOKEN:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      # Skills registry integration (set via .env or COMPOSE_PROFILES)
+      FADEN_GATEWAY_SKILLS_ENABLED: ${FADEN_GATEWAY_SKILLS_ENABLED:-false}
+      FADEN_GATEWAY_SKILLS_SERVICE_URL: ${FADEN_GATEWAY_SKILLS_SERVICE_URL:-http://faden-skills:8000}
+      FADEN_GATEWAY_SKILLS_SERVICE_TOKEN: ${FADEN_GATEWAY_SKILLS_SERVICE_TOKEN:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      # Knowledge search runs in the backend. The default, 127.0.0.1:8000, is this container's own port:
+      # every search reached the gateway itself and failed with 404.
+      FADEN_GATEWAY_RAG_LITE_BACKEND_URL: ${FADEN_GATEWAY_RAG_LITE_BACKEND_URL:-http://faden-backend:8000}
+      # Media URLs in chat requests are fetched by the gateway, from public addresses only, and reach the
+      # model as data: URLs. Internal hosts, *.patterns or networks to fetch from too, comma-separated;
+      # the most a request's URLs may bring in (bytes) and the time one may take; false turns it all off.
+      FADEN_GATEWAY_MEDIA_URL_CHECK: ${FADEN_GATEWAY_MEDIA_URL_CHECK:-true}
+      FADEN_GATEWAY_MEDIA_URL_ALLOWED_HOSTS: ${FADEN_GATEWAY_MEDIA_URL_ALLOWED_HOSTS:-}
+      FADEN_GATEWAY_MEDIA_URL_MAX_BYTES: ${FADEN_GATEWAY_MEDIA_URL_MAX_BYTES:-20971520}
+      FADEN_GATEWAY_MEDIA_URL_TIMEOUT_SEC: ${FADEN_GATEWAY_MEDIA_URL_TIMEOUT_SEC:-20}
+      # Scalability tuning (set via faden tune)
+      FADEN_GATEWAY_WORKERS_COUNT: ${FADEN_GATEWAY_WORKERS_COUNT:-4}
+      # Chat replies one user may have written at once, across their chats.
+      FADEN_GATEWAY_CHAT_TURNS_PER_USER: ${FADEN_GATEWAY_CHAT_TURNS_PER_USER:-3}
+      FADEN_GATEWAY_DB_POOL_SIZE: ${FADEN_GATEWAY_DB_POOL_SIZE:-5}
+      FADEN_GATEWAY_DB_MAX_OVERFLOW: ${FADEN_GATEWAY_DB_MAX_OVERFLOW:-5}
+      FADEN_GATEWAY_RABBIT_POOL_SIZE: ${FADEN_GATEWAY_RABBIT_POOL_SIZE:-2}
+      FADEN_GATEWAY_RABBIT_CHANNEL_POOL_SIZE: ${FADEN_GATEWAY_RABBIT_CHANNEL_POOL_SIZE:-10}
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health', timeout=3).read()"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  # -----------------------------
+  # faden_backend (control-plane)
+  # -----------------------------
+  faden-backend-migrator:
+    image: ${REGISTRY:-ghcr.io/fadenstack}/backend:${VERSION:-latest}
+    container_name: faden-backend-migrator
+    restart: on-failure:5
+    command: ["sh", "-c", "sleep 5 && alembic upgrade head"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      FADEN_BACKEND_DB_HOST: postgres
+      FADEN_BACKEND_DB_PORT: 5432
+      FADEN_BACKEND_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_BACKEND_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_DB_BASE: faden_backend
+
+  faden-backend:
+    image: ${REGISTRY:-ghcr.io/fadenstack}/backend:${VERSION:-latest}
+    build:
+      context: ../backend
+      dockerfile: Dockerfile
+      target: prod
+      # The runtime manifests the Dockerfile copies in (see there).
+      additional_contexts:
+        runtime_manifests: ../runtime-image
+      args:
+        BASE_IMAGE: ${REGISTRY:-ghcr.io/fadenstack}/base:${VERSION:-latest}
+    container_name: faden-backend
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      faden-rmq:
+        condition: service_healthy
+      faden-backend-migrator:
+        condition: service_completed_successfully
+    # No host port — accessed via nginx reverse proxy
+    environment:
+      FADEN_BACKEND_HOST: 0.0.0.0
+      FADEN_BACKEND_PORT: 8000
+      # Behind nginx, which sets X-Forwarded-Proto/For; uvicorn honours them
+      # only from these addresses (its default is 127.0.0.1, which nginx is
+      # not here). Only the compose network reaches the backend, so any peer
+      # is ours. Without this the backend believes every request is plain
+      # HTTP: it would refuse a TLS upload and never mark a cookie Secure.
+      FORWARDED_ALLOW_IPS: "*"
+      FADEN_BACKEND_RELOAD: "false"
+      FADEN_BACKEND_ENVIRONMENT: ${FADEN_BACKEND_ENVIRONMENT:-production}
+      FADEN_BACKEND_DB_HOST: postgres
+      FADEN_BACKEND_DB_PORT: 5432
+      FADEN_BACKEND_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_BACKEND_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_DB_BASE: faden_backend
+      FADEN_BACKEND_REDIS_HOST: redis
+      FADEN_BACKEND_REDIS_PORT: 6379
+      FADEN_BACKEND_REDIS_PASS: ${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_RABBIT_HOST: faden-rmq
+      FADEN_BACKEND_RABBIT_PORT: 5672
+      FADEN_BACKEND_RABBIT_USER: faden-backend
+      FADEN_BACKEND_RABBIT_PASS: ${RABBITMQ_BACKEND_PASS:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_RABBIT_VHOST: /
+      FADEN_BACKEND_GATEWAY_URL: ${FADEN_BACKEND_GATEWAY_URL:-http://faden-gateway:8000}
+      FADEN_BACKEND_SETTINGS_MASTER_KEY: ${FADEN_BACKEND_SETTINGS_MASTER_KEY:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      # An install that has stored data under the published development key may
+      # keep it, with a warning at every start, until it is changed (Help:
+      # Installing, Secrets in .env). Outside development the service refuses it otherwise.
+      FADEN_BACKEND_ALLOW_PUBLISHED_KEYS: ${FADEN_ALLOW_PUBLISHED_KEYS:-false}
+      FADEN_BACKEND_LLM_GRAPH_DB_HOST: postgres
+      FADEN_BACKEND_LLM_GRAPH_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_BACKEND_LLM_GRAPH_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_LOKI_BASE_URL: http://faden-loki:3100
+      FADEN_BACKEND_COOKIE_SECURE: "false"
+      USERS_SECRET: ${USERS_SECRET:-}
+      # Asked for before the first administrator is created (POST /api/bootstrap);
+      # `faden deploy` writes it into .env and sends it. Empty: bootstrap is refused.
+      FADEN_BACKEND_BOOTSTRAP_TOKEN: ${FADEN_BACKEND_BOOTSTRAP_TOKEN:-}
+      # The update check (Settings > Updates overrides it): `faden deploy` asks whether to read
+      # the public list of releases once a day. The release this install runs and how the CLI
+      # was installed give the console the upgrade commands to show.
+      FADEN_BACKEND_UPDATES_CHECK_ENABLED: ${FADEN_UPDATE_CHECK:-true}
+      # A copy of the release list in your network, for a server without internet (Settings > Updates too).
+      FADEN_BACKEND_UPDATES_FEED_URL: ${FADEN_UPDATE_FEED_URL:-}
+      FADEN_BACKEND_INSTALL_RELEASE: ${VERSION:-}
+      FADEN_BACKEND_CLI_INSTALLER: ${FADEN_CLI_INSTALLER:-}
+      # Module enabled flags + service URLs (Docker-internal for health probes)
+      FADEN_BACKEND_PII_ENABLED: ${FADEN_BACKEND_PII_ENABLED:-false}
+      FADEN_BACKEND_PII_SERVICE_URL: ${FADEN_BACKEND_PII_SERVICE_URL:-http://faden-pii:8000/api}
+      FADEN_BACKEND_INTERNAL_TOKEN: ${FADEN_BACKEND_INTERNAL_TOKEN:-}
+      FADEN_BACKEND_MCP_ENABLED: ${FADEN_BACKEND_MCP_ENABLED:-false}
+      FADEN_BACKEND_MCP_SERVICE_URL: ${FADEN_BACKEND_MCP_SERVICE_URL:-http://faden-mcp:8000}
+      FADEN_BACKEND_MCP_SERVICE_TOKEN: ${FADEN_BACKEND_MCP_SERVICE_TOKEN:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_SKILLS_ENABLED: ${FADEN_BACKEND_SKILLS_ENABLED:-false}
+      FADEN_BACKEND_MAILER_SERVICE_URL: ${FADEN_BACKEND_MAILER_SERVICE_URL:-http://faden-mailer:8000}
+      FADEN_BACKEND_AUTH_SERVICE_URL: ${FADEN_BACKEND_AUTH_SERVICE_URL:-http://faden-auth:8000}
+      FADEN_BACKEND_DOCLING_SERVICE_URL: ${FADEN_BACKEND_DOCLING_SERVICE_URL:-http://faden-docling:8000}
+      FADEN_BACKEND_SKILLS_SERVICE_URL: ${FADEN_BACKEND_SKILLS_SERVICE_URL:-http://faden-skills:8000}
+      FADEN_BACKEND_SKILLS_SERVICE_TOKEN: ${FADEN_BACKEND_SKILLS_SERVICE_TOKEN:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      # Scalability tuning (set via faden tune)
+      FADEN_BACKEND_WORKERS_COUNT: ${FADEN_BACKEND_WORKERS_COUNT:-4}
+      FADEN_BACKEND_DB_POOL_SIZE: ${FADEN_BACKEND_DB_POOL_SIZE:-5}
+      FADEN_BACKEND_DB_MAX_OVERFLOW: ${FADEN_BACKEND_DB_MAX_OVERFLOW:-5}
+      FADEN_BACKEND_RABBIT_POOL_SIZE: ${FADEN_BACKEND_RABBIT_POOL_SIZE:-2}
+      FADEN_BACKEND_RABBIT_CHANNEL_POOL_SIZE: ${FADEN_BACKEND_RABBIT_CHANNEL_POOL_SIZE:-10}
+      FADEN_BACKEND_MODEL_STORE_ROOT: /srv/faden/models
+      FADEN_BACKEND_HOST_HF_CACHE_DIR: ${FADEN_BACKEND_HOST_HF_CACHE_DIR:-}
+      # Runtime monitoring: the clusters' and runtimes' scrape targets for the
+      # Prometheus above and their Grafana dashboards. The cluster page and the
+      # providers' live figures read it. Off with
+      # FADEN_BACKEND_LLM_MONITORING_ENABLED=false.
+      FADEN_BACKEND_LLM_MONITORING_ENABLED: ${FADEN_BACKEND_LLM_MONITORING_ENABLED:-true}
+      FADEN_BACKEND_PROM_URL: http://prometheus:9090
+      FADEN_BACKEND_PROM_TARGETS_FILE: /opt/faden/monitoring/prometheus/targets.json
+      FADEN_BACKEND_PROM_DASHBOARD_DIR: /opt/faden/monitoring/dashboards
+      FADEN_BACKEND_DASH_TEMPLATE: /opt/faden/monitoring/templates/vllm-runtime.json
+      FADEN_BACKEND_DASH_FOLDER: "LLM Runtimes"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - faden_models:/srv/faden/models
+      # Knowledge base uploads (rag_lite.file_store_root): written here, read by faden-backend-worker,
+      # which ingests them. Each container had its own: the worker found no file, every ingest failed,
+      # and the uploads went with the container.
+      - faden_rag_lite:/data/faden/rag-lite
+      # Runtime monitoring — shared with the prometheus + grafana
+      # services (see their mounts). The backend generates
+      # prometheus/targets.json and dashboards/*.json here; grafana
+      # reads the same json dir via its provisioning mount.
+      - ./prometheus/targets.json:/opt/faden/monitoring/prometheus/targets.json:rw
+      - ./grafana/provisioning/dashboards/json:/opt/faden/monitoring/dashboards:rw
+      - ./grafana/dashboards/templates:/opt/faden/monitoring/templates:ro
+      # Agent builds the install line hands out (faden-agent-linux-<arch>).
+      # Without a copy here a machine can only fetch the published release,
+      # which an air-gapped site cannot reach and a new agent may not be yet.
+      - ./agent-binaries:/srv/faden/agent-binaries:ro
+      # The edge certificate and key the TLS admin API writes; nginx mounts
+      # the same directory read-only and serves HTTPS from it.
+      - ./tls:/etc/faden/tls:rw
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health', timeout=3).read()"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  faden-backend-worker:
+    image: ${REGISTRY:-ghcr.io/fadenstack}/backend:${VERSION:-latest}
+    container_name: faden-backend-worker
+    restart: unless-stopped
+    command:
+      - taskiq
+      - worker
+      - faden_backend.tkq:broker
+      - --fs-discover
+      # Processes: two, or one on a server short of memory (set via faden tune).
+      - --workers
+      - ${FADEN_BACKEND_TASK_WORKERS:-2}
+    depends_on:
+      postgres:
+        condition: service_healthy
+      faden-rmq:
+        condition: service_healthy
+      faden-backend-migrator:
+        condition: service_completed_successfully
+    environment:
+      FADEN_BACKEND_ENVIRONMENT: ${FADEN_BACKEND_ENVIRONMENT:-production}
+      FADEN_BACKEND_DB_HOST: postgres
+      FADEN_BACKEND_DB_PORT: 5432
+      FADEN_BACKEND_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_BACKEND_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_DB_BASE: faden_backend
+      FADEN_BACKEND_REDIS_HOST: redis
+      FADEN_BACKEND_REDIS_PORT: 6379
+      FADEN_BACKEND_REDIS_PASS: ${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_RABBIT_HOST: faden-rmq
+      FADEN_BACKEND_RABBIT_PORT: 5672
+      FADEN_BACKEND_RABBIT_USER: faden-backend
+      FADEN_BACKEND_RABBIT_PASS: ${RABBITMQ_BACKEND_PASS:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_RABBIT_VHOST: /
+      FADEN_BACKEND_GATEWAY_URL: ${FADEN_BACKEND_GATEWAY_URL:-http://faden-gateway:8000}
+      FADEN_BACKEND_SETTINGS_MASTER_KEY: ${FADEN_BACKEND_SETTINGS_MASTER_KEY:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_LLM_GRAPH_DB_HOST: postgres
+      FADEN_BACKEND_LLM_GRAPH_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_BACKEND_LLM_GRAPH_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_LOKI_BASE_URL: http://faden-loki:3100
+      FADEN_BACKEND_COOKIE_SECURE: "false"
+      USERS_SECRET: ${USERS_SECRET:-}
+      # Module enabled flags + service URLs (Docker-internal for health probes)
+      FADEN_BACKEND_MCP_ENABLED: ${FADEN_BACKEND_MCP_ENABLED:-false}
+      FADEN_BACKEND_SKILLS_ENABLED: ${FADEN_BACKEND_SKILLS_ENABLED:-false}
+      FADEN_BACKEND_PII_SERVICE_URL: ${FADEN_BACKEND_PII_SERVICE_URL:-http://faden-pii:8000/api}
+      FADEN_BACKEND_INTERNAL_TOKEN: ${FADEN_BACKEND_INTERNAL_TOKEN:-}
+      FADEN_BACKEND_MCP_SERVICE_URL: ${FADEN_BACKEND_MCP_SERVICE_URL:-http://faden-mcp:8000}
+      FADEN_BACKEND_MCP_SERVICE_TOKEN: ${FADEN_BACKEND_MCP_SERVICE_TOKEN:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_BACKEND_MAILER_SERVICE_URL: ${FADEN_BACKEND_MAILER_SERVICE_URL:-http://faden-mailer:8000}
+      FADEN_BACKEND_AUTH_SERVICE_URL: ${FADEN_BACKEND_AUTH_SERVICE_URL:-http://faden-auth:8000}
+      FADEN_BACKEND_DOCLING_SERVICE_URL: ${FADEN_BACKEND_DOCLING_SERVICE_URL:-http://faden-docling:8000}
+      FADEN_BACKEND_SKILLS_SERVICE_URL: ${FADEN_BACKEND_SKILLS_SERVICE_URL:-http://faden-skills:8000}
+      FADEN_BACKEND_SKILLS_SERVICE_TOKEN: ${FADEN_BACKEND_SKILLS_SERVICE_TOKEN:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      # Scalability tuning (set via faden tune)
+      FADEN_BACKEND_DB_POOL_SIZE: ${FADEN_BACKEND_DB_POOL_SIZE:-5}
+      FADEN_BACKEND_DB_MAX_OVERFLOW: ${FADEN_BACKEND_DB_MAX_OVERFLOW:-5}
+      FADEN_BACKEND_RABBIT_POOL_SIZE: ${FADEN_BACKEND_RABBIT_POOL_SIZE:-2}
+      FADEN_BACKEND_RABBIT_CHANNEL_POOL_SIZE: ${FADEN_BACKEND_RABBIT_CHANNEL_POOL_SIZE:-10}
+      FADEN_BACKEND_MODEL_STORE_ROOT: /srv/faden/models
+      FADEN_BACKEND_HOST_HF_CACHE_DIR: ${FADEN_BACKEND_HOST_HF_CACHE_DIR:-}
+      # Ranges a model download fetches at once, up to 64 MB each in memory
+      # (set via faden tune: fewer on a server short of memory).
+      HF_XET_NUM_CONCURRENT_RANGE_GETS: ${FADEN_BACKEND_DOWNLOAD_RANGES:-16}
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - faden_models:/srv/faden/models
+      - faden_rag_lite:/data/faden/rag-lite
+
+  # -----------------------------
+  # frontend (React admin console)
+  # -----------------------------
+  faden-frontend:
+    image: ${REGISTRY:-ghcr.io/fadenstack}/frontend:${VERSION:-latest}
+    build:
+      context: ../frontend
+      dockerfile: Dockerfile
+      # Help is built into the image from docs/help and docs/theme and served at /help.
+      additional_contexts:
+        docs: ../docs
+    container_name: faden-frontend
+    restart: unless-stopped
+    depends_on:
+      faden-backend:
+        condition: service_healthy
+    # No host port — accessed via nginx reverse proxy
+    environment:
+      BACKEND_URL: http://faden-backend:8000
+      API_URL: http://faden-gateway:8000
+
+  # =====================================================================
+  # PII Protection (profile: pii)
+  #
+  # Core redact-only mode. EE extends with tokenize/detokenize.
+  # Activate with:  --profile pii  (or COMPOSE_PROFILES=pii)
+  # =====================================================================
+  faden-pii:
+    profiles: ["pii"]
+    image: ${REGISTRY:-ghcr.io/fadenstack}/pii:${VERSION:-latest}
+    build:
+      context: ../pii
+      dockerfile: Dockerfile
+      target: prod
+      args:
+        BASE_IMAGE: ${REGISTRY:-ghcr.io/fadenstack}/base:${VERSION:-latest}
+    container_name: faden-pii
+    restart: unless-stopped
+    depends_on:
+      faden-rmq:
+        condition: service_healthy
+    environment:
+      FADEN_PII_HOST: 0.0.0.0
+      FADEN_PII_PORT: 8000
+      FADEN_PII_RELOAD: "false"
+      FADEN_PII_ENVIRONMENT: ${FADEN_PII_ENVIRONMENT:-production}
+      FADEN_PII_BACKEND_URL: http://faden-backend:8000
+      FADEN_PII_BACKEND_TOKEN: ${FADEN_PII_BACKEND_TOKEN:-}
+      FADEN_PII_RABBIT_HOST: faden-rmq
+      FADEN_PII_RABBIT_PORT: 5672
+      FADEN_PII_RABBIT_USER: faden-pii
+      FADEN_PII_RABBIT_PASS: ${RABBITMQ_PII_PASS:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_PII_RABBIT_VHOST: /
+      # Scalability tuning (set via faden tune)
+      FADEN_PII_WORKERS_COUNT: ${FADEN_PII_WORKERS_COUNT:-4}
+      FADEN_PII_DB_POOL_SIZE: ${FADEN_PII_DB_POOL_SIZE:-5}
+      FADEN_PII_DB_MAX_OVERFLOW: ${FADEN_PII_DB_MAX_OVERFLOW:-5}
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health', timeout=3).read()"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  faden-pii-worker:
+    profiles: ["pii"]
+    image: ${REGISTRY:-ghcr.io/fadenstack}/pii:${VERSION:-latest}
+    container_name: faden-pii-worker
+    restart: unless-stopped
+    command:
+      - taskiq
+      - worker
+      - faden_pii.tkq:broker
+      - --fs-discover
+    depends_on:
+      faden-rmq:
+        condition: service_healthy
+    environment:
+      FADEN_PII_ENVIRONMENT: ${FADEN_PII_ENVIRONMENT:-production}
+      FADEN_PII_BACKEND_URL: http://faden-backend:8000
+      FADEN_PII_BACKEND_TOKEN: ${FADEN_PII_BACKEND_TOKEN:-}
+      FADEN_PII_RABBIT_HOST: faden-rmq
+      FADEN_PII_RABBIT_PORT: 5672
+      FADEN_PII_RABBIT_USER: faden-pii
+      FADEN_PII_RABBIT_PASS: ${RABBITMQ_PII_PASS:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_PII_RABBIT_VHOST: /
+
+  # =====================================================================
+  # MCP Tool Registry (profile: mcp)
+  #
+  # Generic MCP server registry + tool discovery.
+  # Activate with:  --profile mcp  (or COMPOSE_PROFILES=mcp)
+  # =====================================================================
+  faden-mcp-migrator:
+    profiles: ["mcp"]
+    image: ${REGISTRY:-ghcr.io/fadenstack}/mcp:${VERSION:-latest}
+    container_name: faden-mcp-migrator
+    restart: on-failure:5
+    command: ["sh", "-c", "sleep 5 && alembic upgrade head"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      FADEN_MCP_DB_HOST: postgres
+      FADEN_MCP_DB_PORT: 5432
+      FADEN_MCP_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_MCP_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_MCP_DB_BASE: faden_mcp
+
+  faden-mcp:
+    profiles: ["mcp"]
+    image: ${REGISTRY:-ghcr.io/fadenstack}/mcp:${VERSION:-latest}
+    build:
+      context: ../mcp
+      dockerfile: Dockerfile
+      target: prod
+      args:
+        BASE_IMAGE: ${REGISTRY:-ghcr.io/fadenstack}/base:${VERSION:-latest}
+    container_name: faden-mcp
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      faden-mcp-migrator:
+        condition: service_completed_successfully
+    environment:
+      FADEN_MCP_HOST: 0.0.0.0
+      FADEN_MCP_PORT: 8000
+      FADEN_MCP_RELOAD: "false"
+      FADEN_MCP_ENVIRONMENT: ${FADEN_MCP_ENVIRONMENT:-production}
+      FADEN_MCP_DB_HOST: postgres
+      FADEN_MCP_DB_PORT: 5432
+      FADEN_MCP_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_MCP_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_MCP_DB_BASE: faden_mcp
+      FADEN_MCP_REDIS_HOST: redis
+      FADEN_MCP_REDIS_PORT: 6379
+      FADEN_MCP_REDIS_PASS: ${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_MCP_REDIS_BASE: 3
+      FADEN_MCP_PII_SERVICE_URL: ${FADEN_MCP_PII_SERVICE_URL:-http://faden-pii:8000}
+      FADEN_MCP_SERVICE_TOKEN: ${FADEN_MCP_SERVICE_TOKEN:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_MCP_ENCRYPTION_KEY: ${FADEN_MCP_ENCRYPTION_KEY:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      # An install that has stored data under the published development key may
+      # keep it, with a warning at every start, until it is changed (Help:
+      # Installing, Secrets in .env). Outside development the service refuses it otherwise.
+      FADEN_MCP_ALLOW_PUBLISHED_KEYS: ${FADEN_ALLOW_PUBLISHED_KEYS:-false}
+      FADEN_MCP_WORKERS_COUNT: ${FADEN_MCP_WORKERS_COUNT:-1}
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health', timeout=3).read()"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+
+  # =====================================================================
+  # Skills Registry (profile: skills)
+  #
+  # Centralized LLM skill management with versioning & assignments.
+  # Activate with:  --profile skills  (or COMPOSE_PROFILES=skills)
+  # =====================================================================
+  faden-skills-migrator:
+    profiles: ["skills"]
+    image: ${REGISTRY:-ghcr.io/fadenstack}/skills:${VERSION:-latest}
+    container_name: faden-skills-migrator
+    restart: on-failure:5
+    command: ["sh", "-c", "sleep 5 && alembic upgrade head"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      FADEN_SKILLS_DB_HOST: postgres
+      FADEN_SKILLS_DB_PORT: 5432
+      FADEN_SKILLS_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_SKILLS_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_SKILLS_DB_BASE: faden_skills
+
+  faden-skills:
+    profiles: ["skills"]
+    image: ${REGISTRY:-ghcr.io/fadenstack}/skills:${VERSION:-latest}
+    build:
+      context: ../skills
+      dockerfile: Dockerfile
+      target: prod
+      args:
+        BASE_IMAGE: ${REGISTRY:-ghcr.io/fadenstack}/base:${VERSION:-latest}
+    container_name: faden-skills
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      faden-skills-migrator:
+        condition: service_completed_successfully
+    environment:
+      FADEN_SKILLS_HOST: 0.0.0.0
+      FADEN_SKILLS_PORT: 8000
+      FADEN_SKILLS_RELOAD: "false"
+      FADEN_SKILLS_ENVIRONMENT: ${FADEN_SKILLS_ENVIRONMENT:-production}
+      FADEN_SKILLS_DB_HOST: postgres
+      FADEN_SKILLS_DB_PORT: 5432
+      FADEN_SKILLS_DB_USER: ${POSTGRES_USER:-postgres}
+      FADEN_SKILLS_DB_PASS: ${POSTGRES_PASSWORD:?set it in .env; an install that ran without it keeps its data only with the old default value (Help, Installing, Secrets in .env)}
+      FADEN_SKILLS_DB_BASE: faden_skills
+      FADEN_SKILLS_REDIS_HOST: redis
+      FADEN_SKILLS_REDIS_PORT: 6379
+      FADEN_SKILLS_REDIS_PASS: ${REDIS_AUTH:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_SKILLS_REDIS_BASE: 4
+      FADEN_SKILLS_SERVICE_TOKEN: ${FADEN_SKILLS_SERVICE_TOKEN:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      FADEN_SKILLS_WORKERS_COUNT: ${FADEN_SKILLS_WORKERS_COUNT:-1}
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health', timeout=3).read()"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  # -----------------------------
+  # Observability: Loki + Grafana + Alloy + Prometheus
+  # -----------------------------
+  prometheus:
+    # Scrape targets for LLM runtime (vLLM) /metrics endpoints.
+    # targets.json is GENERATED by the backend's monitoring
+    # provisioner (bound rw below); the service never binds a public
+    # host port — Grafana and the backend reach it on the compose
+    # network. Set PROM_BIND=127.0.0.1 is the safe default (loopback
+    # for debugging); omit the port entirely if you want it
+    # compose-private.
+    image: prom/prometheus:v2.53.0
+    container_name: faden-prometheus
+    restart: unless-stopped
+    ports:
+      # Not 9090 on the host: MinIO's API is published there in this stack,
+      # and with that default an upgrade stopped on "Bind for 127.0.0.1:9090
+      # failed: port is already allocated". Inside the compose network
+      # Prometheus is always :9090, which is what Grafana and the backend use.
+      - "${PROM_BIND:-127.0.0.1}:${PROM_PORT:-9099}:9090"
+    command:
+      - --config.file=/etc/prometheus/prometheus.yml
+      - --storage.tsdb.path=/prometheus
+      - --storage.tsdb.retention.time=14d
+      - --web.enable-lifecycle
+    volumes:
+      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      # Generated by faden-backend — do not hand-edit.
+      - ./prometheus/targets.json:/etc/prometheus/targets.json:rw
+      - prom_data:/prometheus
+    extra_hosts:
+      # Lets us scrape LOCAL_DOCKER runtimes on this host (mirrors the
+      # backend service's host-gateway mapping).
+      - "host.docker.internal:host-gateway"
+
+  loki:
+    image: grafana/loki:3.0.0
+    container_name: faden-loki
+    restart: unless-stopped
+    # Loki has no authentication — it must never be reachable from the
+    # network. Default to the loopback interface only; set LOKI_BIND
+    # deliberately if you need to expose it behind a firewall/proxy.
+    ports:
+      - "${LOKI_BIND:-127.0.0.1}:3100:3100"
+    command: -config.file=/etc/loki/local-config.yaml
+    volumes:
+      - ./loki/local-config.yaml:/etc/loki/local-config.yaml:ro
+      - loki_data:/loki
+
+  grafana:
+    # 12.4, the last 12.x line, security-supported until May 2027 (11.6 ended in
+    # June 2026), pinned by digest. It carries the fixes for the XSS advisories
+    # 11.5.2 lacked (CVE-2025-2703, CVE-2025-4123, CVE-2025-6023 and its bypass).
+    # The dashboards use only core panels, which 12 still ships. Grafana
+    # migrates its database on the first start (tested from 11.5.2); going
+    # back needs the backup the upgrade makes.
+    image: grafana/grafana:12.4.12@sha256:a3b504df900c24db125e5ec0646f3ac3428db38161302d69f05d0db70a330a90
+    container_name: faden-grafana
+    restart: unless-stopped
+    ports:
+      # Dashboards, anonymous read-only (login form disabled), plain HTTP. The
+      # console reaches them through nginx at /grafana/ -- over HTTPS when that
+      # is on -- so the port itself stays on this machine by default; published
+      # on the network it bypassed HTTPS and showed every dashboard to anyone.
+      # GRAFANA_BIND=0.0.0.0 publishes it.
+      - "${GRAFANA_BIND:-127.0.0.1}:3001:3000"
+    environment:
+      GF_SECURITY_ADMIN_USER: ${GRAFANA_ADMIN_USER:-admin}
+      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:?set it in .env, as faden deploy and faden upgrade do (Help, Installing, Secrets in .env)}
+      GF_SECURITY_ALLOW_EMBEDDING: "true"
+      GF_SECURITY_COOKIE_SAMESITE: "disabled"
+      GF_AUTH_ANONYMOUS_ENABLED: "true"
+      GF_AUTH_ANONYMOUS_ORG_ROLE: Viewer
+      GF_AUTH_ANONYMOUS_ORG_NAME: Main Org.
+      GF_AUTH_DISABLE_LOGIN_FORM: "true"
+      GF_AUTH_BASIC_ENABLED: "false"
+      GF_SERVER_ROOT_URL: "%(protocol)s://%(domain)s:%(http_port)s/grafana/"
+      GF_SERVER_SERVE_FROM_SUB_PATH: "true"
+      GF_PLUGINS_PREINSTALL: ""
+      GF_PATHS_PROVISIONING: /etc/grafana/provisioning
+      # Nothing leaves this server: no usage reports, no update or plugin
+      # checks against grafana.com, no news feed, no Gravatar pictures.
+      GF_ANALYTICS_REPORTING_ENABLED: "false"
+      GF_ANALYTICS_CHECK_FOR_UPDATES: "false"
+      GF_ANALYTICS_CHECK_FOR_PLUGIN_UPDATES: "false"
+      GF_NEWS_NEWS_FEED_ENABLED: "false"
+      GF_SECURITY_DISABLE_GRAVATAR: "true"
+    volumes:
+      - grafana_data:/var/lib/grafana
+      - ./grafana/provisioning:/etc/grafana/provisioning:ro
+    depends_on:
+      - loki
+
+  alloy:
+    # Pinned, not :latest: an install otherwise ran whatever was published
+    # last. --disable-reporting: no usage reports to Grafana Labs.
+    image: grafana/alloy:v1.20.1@sha256:2aa2099af76c0098d4af7a4d6e48f86cb66dc1a000222ad927a1c67c6542d13f
+    container_name: faden-alloy
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:12345:12345"
+    command: >
+      run --server.http.listen-addr=0.0.0.0:12345
+      --disable-reporting
+      /etc/alloy/config.alloy
+    volumes:
+      - ./alloy/config.alloy:/etc/alloy/config.alloy:ro
+      # Docker Desktop on Windows exposes the socket here; Linux path is /var/run/docker.sock
+      - //var/run/docker.sock:/var/run/docker.sock:ro
+    depends_on:
+      - loki
+
+
+
+volumes:
+  pg_data:
+  ch_data:
+  ch_logs:
+  minio_data:
+  loki_data:
+  grafana_data:
+  prom_data:
+  faden_models:
+  faden_rag_lite: