service:
  name: kb-site
  owner_node: piha
  role: static-html-host        # public slice of the KB, rendered by scripts/kb/gen_pages.py
  exposure: public              # public via npm@PIHA (kb-e2a24af3.okit.pl). The container itself binds
                                # 8250 on the LAN; npm is the sole public entry point.
  dependencies: []              # nginx serving a local volume — nothing else required at runtime
  ports:
    - container: 80
      host: 8250
      protocol: tcp
  healthcheck:
    type: http
    endpoint: http://127.0.0.1:8250/index.html   # content must be loaded first (see runbook)
    interval: 30s
    timeout: 10s
    retries: 5
  restart_policy: unless-stopped
  persistence:
    # Docker named volume kb-site_kb-site_content (compose project prefix), NOT a
    # bind under /opt/homelab/data. The content is a pure artifact: regenerate it
    # from the repo with scripts/kb/gen_pages.py, no backup job needed.
    paths:
      - kb-site_kb-site_content
  runtime:
    # The CONTAINER has no .env and no secrets — the port bind is static. The
    # access token below is not a container env var: it is consumed by the
    # generator on the node that builds the site, never by nginx on PIHA.
    config_files: []
    env_vars: []
  content:
    # Only kb/ documents with `visibility: public` are published; the generator
    # is fail-closed (no frontmatter / no visibility field = private).
    generator: scripts/kb/gen_pages.py
    leak_check: scripts/kb/gen_pages.py --check   # must pass before publishing
    source: kb/**/*.md
    # NPM enforces a ?key=<token> gate in front of this site, so every internal
    # href must carry that token or a click lands on 403. The generator reads it
    # from ACCESS_TOKEN; the value lives in the NPM database and in
    # /opt/homelab/config/kb-site/.env ON THE GENERATING NODE (saturn/solaria) —
    # never in this repository. Omitting it yields a valid preview build that
    # must not be published. See kb/runbooks/kb-site-deploy.md.
    access_token_env: ACCESS_TOKEN
    access_token_file: /opt/homelab/config/kb-site/.env   # generating node, not piha