CertiStack Community codebase guide
Community Edition is a CLI-first, local recovery-validation engine. It contains
no web server, dashboard, daemon, webhook listener, entitlement code, or
packaging for a persistent service. This page is the one maintained map of the
tree; README.md and CONTRIBUTING.md link here instead of repeating it.
Package map
| Path | Purpose |
|---|---|
cmd/certistack |
Operator CLI: init, validate, plan, run, verify-report, keygen, doctor, inspect, recover, version, plus the hidden node-run, node-plan and node-discover modes the controller uploads to a PVE node. |
pkg/config |
YAML plan parser, alias normalisation, and validator. Every accepted, aliased, and rejected key is listed in the test-plan reference. |
pkg/initplan |
init: discovery of the VMs with backups, their guests, the node's overlay storages and free IDs (read-only), and composition of a first plan that must validate. |
pkg/runner |
Public local execution path used by the CLI and by products built on the engine: host lock, journal, PVE/PBS clients, orchestrator, RTO target check, report writing. |
pkg/controller |
Strict-SSH bootstrap of the temporary node worker, result retrieval, teardown verification and retry, controller-side report signing and retention. |
pkg/nodeapi |
Versioned controller/worker result contract. |
pkg/orchestrator |
Tiered recovery orchestration: admission, snapshot resolution, mapping, overlays, sandbox VM lifecycle, guest network recovery, probes, soak periods, teardown evidence. |
pkg/pbs, pkg/pve, pkg/sdn |
PBS map/unmap client; PVE REST client with UPID task tracking; isolated SDN zone/VNet lifecycle and read-only validation. |
pkg/admission |
/proc/meminfo and /proc/stat host admission controller and capacity reservation. |
pkg/probe |
Probe result types, with probe/qmp (hypervisor state), probe/synthetic (TCP, HTTP/TLS, DNS, LDAP), probe/qga (constrained guest-agent checks), and probe/screendump (PPM to PNG framebuffer capture). |
pkg/attest |
RFC 8785 canonical JSON, Ed25519 signing, keyring loading, pinned-signer verification, and the report schema (attest.CurrentReportSchemaVersion, currently 1.5). |
pkg/cleanup |
LIFO teardown stack with signal and panic unwinding. |
pkg/progress |
Elapsed-time timeline printer used by the controller during a run. |
pkg/recovery |
Public crash-recovery entry point for programs built on the engine. |
internal/journal |
Durable run journal (active.json) and the host lock. |
internal/process |
Process identity (kernel start ticks) so recovery never acts on a reused PID. |
internal/preflight |
Node preflight checks used by doctor and by the worker before any mutation. |
internal/recovery |
Journal-scoped reconciliation of loops, overlays, VMs, host addresses, and SDN objects; no host-wide sweep. |
internal/guestnet |
COW-only guest network adapter (ifcfg, NetworkManager, Netplan, systemd-networkd, ifupdown, firewalld probe rule) applied with guestfish. |
internal/sysutil |
qemu-img overlays, loop-device inspection, private directories, nft/sysctl containment, and the audited command runner. |
examples/ |
Documentation-conformant plans to copy; validated by the test suite. |
testdata/plans |
Larger fixtures used by tests. |
deploy/controller, deploy/appliance |
Unprivileged OCI image and Compose reference; Packer VM-template recipe. |
terraform/ |
PVE role, service user, token, and reference-VM example. |
scripts/, .lab/ |
Campaign runner and its tests; coverage-case generator and compatibility-matrix audit tools. |
docs/, mkdocs.yml |
This documentation site (make docs). |
Execution path
certistack run loads a plan, then delegates to pkg/runner. The runner
acquires the host lock, records durable run state, creates the PVE/PBS clients,
calls the orchestrator, writes report artifacts, and marks the journal clean.
certistack recover reconciles resources from the same journal after an
interrupted run.
Edition boundary
The private Enterprise repository may import public Community packages. The reverse dependency is prohibited. Management APIs, embedded browser assets, entitlements, protected-asset metering, HTML/PDF compliance-binder rendering, outbound notifications, and service packaging belong only in that private repository. The Community engine's deliverable is the signed JSON report and its verification; a pull request that adds rendering, delivery, scheduling, or multi-tenant features to this repository crosses the edition boundary.