# incus-contrib

Peripheral tools, snippets, and scripts for working with [Incus](https://linuxcontainers.org/incus/),
[IncusOS](https://linuxcontainers.org/incus-os/), and the broader ecosystem.

Primarily aimed at home lab environments but useful in production as well.

## Contents

### [`bin/`](bin/)

Reusable scripts for building IncusOS installation media, deploying labs,
and managing services:

- **`incusos-iso`** -- Build customized IncusOS ISO/IMG images using the official flasher-tool.
  Supports both architectures (x86_64, aarch64), multiple applications (Incus, Operations Center),
  automatic client certificate injection, and batch generation.

- **`incusos-seed`** -- Generate IncusOS seed archives (tar or FAT image) for installation
  customization. Covers all seed file types: install, applications, Incus preseed,
  Operations Center, network, and update configuration.

- **`incusos-proxmox`** -- Declarative IncusOS deployment on Proxmox VE. Define VMs in
  YAML, and the script handles seed generation, ISO upload, VM creation with correct
  settings (UEFI, TPM 2.0, VirtIO-SCSI), and automated installation.

- **`deploy-awx`** -- Deploy and manage AWX (Ansible automation) on the Incus
  cluster. Handles VM creation, K3s install, AWX Operator deployment, project/template
  configuration, and Aether integration. Requires `--config` for environment settings.

- **`deploy-haproxy`** -- Deploy HA HAProxy load balancing via Aether. Requires
  `--config` for environment settings.

- **`deploy-observability`** -- Deploy Prometheus + Grafana + Loki monitoring stack.
  Requires `--config` for environment settings.

See [`bin/README.md`](bin/README.md) for full documentation.

### [`envs/`](envs/)

Per-environment configuration, secrets, and deployment settings:

- **`beelink/`** -- Beelink mini PC target (LAN, vmbr0, VLAN 69, local-lvm)
- **`hetzner/`** -- Hetzner dedicated server target (WireGuard, vmbr1, local-zfs)
  - **`setup/`** -- Host provisioning guide and interactive setup script

Each environment has: `env` (secrets), `proxmox.yaml` (connection),
lab YAML files (VM definitions), and service configs (`awx.yaml`, `haproxy.yaml`,
`observability.yaml`). See [`envs/README.md`](envs/README.md).

### [`ansible/`](ansible/)

Ansible playbooks for AWX/Aether lifecycle hooks. Playbooks use the Incus REST
API (not SSH) for all instance operations — works regardless of network topology.

- **`playbooks/post-deploy.yml`** -- Runs after Aether creates an instance.
  Configures hostname, installs base packages, sets timezone, logs deployment.
- **`playbooks/decommission.yml`** -- Runs before Aether deletes an instance.
  Graceful service shutdown and decommission logging (best-effort).

### [`notes/`](notes/)

Guides and reference material (roughly in learning order):

- [`clustering-guide.md`](notes/clustering-guide.md) --
  Detailed Incus clustering walkthrough (manual cluster formation via remotes).
- [`operations-center-guide.md`](notes/operations-center-guide.md) --
  Operations Center provisioning, cluster management, and tested limitations.
- [`networking-guide.md`](notes/networking-guide.md) --
  OVN overlay networking tutorial (bridge + OVN + LAN access).
- [`shared-storage-guide.md`](notes/shared-storage-guide.md) --
  iSCSI + lvmcluster shared storage for instant migration.
- [`production-lab-guide.md`](notes/production-lab-guide.md) --
  Manual cluster + OVN + HA workloads (validated end-to-end).
- [`migration-guide.md`](notes/migration-guide.md) --
  Migration paths into Incus from Proxmox, UTM, VMware Fusion, and Docker.
- [`aether-guide.md`](notes/aether-guide.md) --
  Aether management platform: deployment, instance/blueprint lifecycle, API
  reference, OVN recovery, and node resizing.
- [`awx-guide.md`](notes/awx-guide.md) --
  AWX deployment, Aether integration, Ansible playbook patterns, and
  the deploy-awx management script.
- [`incus-version-compatibility.md`](notes/incus-version-compatibility.md) --
  Incus package versions across platforms and install instructions.
- [`utm-support.md`](notes/utm-support.md) --
  Design document for future UTM support on macOS.

## Quick Start

```bash
# Install the flasher-tool (requires Go 1.22+)
go install github.com/lxc/incus-os/incus-osd/cmd/flasher-tool@latest

# Build a default IncusOS ISO with your client cert injected
bin/incusos-iso

# Build for a specific architecture and application
bin/incusos-iso --arch aarch64 --app operations-center --defaults

# Generate all common ISO variants at once
bin/incusos-iso --batch

# Generate a standalone seed archive
bin/incusos-seed --app incus --defaults --output my-seed.tar

# Deploy a cluster on Hetzner
source envs/hetzner/env
bin/incusos-proxmox --proxmox envs/hetzner/proxmox.yaml envs/hetzner/lab-production.yaml

# Deploy AWX on Hetzner
bin/deploy-awx --config envs/hetzner/awx.yaml --deploy

# Deploy HAProxy on beelink
source envs/beelink/env
bin/deploy-haproxy --config envs/beelink/haproxy.yaml --deploy
```

## Requirements

- **Go 1.22+** -- for installing the flasher-tool
- **curl** -- for downloading images from the CDN
- **tar**, **gzip** -- for seed archive creation and image decompression
- **Incus client** (recommended) -- for automatic client certificate detection.
  Works with any version; certificates are read directly from disk.
  See [version compatibility notes](notes/incus-version-compatibility.md)
  for install instructions per platform (macOS, Debian/Ubuntu, Arch).
- **mtools** (optional) -- for creating FAT seed images

## License

MIT