Scaffold incremental Terraform foundations for docker and proxmox

infrastructure/terraform/docker/README.md

@@ -0,0 +1,48 @@
+# Docker Terraform scaffold
+
+This directory is for **incremental, import-first Terraform adoption** of existing Docker containers.
+
+## What this directory is for
+
+- Document existing live Docker resources in Terraform.
+- Import containers one-by-one.
+- Reconcile Terraform code with real runtime values until plan is clean.
+
+## Initialize
+
+From this directory:
+
+```bash
+terraform init
+```
+
+## Safe incremental import workflow
+
+1. Add one `docker_container` resource block in `main.tf` for an already-running container.
+2. Import it into state:
+
+   ```bash
+   terraform import docker_container.<resource_name> <container_id_or_container_name>
+   ```
+
+3. Inspect imported state:
+
+   ```bash
+   terraform state show docker_container.<resource_name>
+   ```
+
+4. Copy required/meaningful arguments from state output into `main.tf`.
+5. Run `terraform plan` and refine until there are no unintended changes.
+
+## Reconciliation guidance
+
+- Keep one resource block per imported container.
+- Prefer explicit values for arguments that affect recreation.
+- Avoid broad changes; reconcile each container independently.
+- Do **not** run `terraform apply` until plan output is intentionally clean.
+
+## State and secrets handling
+
+- State files are ignored via `../.gitignore` because they may contain environment-specific metadata.
+- Do not commit real `.tfvars` files with machine-specific values.
+- Use `terraform.tfvars.example` as a safe starter template.