Project map and documentation coverage¶
Use this map to find the procedure for each repository area. Source links open private GitHub content and require repository access; this public site publishes selected guides, not an automatic mirror of every repository file.
Start with the task¶
| Task | Guide | Authoritative inputs |
|---|---|---|
| Find or change a host | Hosts, Appliances | Inventory entity YAML and host variables |
| Deploy or repair a service | Services, onboarding | Service README, Compose, Komodo resources |
| Restore data | Restore, backup triage | Service and external backup manifests; restore drills |
| Change network policy | Network, firewall | Inventory, Tailscale ACL, dated UniFi captures |
| Maintain runners | Runner operations | Fleet manifest, placement map, dispatch workflows |
| Investigate incidents | Alert triage, OneUptime | Alert rules, adapter policies, recorded incident evidence |
| Prepare an operator workstation | Shell, tools | Operator manifests and bootstrap scripts |
| Change documentation | Validation, Pages | MkDocs navigation, documentation checks, locked dependencies |
Inventory and generated files¶
All hosts, appliances, customer apps, and registered services must have an
existing documentation path inside docs/. Status active expresses lifecycle,
not a promise that a VM is powered on. Dated discovery captures are evidence at
their capture time, not an automatic live inventory refresh.
Run generators after inventory changes and use --check before committing.
The stub generator checks presence only; it does not establish accuracy or
completeness of a page. Never overwrite operator notes with regenerated stubs.
| Generator | Output or purpose |
|---|---|
inventory/generators/render-ansible.py |
Ansible inventory and host variables |
inventory/generators/render-diagram.py |
Inventory network diagram |
inventory/generators/render-discovery-inventory.py |
Guest discovery inventory |
inventory/generators/render-dns-rewrites.py |
AdGuard DNS rewrites |
inventory/generators/render-doc-stubs.py |
Missing entity pages only; existing pages are never refreshed |
inventory/generators/render-homepage.py |
Homepage directory |
inventory/generators/render-hyperv-scaler.py |
Hyper-V placement map |
inventory/generators/render-oneuptime.py |
OneUptime desired-state JSON |
inventory/generators/render-prometheus.py |
Prometheus scrape targets |
inventory/generators/render-remediation-targets.py |
Broker target allowlist |
inventory/generators/render-runner-fleet-diagram.py |
Runner topology diagram |
inventory/generators/render-runner-fleet-dispatch.py |
Runner workflow choices |
Configuration management¶
Ansible roles are implementation modules. Follow the linked operating procedure
and its host/class restrictions; the presence of a role is not permission to
apply it to every host. site.yml selects current roles, while retired code can
remain for history. Saltbox container management stays with Saltbox.
| Role source | Responsibility | Procedure |
|---|---|---|
infra/ansible/roles/backup-client |
Backup jobs, offsite copy, isolated restore checks | Guide |
infra/ansible/roles/common |
OS baseline, pull timers, host access and service prerequisites | Guide |
infra/ansible/roles/discover-facts |
Read guest facts into discovery artifacts | Guide |
infra/ansible/roles/github_runner |
Install runner placements from the fleet manifest | Guide |
infra/ansible/roles/github_runner_maintenance |
Guarded runner drain and maintenance | Guide |
infra/ansible/roles/github_runner_observability |
Runner host metrics and logs | Guide |
infra/ansible/roles/graylog-syslog-client |
Forward unmanaged-host and guest syslog | Guide |
infra/ansible/roles/monitoring-deadman |
External heartbeat for total monitoring outages | Guide |
infra/ansible/roles/operator-shell |
Golden shell, dotfiles and operator identity | Guide |
infra/ansible/roles/operator-tools |
Pinned development and operational tools | Guide |
infra/ansible/roles/patch-controller |
Coordinate patch waves from the control host | Guide |
infra/ansible/roles/patching |
Patch target policy, hooks and metrics | Guide |
infra/ansible/roles/postgresql-companion |
PostgreSQL application databases and extensions | Guide |
infra/ansible/roles/prox-mem-soak |
Collect attributed hypervisor memory samples | Guide |
infra/ansible/roles/rexit-exporter |
Scheduled exports, secrets and exporter metrics | Guide |
infra/ansible/roles/saltbox-host |
Saltbox OS boundary and encrypted configuration | Guide |
infra/ansible/roles/tailscale |
Tailnet clients, routes and managed access | Guide |
infra/ansible/roles/wazuh-agent |
Retained retirement implementation; not installed by site.yml | Guide |
infra/ansible/roles/whrrr-reddit-explorer |
Reddit Explorer media and library mounts | Guide |
infra/ansible/roles/whrrr-scans |
Paperless and Stirling shared document storage | Guide |
GitHub workflows¶
Workflow files define triggers, runner selectors, permissions and mutation
controls. Check the current YAML before dispatching a manual job. Reusable
_runner-fleet-* workflows are called by the dispatcher/scheduler.
Supporting areas¶
| Area | Purpose and documentation |
|---|---|
scripts/runner_fleet/, scripts/hyperv_scaler/, infra/github-runners/ |
Runner operations and observability |
scripts/labctl/, discovery and inventory proposal scripts |
Guest discovery; proposals require review before inventory changes |
scripts/runner-observability/ |
Runner telemetry installers |
scripts/ops/ |
Guest discovery SSH bootstrap |
scripts/workstation/ |
Optional workstation ComfyUI helpers; inspect their source and prerequisites before running |
scripts/ bootstrap, render, rotate and one-off hotfix commands |
Use the linked service README or runbook; a historical hotfix is not a normal reconciliation step |
backups/ |
Restore, full disaster recovery, backup triage; runtime jobs come from per-service and external manifests |
monitoring/ |
Alert schema, triage, runner telemetry |
infra/tailscale/ |
Network and tailnet policy; source README contains ACL GitOps details |
secrets/, encrypted service and host vars |
Secrets management; plaintext credentials and runtime outputs must stay outside the site |
operator/dotfiles/, operator/devtools/, operator/codex/, operator/agents-skills/ |
Shell, devtools, Codex management; individual skills document their own workflows |
tests/ and service-local tests |
Executable checks for source behavior; a passing test does not prove a live deployment |
.cursor/rules/, PLAN.md, README.md, SECURITY.md |
Repository conventions, original plan, dated owner task record, and vulnerability reporting; private source references |
docs/journal/, docs/reviews/, docs/evidence/, docs/postmortems/ |
Dated evidence and historical decisions; use current operating guides before acting |
Completeness standard¶
A service guide needs purpose, lifecycle/host, access and authentication, deployment prerequisites, secret configuration boundaries, health verification, backup/restore policy, and troubleshooting or escalation. Stateless, retired, and local-only tools should state which steps do not apply. Link a shared runbook rather than copying its commands into every page.
check-docs.py enforces coverage of entity pointers, service manuals, these role,
workflow and generator mappings, and the built sitemap/search index. It cannot
prove that arbitrary prose is accurate or that a recovery procedure works. Record
those checks and unresolved findings in the validation journal.