Operations

The common flows, and which repo each step happens in. Details live with the code — each stack's justfile is self-documenting (just --list).

Reserve an IP / stand up a new service instance

1. Registry first (jacaranda-inventory): registry reserve <service> --vlan <vlan> --hostname <h> --env <e> — picks the next free IP in the service's declared range, assigns the VMID, places it on a Proxmox node. Commit: reserve: <hostname> (<ip>) on <vlan>.
2. Terraform (jacaranda-homelab or foundation): the stack reads the registry's YAML for octets and hostnames — nothing is retyped.
3. DNS: run foundation's full-dns-sync (or the env-scoped register-foundation-dns recipe) to publish the new records to every Pi-hole.
4. Deploys go reserved → active via registry set-status once the applier has run.

Change or add DNS

Edit intent in the registry — a service allocation, a standalone A record, or a CNAME (which must target a declared A record). Run registry check, commit, then full-dns-sync. Never edit Pi-hole directly; anything added by hand is drift and will not survive the next sync.

Decommission

registry release <service> --ip <ip> marks the allocation retired (never deleted) and starts the reuse cooldown. Tear down the stack with its destroy recipe, then sync DNS. Retired entries stay in the YAML on purpose — DNS caches and ARP tables don't forget immediately.

Deploy a hosted app

Each app stack in hosted-apps/ follows the same recipe surface:

just <env>::plan      # OpenTofu plan via the state wrapper
just <env>::apply     # create/update the LXC (confirm-gated)
just <env>::deploy    # Ansible: configure + run the app
just <env>::validate  # health checks

App images come from the app's own source repo; the stack here only knows the image reference, the registry-derived addresses, and the secrets paths.

Rebuild the world (disaster order)

1. Physical hosts up (Proxmox cluster).
2. Foundation, phase 1 — pihole → secrets-server → step-ca, on hardcoded IPs with bootstrap TLS.
3. Foundation, phase 2 (finalize) — DNS registration, TLS switchover to step-ca, SSH host certs, SSH CA trust.
4. Platform tier, then hosted apps, from the monorepo.

The whole point of foundation's standalone-repo status is that steps 2–3 need nothing from the monorepo.

Conventions cheat-sheet

Thing	Convention
Hostname	env.instance.service, FQDN = <hostname>.<vlan zone>
VMID	1000 + host octet
Commit (registry)	reserve: / retire: / new-service: — intent, not mechanics
State path	<tier>/<service>/<env>/terraform.tfstate on the repo's tfstate branch
Module pin	git::ssh://…//<module>?ref=vX.Y.Z — exact tag
Secrets	op read in justfiles only