Skip to content

Documentation / Guides / Documentation service

Build and run the documentation service

The documentation site is a static MkDocs Material build served by an unprivileged nginx process. The runtime contains only generated site files and the nginx configuration; it does not contain the repository, tests, evidence, or build tooling.

Build locally

Use the explicitly pinned documentation dependencies:

python -m venv .venv-docs
. .venv-docs/bin/activate
python -m pip install -r requirements-docs.txt
python -m mkdocs build --strict
python -m unittest tests.test_docs_site

mkdocs build --strict fails on build warnings. The site test additionally checks that every Markdown page is emitted and every generated internal link and anchor resolves.

Run the production image

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

The container defaults to port 8080 and expands Cloud Run's PORT environment variable when nginx starts. /health returns plain-text ok. HTML asks clients to revalidate, while versioned static assets receive a one-year immutable cache policy.

Deploy to Cloud Run

After authenticating gcloud and selecting an authorized build identity, review the source and deploy it explicitly:

gcloud run deploy vaani-docs \
  --source . \
  --project birla-loyalty-voice-bot \
  --region asia-south1 \
  --allow-unauthenticated \
  --port 8080 \
  --min 0 \
  --max 10

This recommendation creates a public, scale-to-zero service. Adjust the maximum instance count only after reviewing traffic and project quotas. Deployment is an operator action; building or reading these docs does not create cloud resources.

Update the site

  1. Edit Markdown under docs/.
  2. Add every new page to nav in mkdocs.yml.
  3. Keep VAANI's private tested release at 1.0.0rc9 until new evidence approves a replacement.
  4. Keep the companion starter pinned to the privately published create-vaani-app==0.1.2; version 0.1.3 is still in progress.
  5. Run the strict build, site tests, existing docs checker, image build, and HTTP smoke before deployment.

No runtime secrets are required. Private package-index credentials are needed only by users installing the companion CLI; they do not belong in this image or Cloud Run service.