Build and verify the documentation service

This maintainer runbook covers the static MkDocs Material site and its unprivileged nginx container. It does not deploy anything by itself.

Build and test

From a VAANI source checkout:

uv run --no-project --with-editable . --with-requirements requirements-docs.txt \
  python -m mkdocs build --strict
uv run --no-project --with-editable . --with-requirements requirements-docs.txt \
  python scripts/check_docs.py
uv run --no-project --with-editable . --with-requirements requirements-docs.txt \
  python -m unittest tests.test_docs_site tests.test_docs

The tests check navigation, links, release freshness, theme controls, rendered Mermaid containers, and documentation-service response headers.

Verify the local container

docker build -t vaani-docs:local .
docker run --rm -p 8080:8080 -e PORT=8080 vaani-docs:local
python scripts/smoke_docs_service.py \
  --base-url http://127.0.0.1:8080 \
  --expected-release-state published_private

/health returns ok. HTML revalidates; static assets use a one-year immutable cache. The smoke also verifies that repository source and tests are not served.

Deployment boundary

The verified public entry point is docs.vaani.indieverse.studio. It is served by operator-owned Firebase Hosting as a static copy of the built site. The Cloud Run docs service is a separate deployment of the same content; updating Cloud Run does not update the custom domain. This repository contains the shared MkDocs and Cloud Run source, but no persistent Firebase project configuration or deploy workflow. Do not claim that a source build changed either deployment.

An authorized operator may use gcloud run deploy --source . with the reviewed project, region, service, IAM, scaling, and rollback settings. Those values are environment policy, so this repository does not provide a copy-paste public deployment command.

After an approved release, deploy the same strict MkDocs build to Firebase Hosting as well. Smoke the Cloud Run service URL, the Firebase default URL, and the custom domain separately. The custom-domain smoke must show the current runtime and Starter versions; otherwise Firebase is still serving an older static release. Record the Cloud Run revision and image digest plus the Firebase release in the operator's deployment evidence.

Release updates

Update release-status.json and its rendered status page together. Then run the strict build, docs checker, tests, local image smoke, and—only after an approved deployment—the remote smoke.