mrcharles
30ddb37b34
Commit 33b5c76 claimed to harden Pi-hole on both DNS nodes but only
modified markdown — the working docker-compose.yml, gravity-validate.sh,
healthcheck, and autoheal config were never written to the repo, leaving
the DNS hardening unreproducible from version control.
This commits the live, verified-working config from the boxes into
netinfra/pihole/:
- docker-compose.yml (shm_size 1024M root-cause fix, healthcheck, autoheal)
- gravity-validate.sh (pre-start SQLite header check, auto-quarantine corrupt DB)
- .env.example (web UI password templated; real .env gitignored)
Defends against the gravity.db / /dev/shm corruption production outage.
The live password is templated as ${PIHOLE_WEB_PASSWORD} so no secret
enters git.
[#376]
9.2 KiB
9.2 KiB
Documentation Map
Index of all documentation in this repo. Agents must update this file whenever a doc is added, removed, or substantively changed.
Last updated: 2026-08-06 (Pi-hole hardening config committed to netinfra/pihole/ — [#376])
Kubernetes Architecture (k8s/)
Distro decision, target architecture, control-plane design, bootstrap and DR procedures for the pfv-k8s cluster (Talos + vcluster + Keycloak OIDC).
| Document | Description | Last Reviewed |
|---|---|---|
k8s/docs/README.md |
Index + TL;DR of all k8s decisions | 2026-07-28 |
k8s/docs/DISTRO-DECISION.md |
Talos vs k3s analysis. Decision: k3s for regular R&D cluster; Talos preserved for future ITAR/classified | 2026-07-28 |
k8s/docs/ARCHITECTURE.md |
Target architecture: control plane, network, identity, storage, tenant isolation, bootstrap, DR. Mermaid diagrams | 2026-07-28 |
Proxmox Cluster (proxmox/)
Fleet operations, hardware, performance tuning, storage architecture.
| Document | Description | Last Reviewed |
|---|---|---|
proxmox/docs/NETWORK-TOPOLOGY.md |
Full network reference: Mermaid topology diagrams, complete switch port maps, VLAN/subnet map, cross-rack trunk analysis, NFS data-flow, per-host NIC reference | 2026-07-30 |
proxmox/docs/STORAGE-ARCHITECTURE.md |
Full storage reference: tier definitions, physical disk inventory (all 14 disks), NFS export/mount map, per-spindle VM placement, capacity summary | 2026-07-30 |
proxmox/docs/HOST-REFERENCE.md |
Per-host reference: hardware, network, storage, tuning, role, running VMs for all 7 nodes | 2026-07-30 |
proxmox/docs/VM-INVENTORY.md |
Complete VM catalog: placement diagram, all 28 running VMs with disk/CPU/RAM/config, optimization findings (cache mode, CPU type, qga audit), stopped VMs | 2026-07-30 |
proxmox/docs/PROJECT.md |
Comprehensive fleet report: 7 hosts, VM inventory, storage, recommendations | 2026-07-27 |
proxmox/docs/CAPACITY-GOALS.md |
Authoritative capacity targets (80% RAM, ~50% idle CPU) + workload placement model (compute / RackRental / infra) | 2026-07-29 |
proxmox/docs/AUDIT-2026-07-30.md |
Prior audit (network + storage + compute + switches). Superseded by AUDIT-2026-08-05 | 2026-07-30 |
proxmox/docs/AUDIT-2026-08-05.md |
Current & authoritative. Read-only ground-truth via nmap/SNMP/SSH/API: 4 switches up / 1 down, 63 VMs, 167 zones, 753 DHCP leases, k8s DOWN, netinfra-02 wiped, repo restructure, 3-tier Tailscale fleet | 2026-08-05 |
proxmox/docs/DRIFT-2026-07-30.md |
Fleet drift report. Executive briefing of package/service/tuning/security inconsistencies across all 7 hosts, with detailed appendixes | 2026-07-30 |
proxmox/docs/TODO.md |
Pending physical hardware work (tsys2/4/5 Friday plan) | 2026-07-27 |
proxmox/docs/NAMING-POLICY.md |
Canonical naming policy: VM name = source of truth (DNS/Tailscale/monitoring must match) | 2026-07-31 |
proxmox/docs/PHYSICAL-SYSTEMS.md |
Physical infrastructure: Pi's, network devices, UniFi APs, SNMP-discovered hosts | 2026-07-31 |
proxmox/docs/K8S.md |
Kubernetes storage/host analysis (predecessor to k8s/) |
2026-07-27 |
Server Build (docs/server-build/)
Server provisioning, security hardening, DNS/NTP configuration.
| Document | Description | Last Reviewed |
|---|---|---|
docs/server-build/SECURITY.md |
Security architecture: SSH hardening, 2FA, SCAP-STIG, Wazuh, auditd | 2026-07-25 |
docs/server-build/tailscale.md |
Tailscale vs managed DNS analysis (RESOLVED — netinfra pair serves knel.net) | 2026-07-28 |
docs/server-build/DEPLOYMENT.md |
Server deployment procedures, package lists, config flow | 2026-07-25 |
docs/server-build/TSYS-2FA-GUIDE.md |
End-user guide for 2FA setup (SSH, Cockpit, Webmin) | 2026-07-25 |
docs/server-build/DEVELOPMENT-GUIDELINES.md |
Coding standards, commit conventions, script patterns | 2026-07-25 |
Operational Guides (outside docs/)
| Document | Description | Last Reviewed |
|---|---|---|
../netinfra/dhcp-migration.md |
DHCP migration: pfv-netboot → netinfra-01/02 (ISC failover-peer, COMPLETE) | 2026-07-29 |
../awx/README.md |
Ansible AWX deployment on tsys-awx (k3s + AWX Operator 2.19.1, v24.6.1) | 2026-07-29 |
../dcinfra/powerman/README.md |
Cyclades PM10i PDU management via powerman on pfv-tsys1 | 2026-07-28 |
../dcinfra/console/README.md |
Serial console management (ser2net telnet rfc2217 + conman) for 7 network switches on pfv-tsys4 | 2026-07-29 |
../dcinfra/ups/README.md |
UPS management (NUT) for APC Smart-UPS C 1500 on pfv-tsys1 — upsd on Tailscale, HA integration | 2026-07-30 |
../k8s/README.md |
k3s cluster setup scripts: wipe, bootstrap, taint, verify (3-node HA over Tailscale) | 2026-07-28 |
../netinfra/dns-cluster-setup/README.md |
Technitium DNS cluster setup: export, deploy, cluster, verify | 2026-07-28 |
../tests/README.md |
Test suite documentation: unit, security, validation tests | 2026-07-28 |
../netinfra/pfv-netinfra-setup.md |
pfv-netinfra-01/02 initial setup guide | 2026-07-27 |
../netinfra/pihole/README.md |
Pi-hole recursive DNS on netinfra-01/02: shm_size fix, gravity-validate.sh, healthcheck, autoheal (defense-in-depth vs gravity.db corruption) | 2026-08-06 |
../netinfra/pfv-netboot-setup.md |
pfv-netboot reference node setup | 2026-07-27 |
Archive (archive/)
Historical AI reviews, completed task lists, and pre-refactor examples. Read-only context — do not update; link to active docs instead.
| Document | Description |
|---|---|
archive/CODE-REVIEW-FINDINGS.md |
Early code review findings (most issues now fixed) |
archive/REFACTORING-EXAMPLES.md |
Pre-refactor code patterns (historical "before" examples) |
archive/Claude-Review.md |
Claude's initial code review |
archive/AIReview-QWEN.md |
Qwen AI review |
archive/AiOverview-Gemini.md |
Gemini project overview |
archive/AiOverview-OpenCode.md |
OpenCode project overview |
archive/AiSecurityAudit-Gemini.md |
Gemini security audit |
archive/charles-todo.md |
Charles's early task list (completed) |
archive/claude-todo.md |
Claude's early task list (completed) |
External Tracking
| Resource | Description |
|---|---|
| Redmine | System of record for all work. Version: Potential to Kinetic Ready (due 2026-09-30). Project: Technology & Facility Services (id 55) |
| Gitea | Source code repository |
Top-Level Files
| File | Description |
|---|---|
../AGENTS.md |
Agent operating instructions (repo layout, git policy, Redmine tracking, gardening protocol) |
../STATUS.md |
Ticket index + infrastructure summary (read-only snapshot; work tracked in Redmine) |
../README.md |
Project overview and quick start |
../LICENSE |
License |
Agent Gardening Protocol
When making changes to this repo, agents MUST:
- Update Redmine tickets — all work status, completion, and issue tracking lives in Redmine, not in repo files.
- Update
../STATUS.mdif the infrastructure summary or ticket index needs refreshing (read-only snapshot only). - Update this file (
docmap.md) if a doc is added, removed, or has a substantive content change. Update the "Last Reviewed" date. - Verify cross-references — any new
.mdfile must be linked from at least one existing doc or this map. - Check for stale paths — after any directory rename or file move,
grep -rn 'old/path' --include='*.md'and fix all references. - Keep code and docs in sync — if you change a script's interface, behavior, or location, update every doc that references it in the same commit.