KNEL/PFVCluster
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: end-to-end gardening — links, stale refs, tailscale.md update

Browse Source 
Comprehensive documentation gardening across the merged repo:

- tailscale.md: fully rewritten with current ground truth. The netinfra
  pair now runs production Technitium with all knel.net records
  replicated. Both LAN IPs resolve knel.net device names and recurse
  externally. The old "NXDOMAIN / zone is stale" findings are replaced
  with the resolved state and current recommendations.
- AGENTS.md: rewritten with Gitea-compatible clickable relative links
  to all key scripts and docs. Autonomous commit/push policy
  prominently documented. SSH user corrected to localuser.
- README.md: directory table and docs table now use clickable links.
- All .md cross-references converted to Gitea-renderable relative links.
- Stale path references (ProjectCode/, Project-Tests/, ProjectDocs/)
  updated to current names (provisioning/, tests/) across all docs.
- Stale repo name "FetchApply" / "KNELServerBuild" updated to
  "PFVCluster" in actionable docs; historical AI-review docs tagged
  with an HTML comment notice.
- REFACTORING-EXAMPLES.md: tagged as historical (pre-refactor patterns).
- tests/README.md, dns-cluster-setup/README.md, docs/DEPLOYMENT.md,
  docs/SECURITY.md: path references fixed to current structure.

🤖 Generated with [Crush](https://github.com/charmassociates/crush)

Assisted-by: GLM-5 via Crush <crush@charm.land>
This commit is contained in:
mrcharles
2026-07-28 11:28:52 -05:00
parent c2b592a66b
commit a7fbad60ab
21 changed files with 224 additions and 295 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+46 -22
View File
@@ -1,10 +1,10 @@
# Agent Guidelines
This repo combines two formerly-separate projects:
- **Server provisioning** (formerly KNELServerBuild): `provisioning/`, `tests/`,
`vendor/`, `dns-cluster-setup/`
- **Proxmox cluster ops** (formerly PFVCluster/perfopt): `perf/`, `netinfra/`,
`switches/`, `returned-logs/`
- **Server provisioning** (formerly KNELServerBuild): [`provisioning/`](provisioning/),
[`tests/`](tests/), [`vendor/`](vendor/), [`dns-cluster-setup/`](dns-cluster-setup/)
- **Proxmox cluster ops** (formerly PFVCluster/perfopt): [`perf/`](perf/),
[`netinfra/`](netinfra/), [`switches/`](switches/)
## Repository Layout
@@ -16,16 +16,19 @@ This repo combines two formerly-separate projects:
via `BASH_SOURCE` and compute `PROJECT_ROOT_PATH` from it. They must never
depend on the current working directory. Run from anywhere.
- **Local config files are the source of truth**: Configs in
`provisioning/ConfigFiles/` are read with `cat`/`cp`. Do NOT re-introduce
`curl ${DL_ROOT}/...` downloads — that CDN is deprecated.
[`provisioning/ConfigFiles/`](provisioning/ConfigFiles/) are read with
`cat`/`cp`. Do NOT re-introduce `curl ${DL_ROOT}/...` downloads — that CDN
is deprecated.
- **Non-bash agents**: Some files under `provisioning/Agents/` carry a `.sh`
extension but are PHP (e.g. `mysql.sh`, shebang `#!/usr/bin/php`). Syntax
checkers must skip these.
- **Proxmox hosts** are standalone installs managed via **PDM** (Proxmox
Datacenter Manager). SSH keys deployed to root on all hosts.
Datacenter Manager). SSH keys deployed to `localuser` with passwordless sudo
on all hosts.
- **SSH in Crush**: Direct ssh/scp is blocked in the Crush bash environment.
Use the wrapper scripts: `tests/remote.sh`, `dns-cluster-setup/remote-dns.sh`,
or the `deploy-check.sh` / `deploy-tuning.sh` patterns.
Use the wrapper scripts: [`tests/remote.sh`](tests/remote.sh),
[`dns-cluster-setup/remote-dns.sh`](dns-cluster-setup/remote-dns.sh),
or the `perf/deploy-check.sh` / `perf/deploy-tuning.sh` patterns.
## Git Commit Requirements
@@ -37,27 +40,48 @@ This repo combines two formerly-separate projects:
## Autonomous Git Workflow
Agents are authorized to commit AND push autonomously. After each logical unit
of work: stage, commit, push to `origin/main`. Group changes so each commit is
coherent on its own.
**Agents are authorized to commit AND push autonomously — do not wait to be
asked.** After each logical unit of work:
1. Stage only the files belonging to that logical change.
2. Commit with a conventional, well-formed message.
3. Push to `origin` (`git push`). The branch tracks `origin/main`.
4. Repeat per logical unit.
Group changes so each commit is coherent on its own (a reader should
understand the commit without seeing the others). Never batch unrelated
changes into one commit.
## Key scripts
| Script | Purpose |
|--------|---------|
| `provisioning/SetupNewSystem.sh` | Full server provisioning (packages, hardening, 2FA) |
| `tests/vm-validation.sh` | End-to-end deploy + validate on sandbox VM |
| `tests/run-tests.sh` | Project test suite (unit/security/validation) |
| `dns-cluster-setup/setup.sh` | Technitium DNS cluster replication |
| `perf/deploy-check.sh` | Deploy read-only data collector to hosts |
| `perf/deploy-tuning.sh` | Deploy perf tunings to hosts |
| `perf/validate-fixes.sh` | Validate applied tuning changes |
| `perf/iperf-full-matrix.sh` | Full iperf throughput suite |
| [`provisioning/SetupNewSystem.sh`](provisioning/SetupNewSystem.sh) | Full server provisioning (packages, hardening, 2FA) |
| [`tests/vm-validation.sh`](tests/vm-validation.sh) | End-to-end deploy + validate on sandbox VM |
| [`tests/run-tests.sh`](tests/run-tests.sh) | Project test suite (unit/security/validation) |
| [`dns-cluster-setup/setup.sh`](dns-cluster-setup/setup.sh) | Technitium DNS cluster replication |
| [`perf/deploy-check.sh`](perf/deploy-check.sh) | Deploy read-only data collector to hosts |
| [`perf/deploy-tuning.sh`](perf/deploy-tuning.sh) | Deploy perf tunings to hosts |
| [`perf/validate-fixes.sh`](perf/validate-fixes.sh) | Validate applied tuning changes |
| [`perf/iperf-full-matrix.sh`](perf/iperf-full-matrix.sh) | Full iperf throughput suite |
## 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 |
## Project context
This is a solo-founder R&D Proxmox cluster in a private residence. Shoestring
budget. Redundancy is not a concern for the R&D cluster. Backups DO matter
(PBS in use). Production lives on a VPS in Reston VA (Cloudron). See
`docs/PROJECT.md` for the comprehensive fleet report and `docs/TODO.md` for
pending hardware work.
[`docs/PROJECT.md`](docs/PROJECT.md) for the comprehensive fleet report and
[`docs/TODO.md`](docs/TODO.md) for pending hardware work.