docker-compose.yml

# Breeze RMM - Production Deployment
# Pull pre-built images from GHCR. No build step required.
#
# BREEZE_VERSION must be set in .env for runtime metadata, and image refs must
# be digest-pinned for reproducible deploys. Mutable tags like `:latest` are
# intentionally rejected to prevent surprise rollouts.
#
# Quick start (see README for full instructions):
#   git clone https://github.com/LanternOps/breeze.git && cd breeze
#   cp .env.example .env  # Edit with your secrets, domain, and BREEZE_VERSION
#   # On first boot only, set BREEZE_BOOTSTRAP_ADMIN_EMAIL/PASSWORD in .env.
#   docker compose up -d
#
# Optional monitoring stack:
#   docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

x-healthcheck-defaults: &healthcheck
  interval: 30s
  timeout: 10s
  retries: 3

services:
  binaries-init:
    image: ${BREEZE_BINARIES_IMAGE_REF:?Set BREEZE_BINARIES_IMAGE_REF to a digest-pinned image ref}
    pull_policy: always
    container_name: breeze-binaries-init
    volumes:
      - binaries:/target
    restart: "no"
    networks:
      - breeze

  caddy:
    image: ${CADDY_IMAGE_REF:?Set CADDY_IMAGE_REF to a digest-pinned Caddy image ref}
    container_name: breeze-caddy
    restart: unless-stopped
    ports:
      - '80:80'
      - '443:443'
    environment:
      CADDY_SITE_ADDRESS: "${BREEZE_DOMAIN:-:80}"
      ACME_EMAIL: ${ACME_EMAIL:-}
      CADDY_TRUSTED_PROXIES: "${CADDY_TRUSTED_PROXIES:-127.0.0.1/32 ::1/128}"
      CADDY_CLIENT_IP_HEADERS: "${CADDY_CLIENT_IP_HEADERS:-CF-Connecting-IP X-Forwarded-For}"
      REMOTE_ACCESS_ADMISSION_MODE: ${REMOTE_ACCESS_ADMISSION_MODE:?Set REMOTE_ACCESS_ADMISSION_MODE to open or closed}
    volumes:
      - ./docker/Caddyfile.prod:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      web:
        condition: service_healthy
      portal:
        condition: service_healthy
      api:
        condition: service_healthy
    healthcheck:
      <<: *healthcheck
      test: ['CMD', 'caddy', 'version']
      start_period: 20s
    # Static IP so the API can identify the bundled Caddy as its immediate peer
    # and trust the client IP it forwards (TRUSTED_PROXY_CIDRS below defaults to
    # this address). Override BREEZE_CADDY_IP only together with
    # TRUSTED_PROXY_CIDRS and BREEZE_DOCKER_SUBNET — see .env.example.
    networks:
      breeze:
        ipv4_address: ${BREEZE_CADDY_IP:-172.31.0.10}

  api:
    image: ${BREEZE_API_IMAGE_REF:?Set BREEZE_API_IMAGE_REF to a digest-pinned image ref}
    platform: ${DOCKER_PLATFORM:-linux/amd64}
    container_name: breeze-api
    restart: unless-stopped
    # Keep the root filesystem writable while redis_password is environment-backed;
    # standalone Compose supports only file-backed secrets for read-only services.
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    tmpfs:
      - /tmp:size=64m,mode=1777
    environment:
      NODE_ENV: production
      API_PORT: 3001
      DATABASE_URL: postgresql://${POSTGRES_USER:-breeze}:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}@postgres:5432/${POSTGRES_DB:-breeze}
      # The request pool derives its breeze_app URL from DATABASE_URL and the same
      # effective password ensureAppRole uses to CREATE/ALTER that unprivileged role.
      # DATABASE_URL_APP takes precedence and is required for multi-host/HA URLs,
      # which cannot be derived. All three must be mapped here — compose only
      # interpolates vars listed in this block, so omitting one makes a value set
      # in .env silently inert.
      DATABASE_URL_APP: ${DATABASE_URL_APP:-}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      BREEZE_APP_DB_PASSWORD: ${BREEZE_APP_DB_PASSWORD:-}
      # Pool-health watchdog (#3214). Threaded because deploy/environment.mdx
      # documents these as working knobs, and an unmapped var set in .env is
      # silently inert — the IS_HOSTED / #570 failure mode. All optional: an
      # empty value reads as unset and the code applies its own defaults.
      DB_POOL_HEALTH_DISABLED: ${DB_POOL_HEALTH_DISABLED:-}
      DB_POOL_HEALTH_INTERVAL_MS: ${DB_POOL_HEALTH_INTERVAL_MS:-}
      DB_POOL_HEALTH_WINDOW_MS: ${DB_POOL_HEALTH_WINDOW_MS:-}
      DB_POOL_HEALTH_MIN_TIMEOUTS: ${DB_POOL_HEALTH_MIN_TIMEOUTS:-}
      DB_POOL_HEALTH_PROBE_TIMEOUT_MS: ${DB_POOL_HEALTH_PROBE_TIMEOUT_MS:-}
      DB_POOL_HEALTH_CAPTURE_THROTTLE_MS: ${DB_POOL_HEALTH_CAPTURE_THROTTLE_MS:-}
      # Event-loop lag monitor (#3024). Same reasoning as the pool-health block
      # above: deploy/environment.mdx documents these as working knobs, and an
      # unmapped var set in .env is silently inert. The monitor runs on its
      # defaults either way, so this only ever blocked tuning — but an operator
      # raising the warn threshold to cut noise, or setting DISABLED to turn it
      # off, saw no change and no error. All optional: an empty value reads as
      # unset and the code applies its own defaults.
      EVENT_LOOP_MONITOR_INTERVAL_MS: ${EVENT_LOOP_MONITOR_INTERVAL_MS:-}
      EVENT_LOOP_STARVATION_WARN_MS: ${EVENT_LOOP_STARVATION_WARN_MS:-}
      EVENT_LOOP_MONITOR_DISABLED: ${EVENT_LOOP_MONITOR_DISABLED:-}
      REDIS_HOST: redis
      REDIS_PORT: 6379
      REDIS_PASSWORD_FILE: /run/secrets/redis_password
      REMOTE_ACCESS_ADMISSION_MODE: ${REMOTE_ACCESS_ADMISSION_MODE:?Set REMOTE_ACCESS_ADMISSION_MODE to open or closed}
      REMOTE_WS_AUTH_MODE: ${REMOTE_WS_AUTH_MODE:?Set REMOTE_WS_AUTH_MODE to post_upgrade or pre_upgrade}
      REMOTE_WS_REDIS_TOPOLOGY: ${REMOTE_WS_REDIS_TOPOLOGY:?Set REMOTE_WS_REDIS_TOPOLOGY to standalone-single-primary}
      REMOTE_WS_LEGACY_TICKET_WRITER_DRAINED_AT: ${REMOTE_WS_LEGACY_TICKET_WRITER_DRAINED_AT:-}
      REMOTE_WS_LEGACY_VIEWER_ISSUER_DRAINED_AT: ${REMOTE_WS_LEGACY_VIEWER_ISSUER_DRAINED_AT:-}
      JWT_SECRET: ${JWT_SECRET:?Set JWT_SECRET in .env}
      PARTNER_API_CURSOR_SIGNING_KEY: ${PARTNER_API_CURSOR_SIGNING_KEY:?Set PARTNER_API_CURSOR_SIGNING_KEY in .env}
      AGENT_ENROLLMENT_SECRET: ${AGENT_ENROLLMENT_SECRET:?Set AGENT_ENROLLMENT_SECRET in .env}
      # Backup control-plane URL pushed to agents via heartbeat (#2288);
      # see docs/deploy/agent-server-url-migration.md
      AGENT_BACKUP_SERVER_URL: ${AGENT_BACKUP_SERVER_URL:-}
      BREEZE_BOOTSTRAP_ADMIN_EMAIL: ${BREEZE_BOOTSTRAP_ADMIN_EMAIL:-}
      BREEZE_BOOTSTRAP_ADMIN_PASSWORD: ${BREEZE_BOOTSTRAP_ADMIN_PASSWORD:-}
      BREEZE_BOOTSTRAP_ADMIN_NAME: ${BREEZE_BOOTSTRAP_ADMIN_NAME:-}
      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-https://${BREEZE_DOMAIN}}
      PUBLIC_APP_URL: ${PUBLIC_APP_URL:-https://${BREEZE_DOMAIN}}
      DASHBOARD_URL: ${DASHBOARD_URL:-https://${BREEZE_DOMAIN}}
      PUBLIC_API_URL: ${PUBLIC_API_URL:-https://${BREEZE_DOMAIN}}
      # Public origin for customer-portal links (e.g. quote accept emails). The
      # portal is served under /portal on the main domain; falls back to PUBLIC_APP_URL.
      PUBLIC_PORTAL_URL: ${PUBLIC_PORTAL_URL:-https://${BREEZE_DOMAIN}/portal}
      API_URL: ${API_URL:-}
      FORCE_HTTPS: ${FORCE_HTTPS:-true}
      # The bundled Caddy is the only trusted peer, and we pin its address
      # ourselves (see the caddy service). Anything else reaching the API
      # directly is untrusted and falls back to its raw socket peer. Operators
      # who front the API with their own proxy must point TRUSTED_PROXY_CIDRS at
      # it — a CIDR that matches nothing simply means no headers are trusted.
      TRUST_PROXY_HEADERS: ${TRUST_PROXY_HEADERS:-true}
      TRUSTED_PROXY_CIDRS: ${TRUSTED_PROXY_CIDRS:-${BREEZE_CADDY_IP:-172.31.0.10}/32}
      # Only trust CF-Connecting-IP when this deployment is genuinely fronted by
      # Cloudflare — a non-CF reverse proxy does not strip the header, so a
      # client could otherwise spoof it. Off by default; set true in .env only
      # if you front Breeze with Cloudflare.
      TRUST_CF_CONNECTING_IP: ${TRUST_CF_CONNECTING_IP:-}
      # off is the safe mixed-version and self-hosted default: the edge
      # certificate assertion is never consulted, so leaving this unset is a
      # no-op. Never inferred from NODE_ENV/IS_HOSTED/CF_MTLS_* — the operator
      # must opt in explicitly. See docs/operations/cloudflare-mtls-setup.md.
      AGENT_MTLS_BINDING_MODE: ${AGENT_MTLS_BINDING_MODE:-off}
      # Wave 6 security remediation rollout controls. Default-bearing form so
      # a missing value cannot make the stack refuse to start — both are
      # compatibility controls whose defaults are the safe state. See
      # docs/operations/agent-network-and-manifest-rollout.md before setting
      # either to anything other than its default in production.
      #
      # AGENT_REQUIRE_MANIFEST_SIGNING_KEY_ID: NOT a no-op and NOT fleet-wide.
      # A capable agent (this build or newer) applies a pushed `true`/`false`
      # on its next update check (re-read at updater-construction time; its
      # helper-manager needs a restart to pick up the change, same limitation
      # as backup_server_url). An agent build older than this one ignores the
      # pushed value entirely and keeps accepting ID-less manifests.
      # The key is always sent, as true or false, so reverting this variable
      # rolls capable agents back on their next heartbeat.
      AGENT_REQUIRE_MANIFEST_SIGNING_KEY_ID: ${AGENT_REQUIRE_MANIFEST_SIGNING_KEY_ID:-false}
      MANAGED_SOFTWARE_POLICY_MODE: ${MANAGED_SOFTWARE_POLICY_MODE:-compat}
      APP_ENCRYPTION_KEY: ${APP_ENCRYPTION_KEY:?Set APP_ENCRYPTION_KEY in .env}
      # Optional, but required once M365_GRAPH_ACTIONS_TOOLS_ENABLED=true below —
      # boot refuses to start without it (see that var's comment). Must be set
      # here AND in .env; compose only interpolates vars listed in this block.
      APP_ENCRYPTION_KEY_ID: ${APP_ENCRYPTION_KEY_ID:-}
      MFA_ENCRYPTION_KEY: ${MFA_ENCRYPTION_KEY:?Set MFA_ENCRYPTION_KEY in .env}
      ENROLLMENT_KEY_PEPPER: ${ENROLLMENT_KEY_PEPPER:?Set ENROLLMENT_KEY_PEPPER in .env}
      MFA_RECOVERY_CODE_PEPPER: ${MFA_RECOVERY_CODE_PEPPER:?Set MFA_RECOVERY_CODE_PEPPER in .env}
      PATCH_REPORT_STORAGE_PATH: /data/patch-reports
      LOG_LEVEL: ${LOG_LEVEL:-info}
      LOG_JSON: ${LOG_JSON:-true}
      METRICS_SCRAPE_TOKEN: ${METRICS_SCRAPE_TOKEN:-}
      # Platform-operator abuse alerts (all optional; unset = feature disabled)
      OPS_ALERT_WEBHOOK_URL: ${OPS_ALERT_WEBHOOK_URL:-}
      OPS_ALERT_EMAIL: ${OPS_ALERT_EMAIL:-}
      OPS_ALERT_LABEL: ${OPS_ALERT_LABEL:-}
      ABUSE_SIGNAL_OVERRIDES: ${ABUSE_SIGNAL_OVERRIDES:-}
      ABUSE_SCRIPT_INDICATORS: ${ABUSE_SCRIPT_INDICATORS:-}
      ABUSE_HOSTNAME_INDICATORS: ${ABUSE_HOSTNAME_INDICATORS:-}
      ABUSE_SIGNALS_ENABLED: ${ABUSE_SIGNALS_ENABLED:-}
      # Native APNs push for the iOS app (all optional; unset = push disabled).
      # All-or-none: setting ANY of these makes the four credentials required,
      # so a half-configured relay fails at boot instead of silently at first
      # send. Empty values are treated as unset.
      APNS_AUTH_KEY: ${APNS_AUTH_KEY:-}
      APNS_KEY_ID: ${APNS_KEY_ID:-}
      APNS_TEAM_ID: ${APNS_TEAM_ID:-}
      APNS_BUNDLE_ID: ${APNS_BUNDLE_ID:-}
      APNS_ENVIRONMENT: ${APNS_ENVIRONMENT:-}
      SENTRY_DSN: ${SENTRY_DSN:-}
      SENTRY_ENVIRONMENT: ${SENTRY_ENVIRONMENT:-production}
      SENTRY_RELEASE: ${SENTRY_RELEASE:-}
      SENTRY_TRACES_SAMPLE_RATE: ${SENTRY_TRACES_SAMPLE_RATE:-0}
      ENABLE_REGISTRATION: ${ENABLE_REGISTRATION:-false}
      EMAIL_PROVIDER: ${EMAIL_PROVIDER:-auto}
      RESEND_API_KEY: ${RESEND_API_KEY:-}
      EMAIL_FROM: ${EMAIL_FROM:-noreply@breeze.local}
      SMTP_HOST: ${SMTP_HOST:-}
      SMTP_PORT: ${SMTP_PORT:-587}
      SMTP_USER: ${SMTP_USER:-}
      SMTP_PASS: ${SMTP_PASS:-}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
      # Breeze AI for Office (Excel add-in). Entra app-registration client ID that
      # gates the /client-ai exchange + admin surface. Empty/unmapped = surface
      # stays dark (env.ts defaults to ''), so this must be threaded through compose
      # for self-host/droplet deploys to enable it. Same compose-interpolation gap
      # class as IS_HOSTED / RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS.
      CLIENT_AI_ENTRA_CLIENT_ID: ${CLIENT_AI_ENTRA_CLIENT_ID:-}
      # Optional customer Graph-read onboarding. The executor is intentionally
      # not part of this generic Compose stack: deploy it separately with a
      # workload identity, private ingress, and controlled HTTPS egress.
      M365_CUSTOMER_GRAPH_READ_ONBOARDING_ENABLED: ${M365_CUSTOMER_GRAPH_READ_ONBOARDING_ENABLED:-false}
      M365_CUSTOMER_GRAPH_READ_ONBOARDING_ORG_IDS: ${M365_CUSTOMER_GRAPH_READ_ONBOARDING_ORG_IDS:-}
      M365_CUSTOMER_GRAPH_READ_CLIENT_ID: ${M365_CUSTOMER_GRAPH_READ_CLIENT_ID:-}
      M365_CUSTOMER_GRAPH_READ_CALLBACK_URL: ${M365_CUSTOMER_GRAPH_READ_CALLBACK_URL:-}
      M365_CUSTOMER_GRAPH_READ_CREDENTIAL_VERSION: ${M365_CUSTOMER_GRAPH_READ_CREDENTIAL_VERSION:-}
      M365_CUSTOMER_GRAPH_READ_VAULT_REF: ${M365_CUSTOMER_GRAPH_READ_VAULT_REF:-}
      M365_GRAPH_READ_EXECUTOR_URL: ${M365_GRAPH_READ_EXECUTOR_URL:-}
      M365_GRAPH_READ_EXECUTOR_AUDIENCE: ${M365_GRAPH_READ_EXECUTOR_AUDIENCE:-m365-graph-read-executor}
      M365_GRAPH_READ_EXECUTOR_SIGNING_KID: ${M365_GRAPH_READ_EXECUTOR_SIGNING_KID:-}
      M365_GRAPH_READ_EXECUTOR_SIGNING_PRIVATE_JWK_FILE: /run/secrets/m365_graph_read_executor_signing_private_jwk
      # Optional customer Graph-actions (write) executor. Same isolation model
      # as the Graph-read executor above: intentionally not part of this
      # generic Compose stack — deploy it separately with a workload identity,
      # private ingress, and controlled HTTPS egress. Disabled by default.
      # ONBOARDING_ENABLED gates the org-facing consent card; TOOLS_ENABLED
      # (below) independently gates the AI tools/headless execution — either
      # one enabled forces full executor descriptor validation at boot, which
      # in production also requires PUBLIC_APP_URL/PUBLIC_API_URL (or
      # PUBLIC_URL) to derive the consent callback origin.
      M365_CUSTOMER_GRAPH_ACTIONS_ONBOARDING_ENABLED: ${M365_CUSTOMER_GRAPH_ACTIONS_ONBOARDING_ENABLED:-false}
      M365_CUSTOMER_GRAPH_ACTIONS_ONBOARDING_ORG_IDS: ${M365_CUSTOMER_GRAPH_ACTIONS_ONBOARDING_ORG_IDS:-}
      # Enabling this also requires APP_ENCRYPTION_KEY_ID above — boot refuses
      # to start without it, because the m365_reset_password reveal-secret
      # path seals its temp credential with AAD-bound v3 ciphertext.
      M365_GRAPH_ACTIONS_TOOLS_ENABLED: ${M365_GRAPH_ACTIONS_TOOLS_ENABLED:-false}
      M365_GRAPH_ACTIONS_TOOLS_ORG_IDS: ${M365_GRAPH_ACTIONS_TOOLS_ORG_IDS:-}
      M365_CUSTOMER_GRAPH_ACTIONS_CLIENT_ID: ${M365_CUSTOMER_GRAPH_ACTIONS_CLIENT_ID:-}
      M365_CUSTOMER_GRAPH_ACTIONS_CREDENTIAL_VERSION: ${M365_CUSTOMER_GRAPH_ACTIONS_CREDENTIAL_VERSION:-}
      M365_CUSTOMER_GRAPH_ACTIONS_VAULT_REF: ${M365_CUSTOMER_GRAPH_ACTIONS_VAULT_REF:-}
      M365_GRAPH_ACTIONS_EXECUTOR_URL: ${M365_GRAPH_ACTIONS_EXECUTOR_URL:-}
      M365_GRAPH_ACTIONS_EXECUTOR_AUDIENCE: ${M365_GRAPH_ACTIONS_EXECUTOR_AUDIENCE:-m365-graph-actions-executor}
      M365_GRAPH_ACTIONS_EXECUTOR_SIGNING_KID: ${M365_GRAPH_ACTIONS_EXECUTOR_SIGNING_KID:-}
      M365_GRAPH_ACTIONS_EXECUTOR_SIGNING_PRIVATE_JWK_FILE: /run/secrets/m365_graph_actions_executor_signing_private_jwk
      # M365 communications-delegated. Gated per USER, not per org — a delegated
      # mailbox connection is owned by one human. No vault vars here on purpose:
      # the API never touches the comms vault (the client certificate and the
      # token-cache KEK belong to the executor, which is the only identity that
      # can decrypt the cache).
      M365_COMMS_ONBOARDING_ENABLED: ${M365_COMMS_ONBOARDING_ENABLED:-false}
      M365_COMMS_ONBOARDING_USER_IDS: ${M365_COMMS_ONBOARDING_USER_IDS:-}
      M365_COMMS_TOOLS_ENABLED: ${M365_COMMS_TOOLS_ENABLED:-false}
      M365_COMMS_TOOLS_USER_IDS: ${M365_COMMS_TOOLS_USER_IDS:-}
      M365_COMMS_CLIENT_ID: ${M365_COMMS_CLIENT_ID:-}
      M365_COMMS_EXECUTOR_URL: ${M365_COMMS_EXECUTOR_URL:-}
      M365_COMMS_EXECUTOR_AUDIENCE: ${M365_COMMS_EXECUTOR_AUDIENCE:-m365-communications-executor}
      M365_COMMS_EXECUTOR_SIGNING_KID: ${M365_COMMS_EXECUTOR_SIGNING_KID:-}
      M365_COMMS_EXECUTOR_SIGNING_PRIVATE_JWK_FILE: /run/secrets/m365_comms_executor_signing_private_jwk
      APP_VERSION: ${BREEZE_VERSION:-dev}
      BREEZE_VERSION: ${BREEZE_VERSION:?Set BREEZE_VERSION in .env}
      BINARY_SOURCE: ${BINARY_SOURCE:-github}
      RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS: ${RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS:-}
      # BYO signing: override the GitHub repository that releases are pulled
      # from (default lanternops/breeze). Pair with
      # RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS set to YOUR release manifest key.
      BINARY_GITHUB_REPOSITORY: ${BINARY_GITHUB_REPOSITORY:-}
      # Binary edition served by this deployment: self-host (default,
      # unchanged behavior) or hosted (production requires
      # BINARY_SOURCE=local + a manifest trust root — see .env.example).
      BINARY_EDITION: ${BINARY_EDITION:-self-host}
      # Hosted SaaS gate. Compose defaults to false so self-hosters upgrade
      # without touching their .env. Hosted operators must set IS_HOSTED=true
      # in .env so this interpolates to true. The API config validator (#570)
      # refuses to start in production if the container env value is missing
      # or non-boolean, so a hand-edited compose that drops this line still
      # fails loud rather than silently bypassing the email-verification gate.
      IS_HOSTED: ${IS_HOSTED:-false}
      AGENT_BINARY_DIR: /data/binaries/agent
      VIEWER_BINARY_DIR: /data/binaries/viewer
      HELPER_BINARY_DIR: /data/binaries/helper
      BINARY_VERSION_FILE: /data/binaries/VERSION
      S3_ENDPOINT: ${S3_ENDPOINT:-}
      S3_ACCESS_KEY: ${S3_ACCESS_KEY:-}
      S3_SECRET_KEY: ${S3_SECRET_KEY:-}
      S3_BUCKET: ${S3_BUCKET:-}
      S3_REGION: ${S3_REGION:-}
      S3_PRESIGN_TTL: ${S3_PRESIGN_TTL:-900}
      TURN_HOST: ${TURN_HOST:-}
      TURN_PORT: ${TURN_PORT:-3478}
      TURN_SECRET: ${TURN_SECRET:-}
      TURN_CREDENTIAL_TTL_SECONDS: ${TURN_CREDENTIAL_TTL_SECONDS:-600}
      E2E_MODE: ${E2E_MODE:-}
      # Built-in extensions ship inside the API image but load only when the
      # deployment switches them on (default off). Workspace additionally needs
      # a pgvector-capable Postgres — see POSTGRES_IMAGE_REF in .env.example.
      BREEZE_WORKSPACE_ENABLED: ${BREEZE_WORKSPACE_ENABLED:-false}
      # MCP OAuth (off by default, opt-in via env)
      MCP_OAUTH_ENABLED: ${MCP_OAUTH_ENABLED:-false}
      OAUTH_ISSUER: ${OAUTH_ISSUER:-}
      OAUTH_RESOURCE_URL: ${OAUTH_RESOURCE_URL:-}
      OAUTH_AUTH_EPOCH_ENFORCE_AFTER: ${OAUTH_AUTH_EPOCH_ENFORCE_AFTER:-}
      EVENT_PERMISSION_EPOCH_MODE: ${EVENT_PERMISSION_EPOCH_MODE:?Set EVENT_PERMISSION_EPOCH_MODE to compat or enforce}
      OAUTH_COOKIE_SECRET: ${OAUTH_COOKIE_SECRET:-}
      OAUTH_JWKS_PRIVATE_JWK: ${OAUTH_JWKS_PRIVATE_JWK:-}
      OAUTH_JWKS_PUBLIC_JWK: ${OAUTH_JWKS_PUBLIC_JWK:-}
      OAUTH_CONSENT_URL_BASE: ${OAUTH_CONSENT_URL_BASE:-}
      # --- Additional API runtime settings ---------------------------------
      # These are documented in .env.example and read by the API, but were not
      # previously threaded through Compose, so setting them in .env did nothing
      # (the #570 / IS_HOSTED gap class). Every value uses `${VAR:-}`: an empty
      # string is falsy to the API's envFlag/envInt helpers, which then fall
      # back to their in-code default — so mapping them here is non-regressive
      # (unset behaves exactly as before) and never drifts from the code default.
      # Parity between .env.example and this block is enforced by
      # apps/api/src/config/envComposeParity.test.ts.
      # Auth / security / session
      ENABLE_2FA: ${ENABLE_2FA:-}
      BREEZE_PLATFORM_ADMINS: ${BREEZE_PLATFORM_ADMINS:-}
      SESSION_SECRET: ${SESSION_SECRET:-}
      IP_ALLOWLIST_ENFORCEMENT_MODE: ${IP_ALLOWLIST_ENFORCEMENT_MODE:-}
      JWT_SIGNING_KEYRING: ${JWT_SIGNING_KEYRING:-}
      JWT_ACTIVE_KID: ${JWT_ACTIVE_KID:-}
      WS_TICKET_BIND_IP: ${WS_TICKET_BIND_IP:-}
      ENROLLMENT_KEY_DEFAULT_TTL_MINUTES: ${ENROLLMENT_KEY_DEFAULT_TTL_MINUTES:-}
      # Real defaults, not `:-}` — an unset var rendered as `VAR: ""` reaches the
      # container SET to an empty string, and any reader doing
      # `Number(process.env.X ?? default)` then gets 0 (`??` skips '', and
      # Number('') is 0). The readers all use utils/envInt now, which treats ''
      # as absent; these baked defaults are the second line of defence (#2776).
      CHILD_ENROLLMENT_KEY_TTL_MINUTES: ${CHILD_ENROLLMENT_KEY_TTL_MINUTES:-1440}
      INSTALLER_BOOTSTRAP_TOKEN_TTL_MINUTES: ${INSTALLER_BOOTSTRAP_TOKEN_TTL_MINUTES:-1440}
      INSTALLER_PARENT_MIN_REMAINING_SECONDS: ${INSTALLER_PARENT_MIN_REMAINING_SECONDS:-60}
      ENROLLMENT_KEY_CLEANUP_ENABLED: ${ENROLLMENT_KEY_CLEANUP_ENABLED:-true}
      ENROLLMENT_KEY_PURGE_AFTER_DAYS: ${ENROLLMENT_KEY_PURGE_AFTER_DAYS:-7}
      AUTOMATION_WEBHOOK_ALLOW_LEGACY_SECRET: ${AUTOMATION_WEBHOOK_ALLOW_LEGACY_SECRET:-}
      # Email — SMTP extras + Mailgun provider
      SMTP_FROM: ${SMTP_FROM:-}
      SMTP_SECURE: ${SMTP_SECURE:-}
      MAILGUN_API_KEY: ${MAILGUN_API_KEY:-}
      MAILGUN_DOMAIN: ${MAILGUN_DOMAIN:-}
      MAILGUN_FROM: ${MAILGUN_FROM:-}
      MAILGUN_BASE_URL: ${MAILGUN_BASE_URL:-}
      # SMS MFA + alert notifications (Twilio)
      TWILIO_ACCOUNT_SID: ${TWILIO_ACCOUNT_SID:-}
      TWILIO_AUTH_TOKEN: ${TWILIO_AUTH_TOKEN:-}
      TWILIO_VERIFY_SERVICE_SID: ${TWILIO_VERIFY_SERVICE_SID:-}
      TWILIO_MESSAGING_SERVICE_SID: ${TWILIO_MESSAGING_SERVICE_SID:-}
      TWILIO_PHONE_NUMBER: ${TWILIO_PHONE_NUMBER:-}
      # MCP OAuth Dynamic Client Registration
      OAUTH_DCR_ENABLED: ${OAUTH_DCR_ENABLED:-}
      OAUTH_DCR_REQUIRE_IAT: ${OAUTH_DCR_REQUIRE_IAT:-}
      OAUTH_DCR_ALLOW_ANONYMOUS: ${OAUTH_DCR_ALLOW_ANONYMOUS:-}
      # M365 ticket mailbox + C2C backup app + Graph-read AI tools
      TICKET_MAILBOX_M365_CLIENT_ID: ${TICKET_MAILBOX_M365_CLIENT_ID:-}
      TICKET_MAILBOX_M365_CLIENT_SECRET: ${TICKET_MAILBOX_M365_CLIENT_SECRET:-}
      C2C_M365_CLIENT_ID: ${C2C_M365_CLIENT_ID:-}
      C2C_M365_CLIENT_SECRET: ${C2C_M365_CLIENT_SECRET:-}
      M365_GRAPH_READ_TOOLS_ENABLED: ${M365_GRAPH_READ_TOOLS_ENABLED:-}
      M365_GRAPH_READ_TOOLS_ORG_IDS: ${M365_GRAPH_READ_TOOLS_ORG_IDS:-}
      # Cloudflare mTLS (API Shield client certificates)
      CLOUDFLARE_API_TOKEN: ${CLOUDFLARE_API_TOKEN:-}
      CLOUDFLARE_ZONE_ID: ${CLOUDFLARE_ZONE_ID:-}
      # Remote-session concurrency caps
      MAX_ACTIVE_REMOTE_SESSIONS_PER_ORG: ${MAX_ACTIVE_REMOTE_SESSIONS_PER_ORG:-}
      MAX_ACTIVE_REMOTE_SESSIONS_PER_USER: ${MAX_ACTIVE_REMOTE_SESSIONS_PER_USER:-}
      # Metrics label controls
      METRICS_INCLUDE_ORG_ID: ${METRICS_INCLUDE_ORG_ID:-}
      METRICS_SCRAPE_IP_ALLOWLIST: ${METRICS_SCRAPE_IP_ALLOWLIST:-}
      # Hosted billing redirect
      BILLING_URL: ${BILLING_URL:-}
      # --- Optional knobs documented as COMMENTED-OUT defaults ---------------
      # Everything below is documented in .env.example the way this repo
      # documents an optional tuning knob: commented out, showing its default.
      # The parity guard used to read only UNCOMMENTED assignments, so this
      # entire class was exempt from it and quietly never reached a container
      # (#3239; #3236 was one instance of the same shape). All are `${VAR:-}`
      # for the reason spelled out above — '' reads as absent to envStr /
      # envFlag / envInt, so an unset knob still gets its in-code default.
      # Auth cookie + CORS hardening. AUTH_/PORTAL_-prefixed names override the
      # generic COOKIE_* pair; that precedence is resolved with envStr (NOT `??`)
      # precisely because '' must fall through rather than shadow — see
      # resolveAuthCookieSameSite() in routes/auth/helpers.ts.
      COOKIE_SAME_SITE: ${COOKIE_SAME_SITE:-}
      COOKIE_FORCE_SECURE: ${COOKIE_FORCE_SECURE:-}
      AUTH_COOKIE_SAME_SITE: ${AUTH_COOKIE_SAME_SITE:-}
      AUTH_COOKIE_FORCE_SECURE: ${AUTH_COOKIE_FORCE_SECURE:-}
      PORTAL_COOKIE_SAME_SITE: ${PORTAL_COOKIE_SAME_SITE:-}
      PORTAL_COOKIE_FORCE_SECURE: ${PORTAL_COOKIE_FORCE_SECURE:-}
      CORS_INCLUDE_DEFAULT_ORIGINS: ${CORS_INCLUDE_DEFAULT_ORIGINS:-}
      REFRESH_ROTATION_GRACE_SECONDS: ${REFRESH_ROTATION_GRACE_SECONDS:-}
      # Customer-portal session store
      PORTAL_STATE_BACKEND: ${PORTAL_STATE_BACKEND:-}
      # MCP server rate limits + execute-tool gating
      MCP_REQUIRE_EXECUTE_ADMIN: ${MCP_REQUIRE_EXECUTE_ADMIN:-}
      MCP_EXECUTE_TOOL_ALLOWLIST: ${MCP_EXECUTE_TOOL_ALLOWLIST:-}
      MCP_SSE_RATE_LIMIT_PER_MINUTE: ${MCP_SSE_RATE_LIMIT_PER_MINUTE:-}
      MCP_MESSAGE_RATE_LIMIT_PER_MINUTE: ${MCP_MESSAGE_RATE_LIMIT_PER_MINUTE:-}
      MCP_MAX_SSE_SESSIONS_PER_KEY: ${MCP_MAX_SSE_SESSIONS_PER_KEY:-}
      # AI provider overrides (ANTHROPIC_API_KEY is mapped further up)
      ANTHROPIC_MODEL: ${ANTHROPIC_MODEL:-}
      ANTHROPIC_BASE_URL: ${ANTHROPIC_BASE_URL:-}
      ANTHROPIC_AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN:-}
      # External billing service (hosted only; empty on self-host)
      BREEZE_BILLING_URL: ${BREEZE_BILLING_URL:-}
      BREEZE_BILLING_API_KEY: ${BREEZE_BILLING_API_KEY:-}
      BILLING_SERVICE_URL: ${BILLING_SERVICE_URL:-}
      BILLING_SERVICE_API_KEY: ${BILLING_SERVICE_API_KEY:-}
      # Startup + agent-fleet behaviour
      AUTO_MIGRATE: ${AUTO_MIGRATE:-}
      AGENT_AUTO_PROMOTE: ${AGENT_AUTO_PROMOTE:-}
      ENABLE_API_DOCS_UI: ${ENABLE_API_DOCS_UI:-}
      PUBLIC_ACTIVATION_BASE_URL: ${PUBLIC_ACTIVATION_BASE_URL:-}
    volumes:
      - api_data:/data
      - binaries:/data/binaries:ro
    secrets:
      - redis_password
      - source: m365_graph_read_executor_signing_private_jwk
        target: m365_graph_read_executor_signing_private_jwk
      - source: m365_graph_actions_executor_signing_private_jwk
        target: m365_graph_actions_executor_signing_private_jwk
      - source: m365_comms_executor_signing_private_jwk
        target: m365_comms_executor_signing_private_jwk
    depends_on:
      binaries-init:
        condition: service_completed_successfully
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      <<: *healthcheck
      test: ['CMD', 'wget', '--no-verbose', '--tries=1', '--spider', 'http://127.0.0.1:3001/health']
      start_period: 40s
    networks:
      - breeze

  web:
    image: ${BREEZE_WEB_IMAGE_REF:?Set BREEZE_WEB_IMAGE_REF to a digest-pinned image ref}
    platform: ${DOCKER_PLATFORM:-linux/amd64}
    container_name: breeze-web
    restart: unless-stopped
    environment:
      NODE_ENV: production
      HOST: 0.0.0.0
      PORT: 4321
      PUBLIC_API_URL: ${PUBLIC_API_URL:-}
      PUBLIC_SENTRY_DSN_WEB: ${PUBLIC_SENTRY_DSN_WEB:-}
      SENTRY_ENVIRONMENT: ${SENTRY_ENVIRONMENT:-production}
      SENTRY_RELEASE: ${SENTRY_RELEASE:-}
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      <<: *healthcheck
      test: ['CMD', 'wget', '--no-verbose', '--tries=1', '--spider', 'http://127.0.0.1:4321/']
      start_period: 30s
    networks:
      - breeze

  # Customer portal (Astro SSR). Served under /portal on the main domain via the
  # Caddy carve-out — calls the API same-origin (/api/v1/...), so PUBLIC_API_URL
  # stays empty. PORTAL_BASE_PATH is baked at build time; keep it in sync with
  # the Caddyfile carve-out and the image build-arg.
  portal:
    image: ${BREEZE_PORTAL_IMAGE_REF:?Set BREEZE_PORTAL_IMAGE_REF to a digest-pinned image ref}
    platform: ${DOCKER_PLATFORM:-linux/amd64}
    container_name: breeze-portal
    restart: unless-stopped
    environment:
      NODE_ENV: production
      HOST: 0.0.0.0
      PORT: 4322
      PORTAL_BASE_PATH: ${PORTAL_BASE_PATH:-/portal}
      # Browser calls the API same-origin via the /api/* Caddy route, so the
      # public (client) base stays empty. Server-side rendering has no window to
      # derive same-origin from, so it reaches the API over the internal network.
      PUBLIC_API_URL: ${PUBLIC_API_URL:-}
      INTERNAL_API_URL: ${INTERNAL_API_URL:-http://api:3001}
      PUBLIC_SENTRY_DSN_WEB: ${PUBLIC_SENTRY_DSN_WEB:-}
      SENTRY_ENVIRONMENT: ${SENTRY_ENVIRONMENT:-production}
      SENTRY_RELEASE: ${SENTRY_RELEASE:-}
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      <<: *healthcheck
      test: ['CMD-SHELL', 'wget --no-verbose --tries=1 --spider "http://127.0.0.1:4322${PORTAL_BASE_PATH:-/portal}/login"']
      start_period: 30s
    networks:
      - breeze

  postgres:
    image: ${POSTGRES_IMAGE_REF:?Set POSTGRES_IMAGE_REF to a digest-pinned Postgres image ref}
    container_name: breeze-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-breeze}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: ${POSTGRES_DB:-breeze}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      <<: *healthcheck
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-breeze} -d ${POSTGRES_DB:-breeze}']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s
    networks:
      - breeze

  redis:
    image: ${REDIS_IMAGE_REF:?Set REDIS_IMAGE_REF to a digest-pinned Redis image ref}
    container_name: breeze-redis
    restart: unless-stopped
    command: >
      sh -ec 'password="$$(cat /run/secrets/redis_password)";
      if [ -z "$$password" ] || [ "$$password" = "__GENERATE_ME__" ]; then
        echo "[redis] REDIS_PASSWORD is empty or the __GENERATE_ME__ placeholder. Set REDIS_PASSWORD in .env to a strong value (openssl rand -hex 32)." >&2;
        exit 1;
      fi;
      umask 077;
      printf "%s\n" "appendonly yes" "maxmemory ${REDIS_MAXMEMORY:-256mb}" "maxmemory-policy noeviction" "maxclients 10000" "requirepass $$password" > /tmp/redis.conf;
      exec redis-server /tmp/redis.conf'
    secrets:
      - redis_password
    volumes:
      - redis_data:/data
    healthcheck:
      <<: *healthcheck
      test:
        [
          'CMD-SHELL',
          'password="$$(cat /run/secrets/redis_password)"; { printf "AUTH %s\r\n" "$$password"; printf "PING\r\n"; } | redis-cli --no-auth-warning | grep -q PONG',
        ]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 5s
    networks:
      - breeze

  # TURN relay for WebRTC remote desktop. Opt-in via: docker compose --profile turn up -d
  # Or set COMPOSE_PROFILES=turn in .env. Requires TURN_HOST and TURN_SECRET.
  # Open UDP 49152-65535 in your firewall for relay traffic.
  coturn:
    image: ${COTURN_IMAGE_REF:?Set COTURN_IMAGE_REF to a digest-pinned coturn image ref}
    container_name: breeze-coturn
    restart: unless-stopped
    profiles:
      - turn
    network_mode: host
    command: >
      turnserver
      --listening-port=3478
      --tls-listening-port=5349
      --fingerprint
      --use-auth-secret
      --relay-threads=4
      --user-quota=4
      --total-quota=1000
      --max-bps=${TURN_MAX_BPS:-5000000}
      --no-multicast-peers
      --denied-peer-ip=0.0.0.0-0.255.255.255
      --denied-peer-ip=10.0.0.0-10.255.255.255
      --denied-peer-ip=100.64.0.0-100.127.255.255
      --denied-peer-ip=127.0.0.0-127.255.255.255
      --denied-peer-ip=169.254.0.0-169.254.255.255
      --denied-peer-ip=172.16.0.0-172.31.255.255
      --denied-peer-ip=192.0.0.0-192.0.0.255
      --denied-peer-ip=192.168.0.0-192.168.255.255
      --denied-peer-ip=198.18.0.0-198.19.255.255
      --denied-peer-ip=224.0.0.0-239.255.255.255
      --denied-peer-ip=240.0.0.0-255.255.255.255
      --denied-peer-ip=::1
      --denied-peer-ip=fc00::-fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
      --denied-peer-ip=fe80::-febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff
      --denied-peer-ip=ff00::-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
      --log-file=stdout
      --verbose
      --min-port=49152
      --max-port=65535
      --no-cli
      --static-auth-secret=${TURN_SECRET:?TURN_SECRET must be set (openssl rand -hex 32) when the turn profile is enabled}
      --realm=${TURN_REALM:-breeze.local}
      --external-ip=${TURN_HOST:-}

networks:
  # Fixed subnet so Caddy gets a stable, known peer address (see caddy service
  # above). The default is deliberately distinct from
  # deploy/docker-compose.prod.yml's 172.30.0.0/24 so the two stacks never
  # collide if ever run on the same Docker host. Both defaults sit inside
  # Docker's default bridge pool (172.17.0.0/12), so a host that has already
  # auto-allocated this range needs BREEZE_DOCKER_SUBNET set to something
  # outside it — set BREEZE_CADDY_IP to a matching address when you do.
  breeze:
    name: breeze
    ipam:
      config:
        - subnet: ${BREEZE_DOCKER_SUBNET:-172.31.0.0/24}

volumes:
  binaries:
  caddy_data:
  caddy_config:
  api_data:
  postgres_data:
  redis_data:

secrets:
  redis_password:
    environment: REDIS_PASSWORD
  # Standalone Compose bind-mounts file-backed secrets and ignores uid/gid/mode
  # target attributes. /dev/null keeps dark deployments optional; when enabled,
  # the source JWK must already have numeric owner 1001:1001 and mode 0400.
  m365_graph_read_executor_signing_private_jwk:
    file: ${M365_GRAPH_READ_EXECUTOR_SIGNING_PRIVATE_JWK_SOURCE_FILE:-/dev/null}
  m365_graph_actions_executor_signing_private_jwk:
    file: ${M365_GRAPH_ACTIONS_EXECUTOR_SIGNING_PRIVATE_JWK_SOURCE_FILE:-/dev/null}
  m365_comms_executor_signing_private_jwk:
    file: ${M365_COMMS_EXECUTOR_SIGNING_PRIVATE_JWK_SOURCE_FILE:-/dev/null}