Scaffold incremental Terraform foundations for docker and proxmox

infrastructure/terraform/README.md

@@ -0,0 +1,38 @@
+# Terraform foundations
+
+This directory introduces Terraform in a conservative, incremental way for this homelab repo.
+
+## Purpose in this repository
+
+Terraform is used here to **document and gradually adopt management** of existing infrastructure without disrupting running services.
+
+Current intent:
+- Start with imported live Docker resources so infrastructure is visible and reproducible in code.
+- Add Proxmox inventory/configuration later once provider details and import IDs are confirmed.
+- Keep this phase local-state and learning-oriented (no remote backend yet).
+
+## Tool boundaries
+
+- **Docker Compose**: day-to-day application/service runtime definitions already used by this repo.
+- **Terraform**: infrastructure state capture and controlled resource management (starting with imports).
+- **Ansible**: follow-on host/configuration management after Terraform inventory and targets are stable.
+- **NixOS**: host OS/system-level declarative configuration, separate from per-service compose workflows.
+
+## Layout
+
+- `docker/`: Docker provider scaffold and incremental import workflow.
+- `proxmox/`: placeholder scaffold for later Proxmox adoption.
+- `modules/`: placeholder module directories for future shared patterns.
+
+## Incremental adoption plan
+
+1. Import Docker containers one-by-one into Terraform state.
+2. Reconcile and stabilize Docker Terraform configuration until `terraform plan` is clean.
+3. Add Proxmox inventory/configuration scaffolding and imports later.
+4. Introduce Ansible workflow after Terraform-managed inventory is trustworthy.
+
+## Safety notes
+
+- State files are intentionally gitignored for safety and portability.
+- Do **not** run `terraform apply` until imported resources are fully reconciled and plan output is reviewed as no-op for intended targets.
+- No remote backend is configured yet by design.