ZDDC
b5aab81d31
New endpoint GET /<path>/foo.md?convert=docx|html|pdf renders a markdown source on demand. Surfaced as the Download buttons in browse's markdown editor (separate commit). Execution model — two upstream container images, lazy-pulled: • docker.io/pandoc/latex:latest — MD→DOCX, MD→HTML (entrypoint pandoc) • docker.io/zenika/alpine-chrome — HTML→PDF (entrypoint chromium-browser) No custom image build. The runner passes --pull=missing on every podman/ docker invocation so the operator only needs the runtime installed — first request pulls the image, subsequent requests use the local cache. Overrides: --convert-pandoc-image / --convert-chromium-image (and the matching ZDDC_CONVERT_* env vars). Engine: --convert-engine (podman preferred, docker fallback). Resource caps: --convert-mem-mib (512), --convert-cpus (2), --convert-pids (100), --convert-timeout (30s). PDF flow is two-stage: pandoc renders the markdown through the embedded viewer-template.html to standalone HTML, then chromium prints that HTML via --print-to-pdf. Preserves the print-media CSS already authored in viewer-template.html rather than going through pandoc's LaTeX template. Each conversion runs in a throw-away container with --rm --network=none --read-only --tmpfs=/tmp --cap-drop=ALL --security-opt=no-new-privileges --env=HOME=/tmp plus a bind-mounted scratch dir for I/O. Pandoc reads markdown from stdin / writes to stdout; the viewer template lives at /tpl (ro). Chromium reads HTML from a read-write bind mount at /pdf and writes the PDF to the same mount; the host reads it back. No shell wrappers, no shell quoting — argv flows straight into each image's entrypoint. On-disk cache at <dir>/.converted/<base>.<ext> with mtime synced to the source. Fast path is a stat-and-serve with no exec; slow path singleflights concurrent requests for the same target. PUT/DELETE/MOVE on the source .md purges the .converted/ sidecars. Per-project template variables (client/project/contractor/project_number) come from a new .zddc `convert:` cascade block, walked leaf→root with per-key latest-wins. Filename-derived variables (title, tracking_number, revision, status, is_draft) come from a new zddc.ParseFilename helper. If neither podman nor docker is on PATH, the endpoint serves 503 with a clear Retry-After. The rest of the server keeps working. This is the first os/exec site in the codebase. The hardening in internal/convert/runner.go — context.CancelFunc → process kill, cmd.WaitDelay, platform-specific SysProcAttr (Setpgid + Pdeathsig on Linux), minimal env, stdout cap via limitWriter, stderr ring buffer — sets the pattern for any future shell-outs. Public surface: convert.ToDocx(ctx, source, meta) / .ToHTML / .ToPDF convert.Probe(ctx, engineOverride) → install Runner if engine present convert.SetImages(pandoc, chromium) convert.ConfigureLimits(memMiB, cpus, pids, timeout) convert.Available() Container handler at internal/handler/converthandler.go; dispatcher branch in cmd/zddc-server/main.go inserts the convert lookup after the existing ACL gate, reusing the source file's read policy verbatim. |
||
|---|---|---|
| .forgejo | ||
| archive | ||
| browse | ||
| classifier | ||
| form | ||
| helm | ||
| landing | ||
| mdedit | ||
| pandoc | ||
| shared | ||
| tables | ||
| tests | ||
| transmittal | ||
| zddc | ||
| .gitignore | ||
| AGENTS.md | ||
| ARCHITECTURE.md | ||
| build | ||
| CLAUDE.md | ||
| deploy | ||
| dev-server | ||
| freshen-channel | ||
| LICENSE.txt | ||
| package.json | ||
| playwright.config.js | ||
| README.md | ||
| SECURITY.md | ||
Zero Day Document Control (ZDDC)
The Universal Distributed Filing Cabinet
ZDDC is an information management convention plus a small set of single-file HTML tools. Every deliverable's filename encodes its tracking number, revision, status, and title; every transmittal folder is date-prefixed and self-describing. A plain shared folder becomes a fully searchable, auditable archive — no server, no database, no software required to read it.
The name "Zero Day Document Control" comes from the convention itself — adopt it on day zero of a project, with no setup time. The tools are optional interfaces around the structure; the structure works without them.
For end users: https://zddc.varasys.io/ introduces the project, links to all tool channels (stable / beta / alpha), and prints copy-paste shell snippets to install on a self-hosted deployment.
Tools
| Tool | What it does |
|---|---|
| Archive Browser | Browse, search, and filter a project archive folder. Group by transmittal, export selections as ZIP. |
| Transmittal Creator | Self-contained HTML transmittal records with SHA-256 checksums and optional digital signatures. |
| Document Classifier | Spreadsheet-like bulk-renamer that copy/pastes with Excel and writes back to disk. |
| Markdown Editor | Browser-based markdown editor with YAML front matter, TOC, and direct local file access. |
| Form Renderer | Schema-driven *.form.yaml editor — every form spec auto-mounts an editable form at <name>.form.html. |
| Tables | Sortable, filterable, in-place-editable grid view over a directory of YAML rows; click a row → edit in the form renderer. Auto-mounts on any directory containing a table.yaml. |
| Browse | File-tree navigator with previews; the everywhere-available companion to the Archive Browser when you want plain folder navigation rather than tracking-number aggregation. |
| Landing | The project picker served at the deployment root of a zddc-server. |
Each tool is published in three channels (stable, beta, alpha) as static files served from https://zddc.varasys.io/releases/. Local use: download a .html file from releases/ and open it in a browser. Server use: run zddc-server — the current-stable build of every tool is baked into the binary at compile time, so a fresh deployment Just Works with zero config. Which tool a directory URL serves is driven by the .zddc cascade: a baked-in defaults.zddc.yaml (dump it with zddc-server show-defaults) declares, per folder, default_tool (the no-slash form — archive under archive/, transmittal under staging/, mdedit under working/, classifier under incoming/, tables at archive/<party>/mdl, landing at root) and dir_tool (the trailing-slash form; defaults to browse); operators override at any level. A .zip file is also a navigable directory (GET …/Foo.zip/), and GET /dir/?zip=1 streams an ACL-filtered zip of a subtree. Override the tool source per-directory by writing an apps: entry in any .zddc file (channel/version/URL/path) — fetched once and cached in <ZDDC_ROOT>/_app/ — or drop a real .html file at any path.
File-naming convention
The full specification — filename format, tracking numbers, revision rules, status codes, folder naming, and the transmittal workflow — lives at https://zddc.varasys.io/reference.html.
Quick example: 123456-EL-SPC-2623_A (IFR) - Specification For Switchgear.pdf
Build & develop
git clone https://codeberg.org/VARASYS/ZDDC.git && cd ZDDC
./build # dev build of every tool (writes to dist/ only)
sh archive/build.sh # iterate on one HTML tool
./build alpha # lockstep alpha cut for all nine artifacts
./build beta # lockstep beta cut
./build release # lockstep stable, coordinated next version
./build release 1.2.0 # lockstep stable at explicit version
npm install && npx playwright install chromium && npm test # tests
./dev-server start # cache-busting HTTP on :8000
Authoritative build/release docs are in AGENTS.md. Architecture notes (single-file rationale, JS module pattern, security model) are in ARCHITECTURE.md. zddc-server (optional Go HTTP server with ACL and a virtual archive index) is in zddc/README.md. Example Helm charts for deploying zddc-server (production + dev) are under helm/.
Contributing
ZDDC is an open source project hosted on Codeberg at https://codeberg.org/VARASYS/ZDDC. Bug reports, feature requests, and pull requests welcome.
ZDDC is designed for zero configuration to start and minimal configuration overall — feature proposals are filtered through that lens.
License
GNU Affero General Public License v3.0. Free to use, modify, and distribute, including commercially, under the terms of the license. Provided "as is" without warranty.