Gå til indholdet

Docs-portal & hosting (MkDocs + Cloudflare)

Sådan vises denne dokumentation som et pænt, privat site — hostet 100 % på Cloudflare, der auto-opdaterer ved hvert git-push (ingen VPS). Beslutningen er fanget i arkitektur/adr/0002-c4-med-likec4.md.

Sådan hænger det sammen

git push → Cloudflare Pages bygger (mkdocs build) → nyt site live Cloudflare Access spærrer for alle andre end vores e-mails

  • Portal: MkDocs + Material for MkDocs (se mkdocs.yml + requirements.txt i repo-roden).
  • Diagrammer: C4/LikeC4 → eksporterede PNG'er (se arkitektur/c4/README.md).
  • Privat: Cloudflare Access (Zero Trust), gratis, låst til vores e-mails.

Kør lokalt (før Cloudflare kobles på — anbefalet)

bash pip install -r requirements.txt mkdocs serve # → http://127.0.0.1:8000

Ret mkdocs.yml (fx nav) og bekræft at alt renderer, inkl. Mermaid og C4-billederne, før I forbinder Cloudflare.

Cloudflare Pages — engangsopsætning (~5 min)

  1. Giv GitHub-appen adgang til repoet FØRST. Cloudflares GitHub-app er typisk sat til "Only select repositories" — så documentation er usynlig i Cloudflare indtil den tilføjes. Gå til https://github.com/organizations/MelsensHub/settings/installations → Cloudflare Workers and Pages → Configure → under Repository access vælg All repositories eller tilføj documentation → Save.
  2. I Cloudflare: Workers & Pages → Create application → Pages project → Connect to Git → vælg MelsensHub/documentation. (Cloudflare skubber mod Workers; Pages-flowet gemmer sig bag knappen "Pages project" — ikke bare "Pages".) Virker med private repos.
  3. Build-indstillinger (trin "Set up builds and deployments"):
Indstilling Værdi
Production branch main
Framework preset None
Build command pip install -r requirements.txt && mkdocs build && mv ../site ./_site
Build output directory _site (feltet viser / som præfiks → bliver /_site)
Environment variable PYTHON_VERSION = 3.12

Hvorfor mv: mkdocs-same-dir tvinger outputtet til ../site (uden for repoet); vi flytter det ind i _site efter build, så Cloudflare kan finde det. 4. Gør den privat med Cloudflare Access. Aktivér FØRST login-metoden: Zero Trust → Settings → Authentication → Login methods → sørg for One-time PIN er tilføjet (ellers sender Access ingen mails — hyppig fejl). Derefter Zero Trust → Access controls → Applications → Add an application (Self-hosted) på sitets domæne → policy Allow med Include → Emails = jeres to e-mails.

Herefter: I redigerer markdown, pusher, og sitet opdaterer sig selv.

Senere: den interaktive C4-viewer (valgfrit, samme repo)

Den rigtige, zoombare LikeC4-viewer kan stå som et separat Cloudflare Pages-projekt fra samme repo — uden at røre diagrammerne:

Indstilling Værdi
Build command npx likec4@1.59.1 build --base / -o dist
Build output directory dist
Env NODE_VERSION = 22

Beskyt den med samme Cloudflare Access-policy. Så har I: MkDocs = prosa-portal, LikeC4 = interaktiv arkitektur-viewer — begge private, begge auto-byggende, samme kilde.

Forbehold (verificér)

  • Konfigurationen er sammensat ud fra verificeret research (juli 2026), men er ikke bygget/testet i dette miljø — kør mkdocs serve lokalt og bekræft før produktion. Tjek især at billederne i arkitektur/c4/assets/ kopieres med i sitet (docs i repo-roden).
  • Gratis-tier-grænser (Cloudflare Access ~50 brugere; Pages 500 builds/md) — verificér hos Cloudflare.
  • Pin-versioner i requirements.txt bør tjekkes mod PyPI ved opdatering (jf. AGENTS.md om foranderlige fakta).