mrcharles
a7fbad60ab
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>
88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
# Agent Guidelines
|
|
|
|
This repo combines two formerly-separate projects:
|
|
- **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
|
|
|
|
- **Vendored framework**: `KNELShellFramework` lives at
|
|
`vendor/git@git.knownelement.com/29418/KNEL/KNELShellFramework/`. Its includes
|
|
are under `Framework-Includes/` there. Never assume `./Framework-Includes`
|
|
exists relative to the repo root.
|
|
- **Self-locating scripts**: All provisioning scripts derive their own location
|
|
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/`](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 `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`](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
|
|
|
|
1. **Commit atomically**: each logical change its own commit.
|
|
2. **Conventional commit format**: `feat(scope): desc`, `fix(scope): desc`,
|
|
`docs: desc`, `refactor(scope): desc`, `test(scope): desc`, `chore: desc`.
|
|
3. **Verbose messages**: title (50 chars max), blank line, body explaining
|
|
WHAT and WHY, footer with attribution.
|
|
|
|
## Autonomous Git Workflow
|
|
|
|
**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`](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`](docs/PROJECT.md) for the comprehensive fleet report and
|
|
[`docs/TODO.md`](docs/TODO.md) for pending hardware work.
|