nixos/CLAUDE.md

CLAUDE.md — infrastructure

Safety rules and working context for Claude Code in this repository.

Overall goal

Build a complete, auditable Infrastructure as Code system for the sweet.home homelab. The end state is: every host, service, and network resource is declared in this repo; Terraform captures and detects drift in infrastructure state; Ansible idempotently configures non-NixOS hosts; NixOS flake manages NixOS hosts; automated CI pipelines generate internal and external documentation daily. See docs/internal/implementation-plan.md for the phased roadmap.

Production boundary — confirm before touching

pve1.sweet.home and all VMs/LXCs running on it are production. That includes:

• domain-controller.sweet.home (FreeIPA — if this goes down, auth AND DNS break for everything)
• docker.sweet.home (Nextcloud, Passbolt, Gitea — live data)

Always ask before running any Ansible playbook with --apply or terraform apply against production hosts. Use --check (Ansible) or terraform plan (Terraform) for read-only validation; these are safe to run without asking.

pve-test.sweet.home is the sandbox. VMs and containers on it can be created/destroyed without asking. Node-level config (firewall, SSH, unattended-upgrades) still needs confirmation.

Terraform rules

• Always terraform plan before terraform apply.
• Never commit .tfstate or .tfvars files — they go in .gitignore.
• API tokens and secrets go in terraform.tfvars (git-ignored) or environment variables.
• If plan shows unexpected destruction of real resources, stop and ask.

Ansible rules

• Always use --check --diff before the first real run against any host.
• The proxmox-hardening role is safe to re-run (idempotent). Still confirm first.
• The freeipa role is NOT idempotent end-to-end — ipa-server-install will refuse to run if IPA is already installed (it checks). That's fine; treat it as a guard.
• Never run ansible-playbook against production hosts without a --limit specifier unless running the full site.yml intentionally.

NixOS rules

• The nixos/ subdirectory is a flake. Use nix build ./nixos#<target> to validate before nixos-rebuild switch.
• Secrets are SOPS-encrypted with age. Never decrypt secrets into plaintext in the repo.
• The flake remote URL (used by the Switch-nix alias on NixOS hosts) must be updated to point at the new Gitea URL after migration. See implementation plan Phase 4.

Stacks rules

• Changes to stacks/docker/ or stacks/raspi/ take effect only when manually deployed. No automated apply runs against live containers.
• Test compose changes with docker compose config (validates interpolation) before deploying.
• secrets/stack-secrets.env and secrets/*.txt are git-ignored. Never commit real secrets.

Secrets

• Pre-commit hook (installed by scripts/install-hooks.sh) runs gitleaks before every commit.
• CI also runs gitleaks on push. Both must pass.
• If gitleaks false-positives on a known-safe pattern, add it to .gitleaks.toml allowlist, not to the ignore-next-line comment.

Documentation pipeline

• Internal docs: docs/internal/ — full topology, credentials catalog (names only), runbooks.
• External docs: docs/external/ — sanitized, no IPs, no internal hostnames, no credential refs.
• Generated content lands in docs/generated/ — never edit these files by hand.
• Run ./scripts/docs-build.sh locally to preview before pushing.

Directory notes

• stacks/docker/ and stacks/raspi/ are populated via git subtree — see implementation plan.
• nixos/ is populated via git subtree — the flake works from the subdirectory path.
• terraform/dns/ wraps the Dynu provider. Read-only operations only until credentials are configured.
• ansible/roles/ — each role has a README.md describing variables and expected host state.