A fresh zddc-server deployment grants no access to anyone until two config files are populated. Without them the server runs but every request returns 403. The embedded defaults ship with empty role members, so deployments must opt-in to authorize anyone — there is no default "anything goes" mode (except --insecure, which is explicitly for deliberately-public archives).
Two files, both named .zddc. YAML format. Hand-edited.
/.zddcAt <ZDDC_ROOT>/.zddc, name at least one admin:
admins: is honored only at the root file. Admins behave as normal users by default and elevate per-request via the zddc-elevate=1 cookie (the header toggle visible in every tool) or implicitly when authenticating with a bearer token. This sudo-style model means an admin can't accidentally clobber files in their everyday browsing — elevation is opt-in.
Without this file the server refuses to start (the served tree would be publicly accessible to anonymous callers); pass --insecure to acknowledge a deliberately-public deployment.
<project>/.zddcIn each project, populate the document_controller and project_team role members:
That's it. The embedded cascade does the rest:
+ +project_team gets read across the projectdocument_controller gets read+write project-wide, plus create authority on archive/, WORM filing rights on received/ and issued/, and subtree-admin of working/, staging/, and reviewing/Add a new project team member with one line; revoke by removing the line. No need to restate the cascade's grants — they're already in the embedded defaults that ship with zddc-server.
| Key | +Where | +Shape | +
|---|---|---|
admins: |
+ Root only | +List of emails. Sudo-style; gates on zddc-elevate=1. |
+
acl: |
+ Anywhere; cascades | +{ permissions: { <principal>: <bits> }, inherit: <bool>? } |
+
roles: |
+ Anywhere; members union across the cascade | +{ <name>: { members: [...], reset: <bool>? } } |
+
title: |
+ Per-project only | +String; surfaces on the landing-page picker. | +
Permission bits — any subset of:
+ +r readw write (overwrite existing files)c create (new files, new directories)d deletea admin (subtree-admin at this level and below)An empty bits string ('') is an explicit deny.
Principals — three forms:
+ +@, e.g. alice@burnsmcd.com'*@acme.com' (quote it in YAML so the leading * doesn't confuse the parser)@, e.g. document_controller. The role's members are looked up via roles: at any cascade level.This is silently dropped:
+The YAML parses cleanly but ACLRules only reads permissions:. The allow: block is discarded during unmarshal and you end up with zero grants. Correct form:
zddc-server prints a startup warning when the root .zddc grants nobody anything — watch for it on first boot:
To dump the full annotated schema (every cascade key with documentation):
+ +That prints the embedded defaults.zddc.yaml with comments explaining every option (worm:, auto_own:, drop_target:, apps:, convert:, on_plan_review:, records:, available_tools:, default_tool:, dir_tool:, and more). Pipe it to a file and use it as the starting point for any deeper customization.
Two single-file HTML applications — each is complete and self-contained. Save them locally and they work forever, without internet, without updates, without a subscription. Together they cover the full ZDDC workflow: archive for searching and exporting the formal record; browse for navigating, editing, and managing the project tree.