This repository is a study and orientation layer built on top of
DogTag PKI (Red Hat's open-source enterprise Certificate
Authority). The goal is to make the ~600K-LOC codebase navigable: every directory carries a
map.md describing what lives there, where to go next, and where to look when something
breaks.
| Path | What it is |
|---|---|
pki/ |
A snapshot of dogtagpki/pki (see Provenance). Each directory has a map.md. Start at pki/map.md. |
docs/presentation/ |
Interactive HTML tour of the codebase — architecture, subsystems, repo map, code layers, build/test. Open index.html in a browser; no build, no dependencies. |
CLAUDE.md |
Orientation: big-picture architecture (CA / KRA / OCSP / TKS / TPS / ACME / EST over Tomcat + JSS/NSS + 389-DS LDAP), build/test commands, and the map.md contract. |
tools/gen_maps.py |
Generator that creates/maintains a map.md in every directory. Run it after any file changes under pki/. |
map.md |
Workspace-root navigation. |
Once Pages is enabled (one-time, below), the interactive tour is browsable at:
→ https://tro-wolf.github.io/CustomDogTag/
Enable it once: repo *Settings → Pages → Build and deployment → Source: “Deploy from a branch”
→ Branch: main, folder: / (root) → Save. Give it ~1 minute to build. A .nojekyll file is
included so the files are served as-is, and the root index.html redirects to
docs/presentation/.
Each map.md has five sections:
- Purpose — what the directory is and why (hand-authored).
- Contents — a table of files + child maps (auto-generated).
- I want to… → go to — task-oriented navigation links.
- Pointers — up/down links (auto-generated).
- Debug — where to look when something here misbehaves.
The Contents and Pointers blocks (between <!-- AUTOGEN:… --> markers) are regenerated
by tools/gen_maps.py; Purpose / I want to… / Debug are hand-authored and preserved across
runs. All 1,140 directories are documented.
python3 tools/gen_maps.py # create/refresh every map.md
python3 tools/gen_maps.py --check # verify full coverage (exit 1 if any dir lacks a map.md)pki/ is a snapshot of dogtagpki/pki at upstream commit 60dc2ac
("Add ML-KEM storage support to KRA key archival", #5358). Only map.md files were added —
no upstream source files were modified. This is a standalone snapshot (the upstream git history
was not retained); to update, re-clone dogtagpki/pki and re-run tools/gen_maps.py.
DogTag PKI is licensed under GPL-2.0; the upstream license is retained at
pki/LICENSE and governs the pki/ subtree. The added map.md documentation and
tools/gen_maps.py are provided under the same terms. This repository is an independent,
unofficial study aid and is not affiliated with or endorsed by Red Hat or the Dogtag project.