Docs hosting
The documentation site is built as a static HTML/CSS/JS bundle and served from Azure Container Instances next to the API. Mintlify Cloud is not required. Official Mintlify self-host / static-export APIs are Enterprise-only; this project uses the community staticmint exporter against a pinned mint CLI version.
Build pipeline
On main, after the API image build:
1. Generate docs/api-reference/openapi.json from Service.dll with Swashbuckle CLI. 2. Run scripts/Build-DocsStatic.sh (mint + staticmint) to produce docs/out. 3. Build Dockerfile.docs (nginx) and push gals-docs to ACR. 4. Update ACI group aci-gals-docs-dev with scripts/Update-AciImage.sh. 5. Smoke-check that the public docs URL returns the oauth2-proxy auth redirect.
ACI layout
Provision the container group in gals.infrastructure.terraform (not in this repository). An illustrative multi-container shape is checked in as oauth2-proxy.aci.example.yaml for Terraform authors.
Expected layout:
| Container | Image | Role |
|---|---|---|
gals-docs-proxy | quay.io/oauth2-proxy/oauth2-proxy | Public entrypoint; Entra ID OIDC; proxies to nginx |
gals-docs | acrgalsdevc98f.azurecr.io/gals-docs:<tag> | Serves the static export on an internal port |
Suggested oauth2-proxy flags (values come from Key Vault / Terraform):
<pre><code class="language-text">--provider=oidc --oidc-issuer-url=https://login.microsoftonline.com/<tenant-id>/v2.0 --client-id=<docs-app-client-id> --client-secret=<from-key-vault> --cookie-secret=<from-key-vault> --email-domain=<mca-email-domain> --upstream=http://127.0.0.1:8080 --http-address=0.0.0.0:4180 --redirect-url=https://<docs-fqdn>/oauth2/callback --cookie-secure=true --cookie-httponly=true
TLS termination should follow the same pattern used for the API ACI (Caddy sidecar on PTL DEV, or Cloudflare on MITA DEV).
Entra ID app registration checklist
Create a dedicated docs app registration (separate from the API and portal SPA):
1. Platform: Web — redirect URI https://<docs-fqdn>/oauth2/callback. 2. Enable ID tokens for the oauth2-proxy OIDC flow. 3. Restrict access to the MCA tenant / security group used by internal staff. 4. Store client-secret and a random cookie-secret in Key Vault; inject them as ACI secure environment variables. 5. Do not reuse the API audience — docs auth only gates reading the static site.
Static export limitations
| Feature | Behaviour in ACI static bundle |
|---|---|
| Full-text search | Search POSTs to /api/search and needs a backend; not available in the static export |
OpenAPI .md download links | Return 404 (no MDX source for generated pages) |
| Guide pages use Print this page; API pages use browser print + shared print CSS |
If search or first-party static export becomes a hard requirement, evaluate Mintlify Enterprise self-host / static-export API.
Terraform prerequisites
Before the Docs pipeline stage can succeed:
- - ACR repository / push rights for
gals-docs - - ACI group
aci-gals-docs-devwith both containers defined - - DNS / TLS for the docs FQDN
- - Key Vault secrets for oauth2-proxy
- - Entra app registration as above
Update-AciImage.sh fails fast if the container group does not exist — apply Terraform first, then re-run the pipeline.