Typst Document Rendering Architecture
Typst is a markup-based typesetting system for academic documents — papers, theses, lecture notes, exams, and administrative letters. It compiles to PDF with fast incremental builds, built-in scripting, and a package ecosystem, and serves as the modern alternative to LaTeX for institutional document production.
openEduSuite ships Typst as a first-class suite service: upstream-tracked fork, multi-arch container images, an HTTP render API, and deployment wiring for both the Kubernetes (higher education) and Docker Compose (SME) stacks.
Fork and upstream policy
The suite uses tobias-weiss-ai-xr/typst, a fork of upstream typst/typst:
- Weekly sync: a scheduled workflow merges upstream
maininto the fork; merge conflicts fail loudly for manual resolution. - Fork-specific code lives exclusively under
render-service/and.github/workflows/, keeping upstream merges conflict-free. - Releases follow the upstream version (
v0.15.1), reset on each sync. Every GitHub release publishes two multi-arch (linux/amd64 + arm64) images:ghcr.io/tobias-weiss-ai-xr/typst— the pristine typst CLIghcr.io/tobias-weiss-ai-xr/typst-render— the render service (CLI + HTTP API + Liberation fonts)
Render service
The render service is a deliberately small, dependency-free HTTP wrapper around the typst CLI (Python standard library only):
POST /render {"source": "= Hello", "format": "pdf|png|svg",
"assets": {"data.csv": "..."}} -> document bytes
GET /healthz -> {"status": "ok", "typst": "typst 0.15.1 ..."}
Trust boundaries, enforced in-process:
- Body size caps (5 MB request, 2 MB source) and a per-request compile timeout (60 s).
- Asset names are restricted to flat
[A-Za-z0-9._-]identifiers — no path traversal. - Compilation runs from an isolated temporary directory with
--rootconfinement; the typst CLI performs no network access. - Compile concurrency is bounded (default 4) to protect cluster nodes from CPU saturation.
- The service runs as an unprivileged user (UID 1000) in the container.
Liberation fonts are baked into the image, covering the metric-compatible Arial/Times/Courier families used by most institutional document templates.
Deployment
| Stack | Wiring |
|---|---|
| Kubernetes (higher education) | Helmfile chart typst-render in the openEDU-hrz deployment repository, pinned to a release tag |
| Docker Compose (SME) | typst-render service profile in openSME-compose |
Both deployments expose the service on an internal network path, use a /healthz-based liveness probe, and pin images by release tag — the same discipline as every other suite service. The service is machine-facing (template pipelines, admin tooling, portal backends); it is not intended to be exposed directly to end-user browsers.
Integration surface
Typst complements rather than replaces the collaborative editors in the suite (Collabora, CryptPad, HedgeDoc): those cover interactive co-editing; Typst covers deterministic, template-driven production typesetting — e.g., rendering exam papers from a template repository, generating certificates, or batch-producing letters from registry data.
