navidocs

A static documentation host for the navicore homelab. CI/CD jobs post a built site bundle and a slug; navidocs serves it at https://docs.navicore.tech/<slug>.

It hosts the output of any static site generator (mdbook, Hugo, mkdocs, Docusaurus, Zola, plain HTML) — the upload is just a gzipped tar of a directory of files. The generator only needs its base path set to /<slug>/.

See docs/ARCHITECTURE.md for the full design and docs/design/client-credentials-auth.md for the CI auth contract with anz.

API

Method	Path	Auth	Description
GET	/	none	Index of published slugs.
GET	/api/health	none	Liveness/readiness probe.
GET	/{slug}/...	none	Static site content.
POST	/api/sites/{slug}	Bearer JWT	Publish a gzipped-tar site bundle.

Publishing requires a short-lived JWT from anz (client_credentials grant, scope=docs:publish). navidocs verifies it offline against anz's JWKS, then checks its own client_id → slug policy.

Run locally

export NAVIDOCS_OIDC_ISSUER=https://auth.navicore.tech/realms/homelab
export NAVIDOCS_OIDC_AUDIENCE=https://docs.navicore.tech
export NAVIDOCS_DATA_DIR=./sites
export NAVIDOCS_POLICY_FILE=./config/policy.example.toml
cargo run

Development

The justfile is the single source of truth for build/test/lint — CI runs the exact same recipes, so local and CI cannot drift. Before pushing:

just ci    # fmt-check + clippy (warnings = errors) + tests + release build

Other recipes: just fmt (format), just test, just build, just install (binary onto PATH), just stats (LOC/module report), just clean. The toolchain is pinned in rust-toolchain.toml and matched by every .forgejo/workflows/*.yml — keep the two in sync.

CI runs on push/PR to main (.forgejo/workflows/ci.yml); tagging v* builds and pushes the deployment image (.forgejo/workflows/release.yml).

Publishing docs from CI

See docs/examples/forgejo-docs-workflow.yml for a drop-in Forgejo Actions workflow that publishes a site to navidocs.

Configuration

All configuration is via environment variables — see the table in docs/ARCHITECTURE.md.