113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
# CLAUDE.md - Project context for AI assistants
|
|
|
|
## What this repository is
|
|
|
|
A collection of peripheral tools, scripts, and snippets for working with
|
|
Incus, IncusOS, and the broader ecosystem (Operations Center, Migration Manager).
|
|
Primarily targeting home lab environments but aiming for production-quality scripts.
|
|
|
|
## Repository structure
|
|
|
|
```
|
|
incus-contrib/
|
|
├── CLAUDE.md # This file -- behavioral rules + project overview
|
|
├── .claude/rules/ # Topic-specific context (auto-loaded by paths:)
|
|
├── .claude/skills/ # Slash commands: /screenshot, /proxmox-api
|
|
├── README.md # Main overview
|
|
├── .gitignore
|
|
├── ansible/ # Ansible playbooks for AWX/Aether lifecycle hooks
|
|
│ ├── ansible.cfg
|
|
│ └── playbooks/
|
|
│ ├── post-deploy.yml # Runs after Aether creates an instance
|
|
│ └── decommission.yml # Runs before Aether deletes an instance
|
|
├── incusos/ # IncusOS installation tooling
|
|
│ ├── README.md
|
|
│ ├── incusos-iso # ISO/IMG builder (wraps flasher-tool)
|
|
│ ├── incusos-seed # Seed archive generator (Linux + macOS)
|
|
│ ├── incusos-proxmox # Declarative Proxmox VM deployment + lab lifecycle
|
|
│ ├── deploy-awx # AWX deployment + management on Incus cluster
|
|
│ ├── awx-manifests/ # K8s manifests for AWX Operator + instance
|
|
│ ├── helpers/
|
|
│ │ ├── proxmox-screenshot # VMID -> PNG console screenshot
|
|
│ │ └── proxmox-api # Authenticated API calls (handles ! in token)
|
|
│ ├── lab-test # Guided lab validation (12 test phases)
|
|
│ ├── observe-deploy # Single-VM deploy with console screenshots
|
|
│ ├── proxmox.yaml # Proxmox connection (gitignored)
|
|
│ ├── TESTING.md
|
|
│ └── examples/ # Example seed + Proxmox YAML files
|
|
├── env # PROXMOX_TOKEN_SECRET + PROXMOX_ROOT_PASSWORD (gitignored)
|
|
└── notes/ # Reference guides (clustering, networking, OC, AWX, etc.)
|
|
```
|
|
|
|
## Capabilities you have
|
|
|
|
### Proxmox VM screenshots
|
|
Take console screenshots during deploys to see boot progress or errors:
|
|
```
|
|
incusos/helpers/proxmox-screenshot VMID [/tmp/output.png]
|
|
```
|
|
Use the Read tool on the PNG to view it. **USE THIS PROACTIVELY** during
|
|
deploy scenarios to monitor boot progress, diagnose hangs, and verify installs.
|
|
|
|
### Proxmox API calls
|
|
Make authenticated API calls (handles the `!` in `automation@pve!deploy`):
|
|
```
|
|
incusos/helpers/proxmox-api GET /nodes/pve/qemu/900/status/current --json
|
|
incusos/helpers/proxmox-api GET /nodes/pve/status --json
|
|
incusos/helpers/proxmox-api POST /nodes/pve/qemu/900/status/stop
|
|
```
|
|
|
|
### Live AWX job output
|
|
Capture output while a job is running (don't just poll status):
|
|
```bash
|
|
curl -sk http://192.168.102.161:30080/api/v2/jobs/{JOB_ID}/stdout/?format=txt \
|
|
-H "Authorization: Bearer $AWX_TOKEN"
|
|
```
|
|
|
|
## Critical safety rules
|
|
|
|
- **Proxmox SSH is screenshots-only.** Full rules in `.claude/rules/proxmox-ssh-rules.md`.
|
|
- **Never hard-stop VMs during first boot** -- corrupts TPM permanently.
|
|
- **Boot timeout is 180s** -- do not reduce (sysext download takes 30-120s).
|
|
- **No `force_reboot` in seeds for Proxmox** -- causes crontab race condition.
|
|
- **VMID ranges**: 400-499 (OC), 800-809 (single), 900-939 (clusters).
|
|
|
|
## Coding conventions
|
|
|
|
- **Shell**: bash with `set -euo pipefail`
|
|
- **Arithmetic**: `var=$((var + 1))` not `((var++))` (set -e safety)
|
|
- **Colors**: support `NO_COLOR=1` and `TERM=dumb`; use `setup_colors()` pattern
|
|
- **Flags**: both short (`-d`) and long (`--defaults`)
|
|
- **Defaults**: useful behavior with zero flags
|
|
- **Dry run**: all scripts support `--dry-run`
|
|
- **Cert detection**: files on disk first (`~/.config/incus/client.crt`), CLI second
|
|
- **Errors**: include actionable remediation steps
|
|
- **No hardcoded package managers**: say "install the Incus client" with a link
|
|
|
|
## Technical context loading
|
|
|
|
Detailed technical context loads automatically from `.claude/rules/` based on
|
|
which files are being edited:
|
|
|
|
| Rule file | Loads when editing |
|
|
|---|---|
|
|
| `incusos-scripts.md` | incusos-iso, incusos-seed, incusos-proxmox, helpers |
|
|
| `proxmox-deployment.md` | incusos-proxmox, observe-deploy, helpers, examples |
|
|
| `clustering.md` | lab-test, incusos-proxmox, clustering/production guides |
|
|
| `operations-center.md` | OC guide, incusos-proxmox, OC example configs |
|
|
| `networking-storage.md` | networking, storage, migration, UTM guides |
|
|
| `awx-integration.md` | ansible/, deploy-awx, awx-manifests, AWX guide |
|
|
| `proxmox-ssh-rules.md` | **Always loaded** (no paths filter) |
|
|
| `lab-infrastructure.md` | incusos-proxmox, lab-test, examples |
|
|
|
|
For deep reference, see the guides in `notes/`.
|
|
|
|
## Git workflow
|
|
|
|
- **Main branch**: `master`
|
|
- **Remotes**:
|
|
- `origin`: `ssh://git@192.168.1.200:2222/maarten/incus-contrib.git` (private Gitea)
|
|
- `aether`: `_gitea@code.sovereignprivatecloud.nl:maarten/incus-contrib.git`
|
|
- Push to **both remotes** when committing
|
|
- Development happens on feature branches
|