docs: add STATUS.md, docmap.md, encode gardening protocol
Restructure top-level to exactly three .md files: - AGENTS.md (agent operating instructions) - README.md (project overview, links to status + docmap) - STATUS.md (living project status, agent-maintained, human read-only) Add docs/docmap.md as the single documentation index/map. All docs are categorized (active, operational guides, historical) with last-reviewed dates. Includes the agent gardening protocol requiring agents to update STATUS.md and docmap.md after every work session. Rewrite AGENTS.md to be lean: points to docmap.md for doc discovery, encodes the automatic gardening protocol (keep docs/code in sync, grep for stale paths after renames, update STATUS.md after infrastructure changes). All references are Gitea-renderable relative links. Simplify README.md: header links to STATUS.md + docmap.md + AGENTS.md, doc table replaced with pointer to docmap.md. 🤖 Generated with [Crush](https://github.com/charmassociates/crush) Assisted-by: GLM-5 via Crush <crush@charm.land>
This commit is contained in:
@@ -1,7 +1,8 @@
|
||||
# PFVCluster
|
||||
|
||||
Unified infrastructure repo for the Known Element Enterprises Proxmox R&D cluster.
|
||||
Combines server provisioning, Proxmox cluster operations, and DNS infrastructure.
|
||||
|
||||
**[→ Current Status](STATUS.md)** · **[→ Documentation Index](docs/docmap.md)** · **[→ Agent Guidelines](AGENTS.md)**
|
||||
|
||||
## Directory Structure
|
||||
|
||||
@@ -13,7 +14,7 @@ Combines server provisioning, Proxmox cluster operations, and DNS infrastructure
|
||||
| [`perf/`](perf/) | Proxmox performance tuning, fleet audit, iperf, switch diagnostics |
|
||||
| [`netinfra/`](netinfra/) | pfv-netinfra-01/02 DNS/NTP setup + audit scripts |
|
||||
| [`switches/`](switches/) | Switch configuration captures |
|
||||
| [`docs/`](docs/) | All documentation |
|
||||
| [`docs/`](docs/) | All documentation ([see docmap](docs/docmap.md)) |
|
||||
| [`vendor/`](vendor/) | Vendored KNELShellFramework |
|
||||
|
||||
## Quick Start
|
||||
@@ -22,50 +23,26 @@ Combines server provisioning, Proxmox cluster operations, and DNS infrastructure
|
||||
```bash
|
||||
sudo bash provisioning/SetupNewSystem.sh
|
||||
```
|
||||
Installs packages, applies security hardening (SSH, SCAP-STIG, 2FA, Wazuh),
|
||||
configures NTP/DNS/SNMP/syslog/postfix.
|
||||
|
||||
### Validate provisioning on the sandbox VM
|
||||
### Validate on the sandbox VM
|
||||
```bash
|
||||
VM_ID=6000 ./tests/vm-validation.sh all
|
||||
```
|
||||
Snapshots, deploys, runs the test suite, auto-rolls back on failure.
|
||||
|
||||
### Run the test suite
|
||||
### Deploy DNS cluster
|
||||
```bash
|
||||
./tests/run-tests.sh all
|
||||
cd dns-cluster-setup/ && ./setup.sh all
|
||||
```
|
||||
|
||||
### Deploy DNS cluster setup
|
||||
### Deploy perf tunings
|
||||
```bash
|
||||
cd dns-cluster-setup/
|
||||
./setup.sh all
|
||||
cd perf/ && ./deploy-tuning.sh
|
||||
```
|
||||
|
||||
### Deploy perf tunings to hosts
|
||||
```bash
|
||||
cd perf/
|
||||
./deploy-check.sh # read-only data collection
|
||||
./deploy-tuning.sh # apply sysctl/tuned/NFS tunings
|
||||
```
|
||||
|
||||
## Key Documentation
|
||||
|
||||
| Doc | Contents |
|
||||
|-----|----------|
|
||||
| [`docs/PROJECT.md`](docs/PROJECT.md) | Comprehensive fleet report (7 hosts, VM inventory, storage) |
|
||||
| [`docs/SECURITY.md`](docs/SECURITY.md) | Security architecture and hardening details |
|
||||
| [`docs/tailscale.md`](docs/tailscale.md) | Tailscale vs managed DNS analysis (resolved) |
|
||||
| [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) | Deployment procedures |
|
||||
| [`docs/TODO.md`](docs/TODO.md) | Pending hardware work (tsys2/4/5) |
|
||||
| [`docs/K8S.md`](docs/K8S.md) | Kubernetes architecture deep-dive |
|
||||
| [`dns-cluster-setup/README.md`](dns-cluster-setup/README.md) | DNS cluster setup guide |
|
||||
| [`tests/README.md`](tests/README.md) | Test suite documentation |
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Proxmox hosts**: 7 standalone PVE installs managed via PDM
|
||||
- **DNS**: Technitium (authoritative) + Pi-hole (recursive) on pfv-netinfra-01/02
|
||||
- **NTP**: pfv-netinfra-01/02 (redundant, LAN IPs)
|
||||
- **NTP**: pfv-netinfra-01/02 (redundant, LAN IPs, stratum 2/3)
|
||||
- **Production**: Cloudron VPS in Reston VA (this cluster is R&D only)
|
||||
- **Backups**: Proxmox Backup Server (PBS)
|
||||
|
||||
Reference in New Issue
Block a user