Skip to content

docs(ansible): achieve read-once-and-deploy documentation standard

Jérôme Revillard requested to merge docs/issue-823 into main

Closes #823 (closed)

Changes

deploy/ansible/README.md (+97/-21):

  • Vault secrets: Add kc_mobile_client_id, kc_mobile_redirect_scheme, vllm_api_key. Remove unused session_secret. Add Required column with conditional values (always/GPU node/remote GPU/observability)
  • Environment variables: Document missing configurable vars (translation_cache, kong_trusted_ips, opea_streaming, chatqna_stream_timeout, grafana_alert_webhook_url, grafana_alert_email)
  • Keycloak: Add Realm Behavior sub-table with 14 optional configuration variables (registration, brute-force, theme, i18n, etc.)
  • Troubleshooting: Add 5 common first-run errors (swarm_registry_url undefined, image_tag undefined, nginx_permissions_policy undefined, Permission denied publickey, kc_mobile_client_id missing)

docs/architecture.md (+2):

  • Add cross-references to deploy/ansible/README.md and configs/otel/README.md

Verification

  • All documented variables verified against deploy/ansible/templates/env.j2, deploy/ansible/group_vars/all.yml, and deploy/ansible/deploy.yml
  • Defaults cross-checked against codebase (e.g. chatqna_stream_timeout in ms, not seconds)
  • Only configurable variables documented (e.g. grafana_port excluded — host port mapping commented out)

Merge request reports