Restructure infra repo into documentation-first homelab platform#8
Closed
Restructure infra repo into documentation-first homelab platform#8
Conversation
There was a problem hiding this comment.
Pull request overview
This PR pivots the repository into a documentation-first homelab/platform hub (Proxmox → virtualized Kubernetes → Argo CD GitOps, with TrueNAS as a separate storage anchor) while archiving the previous Talos/PXE bare-metal implementation and redacting sensitive operational values.
Changes:
- Introduces a new docs-centric structure (
docs/{vision,inventory,architecture,decisions,runbooks,roadmap,archive}) plus top-level stubs for platform areas (proxmox/,kubernetes/,argocd/,automation/,ai/,scripts/). - Adds foundational documentation: vision, inventories, architecture drafts, bootstrap sequence runbook, roadmap (milestones/backlog/current phase/media migration), and ADRs (ADR-001..ADR-005).
- Archives legacy Talos/PXE Terraform/Talos artifacts under
docs/archive/..., removes the previously liveterraform.auto.tfvars, and adds a redacted sample tfvars in the archive; adds GitHub issue/PR templates.
Reviewed changes
Copilot reviewed 36 out of 68 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| scripts/README.md | Adds scripts area stub and basic hygiene guidelines. |
| proxmox/README.md | Adds Proxmox planning stub. |
| kubernetes/README.md | Adds Kubernetes planning/ops stub for VM-based cluster. |
| infra/live/prod/terraform.auto.tfvars | Removes previously live environment-specific tfvars (sensitive values). |
| docs/vision/homelab-vision.md | Establishes platform purpose, direction, and principles. |
| docs/runbooks/bootstrap-sequence.md | Adds conservative doc-first bootstrap sequencing runbook. |
| docs/roadmap/milestones.md | Defines milestone progression for the new platform direction. |
| docs/roadmap/media-migration.md | Drafts media migration roadmap and evaluation phases. |
| docs/roadmap/current-phase.md | Documents current “Foundation / Repository Realignment” phase. |
| docs/roadmap/backlog.md | Adds a starter backlog aligned to the roadmap. |
| docs/inventory/service-inventory.md | Establishes service inventory baseline and TODOs. |
| docs/inventory/network-inventory.md | Captures known network hardware and TODOs for segmentation. |
| docs/inventory/hardware-inventory.md | Captures known hardware assets and TODOs for details. |
| docs/inventory/current-media-stack.md | Documents current media stack baseline (compose on VM + NFS). |
| docs/decisions/ADR-005-media-platform-stays-separate-from-core-lab.md | Records decision to keep media workstream operationally separate. |
| docs/decisions/ADR-004-truenas-separate.md | Records decision to keep TrueNAS as separate storage anchor. |
| docs/decisions/ADR-003-argocd-over-flux.md | Records decision preferring Argo CD over Flux going forward. |
| docs/decisions/ADR-002-k8s-inside-proxmox.md | Records decision to run initial Kubernetes inside Proxmox VMs. |
| docs/decisions/ADR-001-proxmox-first.md | Records decision to adopt Proxmox-first direction. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/variables.tf | Archives legacy Talos node module inputs. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/worker.yaml.tftpl | Archives legacy worker template placeholder. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/controlplane.yaml.tftpl | Archives legacy Talos controlplane template. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/cilium-install.yaml.tftpl | Archives legacy inline manifest for Cilium install. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/providers.tf | Archives legacy provider constraints for node module. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/main.tf | Archives legacy Talos apply workflow for nodes. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/variables.tf | Archives legacy module variables for deploy key. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/providers.tf | Archives legacy provider constraints for deploy key module. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/outputs.tf | Archives outputs for generated deploy key material. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/main.tf | Archives deploy key creation logic. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/variables.tf | Archives legacy Flux module inputs. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/values/components.yaml | Archives Flux component selection/patching values. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/providers.tf | Archives Flux module provider constraints. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/main.tf | Archives Flux operator/instance installation logic. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/variables.tf | Archives config module inputs (Talos, Cilium, etc.). |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/providers.tf | Archives provider constraints for config module. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/outputs.tf | Archives sensitive outputs (secrets/config/manifests). |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/main.tf | Archives Talos secrets + Cilium template generation logic. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/variables.tf | Archives cluster module inputs. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/providers.tf | Archives provider constraints for cluster module. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/outputs.tf | Archives kubeconfig connection material outputs. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/main.tf | Archives Talos bootstrap + kubeconfig generation logic. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/variables.tf | Archives baremetal module inputs/validation. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/providers.tf | Archives provider constraints for baremetal module. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/outputs.tf | Archives baremetal module outputs. |
| docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/main.tf | Archives PXE helper container + image factory logic. |
| docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/variables.tf | Archives legacy live/prod variables. |
| docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/terraform.auto.tfvars | Adds redacted sample tfvars for archived live/prod. |
| docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/providers.tf | Archives live/prod provider configuration. |
| docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/main.tf | Archives live/prod wiring of legacy modules. |
| docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/.terraform.lock.hcl | Archives OpenTofu lockfile for legacy live/prod. |
| docs/archive/legacy-baremetal-talos-pxe/infra/live/dev/.gitkeep | Keeps dev live directory in archive. |
| docs/archive/legacy-baremetal-talos-pxe/infra/README.md | Archives legacy infra README and usage notes. |
| docs/archive/legacy-baremetal-talos-pxe/README.md | Adds archive-level explanation and safety note. |
| docs/archive/README.md | Adds archive index description and guardrail. |
| docs/architecture/target-architecture.md | Defines working-draft target architecture. |
| docs/architecture/security-model.md | Defines baseline security model and TODOs. |
| docs/architecture/proxmox-k8s-strategy.md | Captures Proxmox→K8s strategy and rationale. |
| docs/architecture/network-topology.md | Captures draft topology and segmentation intent. |
| docs/architecture/media-platform.md | Captures media platform current/future state framing. |
| docs/README.md | Adds docs index entrypoint. |
| automation/README.md | Adds automation area stub + conventions statement. |
| argocd/README.md | Adds Argo CD area stub. |
| ai/README.md | Adds AI workstream area stub. |
| README.md | Adds root repository entrypoint and navigation. |
| .github/pull_request_template.md | Adds PR template aligned to the new workflow. |
| .github/ISSUE_TEMPLATE/task.yml | Adds Task issue template. |
| .github/ISSUE_TEMPLATE/epic.yml | Adds Epic issue template. |
| .github/ISSUE_TEMPLATE/decision.yml | Adds Decision issue template. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+5
to
+15
| cluster_nodes = { | ||
| node0 = { | ||
| hostname = "TODO.example.internal" | ||
| ip = "TODO" | ||
| mac_address = "TODO" | ||
| wake_on_lan_mac = "TODO" | ||
| install_disk = "/dev/TODO" | ||
| role = "controlplane" | ||
| bootstrap = true | ||
| } | ||
| } |
There was a problem hiding this comment.
The redacted sample uses cluster_nodes key node0, but main.tf references var.cluster_nodes["nx0"]/nx1/nx2. Align the sample keys with the expected map keys (or adjust main.tf) so the sample is internally consistent.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Description
docs/{vision,inventory,architecture,decisions,runbooks,roadmap,archive}plusproxmox/,kubernetes/,argocd/,automation/,ai/,scripts/, and.github/ISSUE_TEMPLATE/with starter content and README stubs.README.md, a documentation index (docs/README.md), inventory and media-stack docs (docs/inventory/*anddocs/inventory/current-media-stack.md), architecture drafts (docs/architecture/*), runbook (docs/runbooks/bootstrap-sequence.md), roadmap (milestones/backlog/current-phase/media-migration), and ADRs (docs/decisions/ADR-001throughADR-005) in the requested ADR format.docs/archive/legacy-baremetal-talos-pxe/infra/and replaced sensitive values with a redactedterraform.auto.tfvarssample; preserved legacy Terraform/Talos modules for reference rather than deletion..github/ISSUE_TEMPLATE/{task,epic,decision}.ymland.github/pull_request_template.md, and ensured all new files explicitly mark TODOs where exact technical details are intentionally omitted.Testing
git status --short --branchto confirm working-tree changes and branch context and it completed successfully.find docs -maxdepth 4 -type f | sortand confirmed the expected files were created.git add -A && git commit -m "Restructure repo to documentation-first homelab platform"which recorded the new layout (68 files changed).git push -u origin docs/pivot-homelab-platformwhich failed due to nooriginremote configured in this environment, so the branch has been created and committed locally but not pushed to a remote from this run.Codex Task