mrcharles
c14b48f39e
Merge the KNELServerBuild repository (server provisioning, security hardening, DNS cluster setup, test suite) into PFVCluster (Proxmox cluster ops, performance tuning, fleet audit). Both histories are preserved via --allow-unrelated-histories. The two repos had no source-file collisions; only AGENTS.md and .gitignore conflicted (both resolved by merging content from both). Directory reorganization and doc gardening will follow in subsequent commits. 🤖 Generated with [Crush](https://github.com/charmassociates/crush) Assisted-by: GLM-5 via Crush <crush@charm.land>
64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# 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/`
|
|
|
|
## 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/` 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.
|
|
- **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.
|
|
|
|
## 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. After each logical unit
|
|
of work: stage, commit, push to `origin/main`. Group changes so each commit is
|
|
coherent on its own.
|
|
|
|
## 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 |
|
|
|
|
## 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.
|