Typst-Dokumentenrendering-Architektur
Typst ist ein markup-basiertes Satzesystem für akademische Dokumente — Papers, Abschlussarbeiten, Vorlesungsnotizen, Klausuren und Verwaltungsbriefe. Es kompiliert zu PDF mit schnellen inkrementellen Builds, integrierter Skriptsprache und einem Paket-Ökosystem und ist die moderne Alternative zu LaTeX für den institutionellen Dokumentenproduktion.
openEduSuite betreibt Typst als vollwertigen Suite-Service: upstream-getrackter Fork, Multi-Arch-Containerimages, eine HTTP-Render-API und Deployment-Verkabelung für beide Stacks — Kubernetes (Hochschule) und Docker Compose (SME).
Fork- und Upstream-Policy
Die Suite verwendet tobias-weiss-ai-xr/typst, einen Fork von Upstream typst/typst:
- Wöchentlicher Sync: Ein geplanter Workflow merged Upstream
mainin den Fork; Merge-Konflikte schlagen bewusst laut fehl (manuelle Auflösung). - Fork-spezifischer Code liegt ausschließlich unter
render-service/und.github/workflows/— Upstream-Merges bleiben konfliktfrei. - Releases folgen der Upstream-Version (
v0.15.1) und werden bei jedem Sync zurückgesetzt. Jedes GitHub-Release veröffentlicht zwei Multi-Arch-Images (linux/amd64 + arm64):ghcr.io/tobias-weiss-ai-xr/typst— die unveränderte typst-CLIghcr.io/tobias-weiss-ai-xr/typst-render— der Render-Service (CLI + HTTP-API + Liberation-Fonts)
Render-Service
Der Render-Service ist ein bewusst kleiner, abhängigkeitsfreier HTTP-Wrapper um die typst-CLI (nur Python-Standardbibliothek):
POST /render {"source": "= Hallo", "format": "pdf|png|svg",
"assets": {"daten.csv": "..."}} -> Dokument-Bytes
GET /healthz -> {"status": "ok", "typst": "typst 0.15.1 ..."}
Vertrauensgrenzen, im Prozess erzwungen:
- Größenlimits (5 MB Request, 2 MB Quelle) und ein Compile-Timeout pro Request (60 s).
- Asset-Namen sind auf flache
[A-Za-z0-9._-]-Bezeichner beschränkt — kein Path Traversal. - Die Kompilierung läuft in einem isolierten temporären Verzeichnis mit
--root-Beschränkung; die typst-CLI führt keine Netzwerkzugriffe aus. - Die Compile-Konkurrenz ist begrenzt (Standard 4), um Cluster-Knoten vor CPU-Sättigung zu schützen.
- Der Service läuft im Container als unprivilegierter Benutzer (UID 1000).
Liberation-Fonts sind im Image enthalten und decken die metrisch kompatiblen Schriftfamilien Arial/Times/Courier ab, die die meisten institutionellen Dokumentvorlagen verwenden.
Deployment
| Stack | Verkabelung |
|---|---|
| Kubernetes (Hochschule) | Helmfile-Chart typst-render im Deployment-Repository openEDU-hrz, gepinnt auf ein Release-Tag |
| Docker Compose (SME) | typst-render-Service-Profil in openSME-compose |
Beide Deployments exponieren den Service auf einem internen Netzwerkpfad, nutzen eine /healthz-Liveness-Probe und pinnen Images per Release-Tag — dieselbe Disziplin wie bei allen anderen Suite-Services. Der Service ist maschinengerichtet (Template-Pipelines, Admin-Werkzeuge, Portal-Backends) und nicht für den direkten Browser-Zugriff durch Endnutzer vorgesehen.
Integrationsfläche
Typst ergänzt die kollaborativen Editoren der Suite (Collabora, CryptPad, HedgeDoc), anstatt sie zu ersetzen: Diese decken interaktives gemeinsames Bearbeiten ab; Typst deckt deterministisches, template-getriebenes Produktionssatz ab — z. B. Klausuren aus einem Vorlagen-Repository rendern, Zertifikate erzeugen oder Briefe in Serie aus Registrierungsdaten produzieren.
