TDS-PORTFOLIO-002: Docusaurus + Docker-opzet

Datum: 2026-05-19 Status: Opgeleverd

Doel

De technische opzet van de Docusaurus-frontend en de Docker-runtime voor Ruimtemeesters Documentatie. Levert "iets dat draait": een Caddy-container op rm-network die de statische Docusaurus-build serveert.

Referentie

• ADR: [[PORTFOLIO-002-docusaurus-als-presentatielaag]]
• Content-strategie: [[PORTFOLIO-001-overlay-geen-mirror]]

Referentiepatroon

Ruimtemeesters-Documentatie/
├── docs/                           ← bestaande markdown blijft de bron
│   ├── 00-visie/
│   ├── 05-user-journeys/
│   └── …
├── src/
│   ├── css/custom.css              ← brand-kleuren
│   └── pages/index.tsx             ← landingspagina op /
├── static/                         ← favicon, logo, afbeeldingen
├── docusaurus.config.ts            ← Docusaurus-configuratie
├── sidebars.ts                     ← autogenerated uit docs/
├── tsconfig.json
├── package.json
├── Dockerfile                      ← multi-stage: node-build → Caddy
├── Caddyfile                       ← static + SPA-fallback + asset-caching
└── docker-compose.yml              ← service op rm-network

Vereiste technische eigenschappen

Build-stack

• Docusaurus ^3.10.0 (preset-classic + theme-mermaid)
• Node >=20 voor de build-stage
• TypeScript voor configuratie (docusaurus.config.ts)
• MDX 3 voor inline React-components in markdown

Runtime

• caddy:2-alpine als runtime-image (consistent met de portfolio-keuze voor Caddy als reverse-proxy/static server)
• Multi-stage Dockerfile: Node-build → Caddy-serve. Geen Node in de runtime-image.
• Image-grootte target: < 50 MB (alpine + static files)
• Geen secrets, geen env-vars nodig op runtime

Network

• Container hangt op rm-network (extern Docker-netwerk dat al bestaat naast de andere Ruimtemeesters-apps).
• Lokaal previewen: poort 8080 op de host gemapt op container-poort 80.
• Productie: reverse-proxy (apart, niet in deze compose) op een eigen domein. Auth-gating regelt de proxy.

Build-determinisme

• package-lock.json gecommit zodat builds reproduceerbaar zijn.
• Dockerfile gebruikt npm ci met fallback naar npm install als lockfile ontbreekt.

Markdown-compatibiliteit

• Bestaande README.md per folder fungeert automatisch als category-index.
• docs/README.md is de root-category. De landingspagina (/) komt uit src/pages/index.tsx.
• Mermaid-fences (```mermaid) renderen via @docusaurus/theme-mermaid.
• Wikilinks ([[naam]]) renderen als platte tekst in fase 1; later wordt een resolver-plugin toegevoegd.
• onBrokenLinks: 'warn' zodat de build niet faalt op interne verwijzingen die nog niet bestaan.

Commando's

Commando	Doel
npm install	Dependencies installeren (eenmalig)
npm start	Lokale dev-server met hot-reload op :3000
npm run build	Statische build naar build/
npm run serve	Lokale preview van de productiebuild
npm run typecheck	TypeScript-validatie van de config
docker compose up --build -d	Container builden en starten op rm-network
docker compose down	Container stoppen

Buiten scope (fase 1)

• Algolia-search — local lunr volstaat tot het volume het rechtvaardigt
• Versionering van docs — git-historie volstaat
• i18n — alleen Nederlands
• Auth-gating in de container — regelt de proxy / Workspace
• Algoritmische wikilink-resolver — later via remark-plugin
• CI-integratie van de build — eerst lokaal valideren

Openstaande vragen

• URL en gating: documentatie.datameesters.nl achter de centrale Caddy-proxy; Clerk-auth via Workspace of intern alleen via VPN? Defer tot na fase 1.
• Generator-integratie: wanneer de overlay-generator ([[TDS-PORTFOLIO-001-overlay-generator]]) bestaat, runt die als pre-build step in Docker of als losse CLI? Defer tot generator gebouwd wordt.