Skip to content

ADR-0017: Public documentation pipeline — CanEast sanitization via ADO CI/CD

Status

Accepted — 2026-04-03

Context

archon-docs contains internal documentation with real hostnames (caneast-c1-node2, caneast-c1-node3), IP addresses (192.168.2.x), ports, and credential paths. The platform needs a public-facing version on peries.ca for portfolio purposes without exposing internal infrastructure details.

ADR-0008 established the CanEast naming convention. ADR-0015 moved internal docs to ADO Wiki. This ADR defines how sanitized public docs are built and deployed automatically.

Decision

An ADO CI/CD pipeline on archon-docs triggers on push to main, sanitizes content via sanitize.py, builds with MkDocs Material, versions with mike, and deploys to Cloudflare Pages.

Pipeline stages

push to archon-docs main
  → ADO pipeline triggers
  → sanitize.py strips IPs/hostnames → CanEast naming
  → mkdocs build (public mkdocs.yml, no internal references)
  → mike deploy {version} latest
  → deploy static site to Cloudflare Pages (peries.ca)

Stage 1 — Sanitize

sanitize.py reads all markdown files and applies CanEast substitutions before build:

Internal Public (CanEast)
caneast-c1-node2, caneast-c1-node3 compute-node-01, compute-node-02
caneast-c1-node1 vpn-node-01
caneast-c1-mqtt1 mqtt-broker-01
caneast-c1-ot1-esp1 ot-sensor-01
caneast-c1-fw1 firewall-01
caneast-c1-jmp1 jumpbox-01
192.168.2.x 10.x.x.0/24 (network/mask only)
10.10.10.x, 10.10.20.x, 10.10.30.x 10.x.x.0/24 (preserved as-is — already generic)
Real port numbers Functional descriptions or omitted
caneast/prod/telegram/bot-token secrets/prod/alerting/bot-token
REDACTED REDACTED
dev.azure.com/caneast-platform dev.azure.com/caneast-platform
CAE prefix in naming CanEast prefix

The script operates on a copy in a _build/ staging directory — the source docs/ directory is never modified.

Stage 2 — Build

MkDocs Material builds the sanitized copy into static HTML. A separate mkdocs-public.yml configures the public site: - site_url: https://peries.ca - Theme: Material default (no custom palette) - Plugins: search, mike - No internal-only pages (e.g., _index.md excluded from nav)

Stage 3 — Version

mike manages version snapshots on a gh-pages-public branch, mirroring the internal version history but with sanitized content.

Stage 4 — Deploy

Cloudflare Pages deployment via Wrangler CLI or Cloudflare Pages Git integration: - DNS managed by Terraform in archon-cloud (Cloudflare provider) - Deployment triggered by pipeline on successful build - CrowdSec bouncer active on Cloudflare (already running per _index.md)

Rationale

  • Single source of truth — internal docs in archon-docs, public layer is a derivative
  • Automated sanitization eliminates manual error — no risk of leaking internal IPs or hostnames
  • ADO pipeline ensures every push to main produces a fresh public build
  • Cloudflare Pages provides free static hosting with global CDN, no server to maintain
  • MkDocs Material for public site only — internal docs use ADO Wiki (no build step needed internally)

Alternatives considered

  • Manual sanitization: rejected — error-prone, does not scale, will be forgotten
  • Separate public repo: rejected — content drift between internal and public copies
  • ADO Wiki for public: rejected — requires ADO authentication, not suitable for anonymous portfolio access
  • GitHub Pages: viable, but Cloudflare Pages provides better CDN integration and the platform already uses Cloudflare for CrowdSec bouncer

Consequences

  • sanitize.py must be maintained as internal naming evolves — new hostnames/IPs require new substitution rules
  • mkdocs-public.yml is a separate config from the removed internal mkdocs.yml — it only exists in the pipeline, not for local serving
  • Public site lags internal docs by one pipeline run (push-to-deploy latency)
  • Terraform in archon-cloud must manage Cloudflare DNS for peries.ca before this pipeline can deploy
  • Pipeline requires Cloudflare API token stored in Infisical at caneast/prod/cloudflare/api-token

References

  • ADR-0008: CanEast naming convention
  • ADR-0015: Internal documentation platform (ADO Wiki)