beatzaplenty/docker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: overhaul repo documentation and workflow guides

Browse Source
This commit is contained in:
beatz174-bit
2026-04-21 09:28:55 +10:00
parent 020d6ecb79
commit c7dd9f2229
13 changed files with 539 additions and 174 deletions
Download Patch File Download Diff File Expand all files Collapse all files
infrastructure/terraform/README.md
+41 -35
View File
@@ -1,54 +1,60 @@
# Terraform foundations
# Terraform in This Repository
This directory introduces Terraform in a conservative, incremental way for this homelab repo.
Terraform here is used as a **structured inventory + reconciliation layer** for existing infrastructure.
## Purpose in this repository
It does **not** replace Docker Compose as runtime deployment authority.
Terraform is used here to **document and gradually adopt management** of existing infrastructure without disrupting running services.
## What Terraform is currently used for
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).
- Proxmox VM import/reconciliation for existing VMs.
- Physical host metadata represented in Terraform locals/outputs.
- Select Docker container mirror resources for documentation-oriented tracking.
- Outputs that can support documentation and later downstream tooling.
## Tool boundaries
## What Terraform is not used for (today)
- **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.
- Replacing `services-up.sh` / Compose for day-to-day app runtime orchestration.
- Broad, immediate greenfield provisioning of the whole stack.
- Casual `apply` operations across all infrastructure.
## Layout
## Directory map
- `docker/`: Docker provider scaffold and incremental import workflow.
- `proxmox/`: placeholder scaffold for later Proxmox adoption.
- `modules/`: placeholder module directories for future shared patterns.
- `proxmox/` — imported/reconciled VM resources and host metadata outputs.
- `docker/` — selective Docker container import/mirror resources.
- `bootstrap/` — backend/provider bootstrap scaffolding.
- `modules/` — placeholder module directories for future stable abstractions.
- `scripts/reconcile_from_plan.sh` — helper to convert generated plan config into reviewable draft files.
## Incremental adoption plan
## Brownfield workflow standard
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.
1. Import one existing object.
2. Inspect state/plan output.
3. Reconcile hand-maintained Terraform code.
4. Keep `ignore_changes` narrowly scoped.
5. Iterate to no-op/sane plan for intended scope.
6. Avoid casual apply.
See detailed steps in [../../docs/terraform-workflows.md](../../docs/terraform-workflows.md).
## Plan-to-config helper script
## Safe validation commands
Use `scripts/reconcile_from_plan.sh` to automate Terraform configuration generation from `terraform plan` output (via Terraform's `-generate-config-out`).
From a Terraform module directory (for example `infrastructure/terraform/docker`):
From Terraform directories, preferred checks are:
```bash
../../scripts/reconcile_from_plan.sh --output-file zz_generated_from_plan.auto.tf
terraform fmt -check -recursive
terraform init -backend=false -input=false
terraform validate
```
Notes:
- Best used with an import-first workflow that already contains `import {}` blocks.
- The script writes generated config into a `.auto.tf` file and runs `terraform fmt` on it.
- Always review generated arguments before apply.
## Secrets and state safety
## Safety notes
- Do not commit `.tfstate*`.
- Do not commit real `.tfvars` values.
- Keep credentials in local, untracked inputs only.
- 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.
## Related docs
- [../../docs/source-of-truth.md](../../docs/source-of-truth.md)
- [../../docs/infrastructure-inventory.md](../../docs/infrastructure-inventory.md)
- [docker/README.md](docker/README.md)
- [proxmox/README.md](proxmox/README.md)
infrastructure/terraform/docker/README.md
+29 -34
View File
@@ -1,48 +1,43 @@
# Docker Terraform scaffold
# Terraform Docker Mirror Layer
This directory is for **incremental, import-first Terraform adoption** of existing Docker containers.
This directory tracks selected existing Docker containers in Terraform for inventory/documentation purposes.
## What this directory is for
## Purpose
- Document existing live Docker resources in Terraform.
- Import containers one-by-one.
- Reconcile Terraform code with real runtime values until plan is clean.
- Mirror specific running containers as Terraform resources.
- Reconcile imported state into maintainable code.
- Produce structured outputs/reminders that support documentation workflows.
## Initialize
## Boundary with Docker Compose
From this directory:
Docker Compose + `services-up.sh` remain runtime composition authority.
```bash
terraform init
```
Terraform resources here are **not** the primary day-to-day deployment mechanism for app services.
## Safe incremental import workflow
## Current contents
1. Add one `docker_container` resource block in `main.tf` for an already-running container.
2. Import it into state:
- `main.tf` — import-first workflow notes and minimal scaffolding.
- `searxng-webapp.tf` — generated/reconciled example container resource.
- `outputs.tf` — documentation-oriented reminders/outputs.
- `terraform.tfvars.example` — safe template for local values.
```bash
terraform import docker_container.<resource_name> <container_id_or_container_name>
```
## Import/reconciliation workflow
3. Inspect imported state:
1. Start with one existing container.
2. Import with `import {}` block or `terraform import`.
3. Inspect state / generated config.
4. Reduce generated attributes to meaningful, stable arguments.
5. Keep lifecycle `ignore_changes` narrow and justified.
6. Iterate until plan is clean for the intended resource.
```bash
terraform state show docker_container.<resource_name>
```
## Guardrails
4. Copy required/meaningful arguments from state output into `main.tf`.
5. Run `terraform plan` and refine until there are no unintended changes.
- Do not attempt to mirror all containers in one pass.
- Do not commit local state or real credentials.
- Treat generated config as draft input that needs review.
## Reconciliation guidance
## Related docs
- 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.
- [../README.md](../README.md)
- [../../../docs/source-of-truth.md](../../../docs/source-of-truth.md)
- [../../../docs/terraform-workflows.md](../../../docs/terraform-workflows.md)
infrastructure/terraform/proxmox/README.md
+31 -23
View File
@@ -1,36 +1,44 @@
# Proxmox Terraform scaffold
# Terraform Proxmox Inventory Layer
This directory is a **placeholder scaffold** for future Proxmox Terraform adoption.
This directory codifies existing Proxmox infrastructure using an import-first reconciliation model.
## What this directory is for
## Purpose
- Prepare provider/version/variable structure now.
- Delay real Proxmox resource management until import strategy is validated.
- Track existing Proxmox VMs in Terraform.
- Reconcile imported VM configuration into maintainable, explicit files.
- Represent physical host metadata as structured Terraform locals/outputs.
- Support documentation inventory and future downstream tooling.
## Initialize
## Current repository status
From this directory:
This directory already contains imported/reconciled VM resources (for example `docker`, `server-nixos`, `nix-cache`, `pbs`, `pihole`) plus host metadata locals/outputs.
```bash
terraform init
```
This means it is no longer just a scaffold; treat it as active infrastructure inventory code.
## Current status
## Workflow standard (brownfield)
- No live Proxmox resources are defined yet.
- Provider auth variables are placeholders only.
- Import IDs and resource schemas must be verified against provider docs before adding resources.
1. Import one existing VM at a time.
2. Confirm provider-specific import ID format.
3. Inspect state/plan details.
4. Keep hand-maintained `.tf` files focused and readable.
5. Use `ignore_changes` only where drift noise is unavoidable.
6. Stop when plan is sane/no-op for intended scope.
## Future safe workflow
## File organization expectations
1. Add one resource block for an existing VM/object.
2. Import it with the provider-specific ID format.
3. Inspect with `terraform state show`.
4. Reconcile `.tf` arguments until `terraform plan` is clean.
5. Repeat incrementally.
- Prefer one-resource-per-file patterns when practical.
- Keep shared metadata in `locals`/outputs with clear descriptions.
- Keep generated comments/config under ongoing cleanup rather than assuming generated output is final.
## Safety notes
- Do not commit real credentials in `.tf` files or tracked `.tfvars`.
- State files are ignored by the Terraform-level `.gitignore`.
- Do not run `terraform apply` until plan is intentionally no-op for existing resources.
- Do not run broad applies casually.
- Do not commit real credentials or `.tfstate*`.
- Keep changes incremental and reviewable.
## Related docs
- [../README.md](../README.md)
- [../../../docs/source-of-truth.md](../../../docs/source-of-truth.md)
- [../../../docs/terraform-workflows.md](../../../docs/terraform-workflows.md)
- [../../../docs/infrastructure-inventory.md](../../../docs/infrastructure-inventory.md)