Homelab Docker + Terraform Inventory Repository

This repository is both:

1. operational (Docker Compose application/runtime definition), and
2. documentary/inventory-oriented (Terraform capture of Proxmox VMs, host metadata, and selected Docker objects).

If you only read one section, read Source-of-truth boundaries first.

---

Quick navigation

• Architecture overview: docs/architecture.md
• Repository layout: docs/repo-structure.md
• Source-of-truth boundaries and guardrails: docs/source-of-truth.md
• Docker environment composition and services-up.sh: docs/docker-environment.md
• Terraform workflows (brownfield import/reconciliation): docs/terraform-workflows.md
• Infrastructure inventory intent and outputs: docs/infrastructure-inventory.md
• Deployment prerequisites and secrets setup: DEPLOYMENT.md
• Secrets inventory: SECURITY_SECRETS_INVENTORY.md

Terraform subtrees:

• Terraform root docs: infrastructure/terraform/README.md
• Terraform Docker mirror: infrastructure/terraform/docker/README.md
• Terraform Proxmox inventory: infrastructure/terraform/proxmox/README.md

---

Operating model

Docker Compose (runtime authority)

• Compose files under core/, apps/, and monitoring/ describe runtime services.
• services-up.sh composes the environment by discovering compose files and applying common env/network inputs.
• For service runtime behavior, start from Compose files and services-up.sh (not Terraform).

Terraform (inventory and reconciliation authority)

• Terraform under infrastructure/terraform/ is used to codify and reconcile existing infrastructure.
• Current repo usage emphasizes brownfield import-first workflows and safe reconciliation.
• Terraform captures:
  • Proxmox VM configuration for existing VMs.
  • Physical host metadata in locals/outputs.
  • Documentation-oriented Docker container mirroring (limited, selective).

Terraform here is not a replacement for Docker Compose deployment.

---

Guardrails

• Do not run destructive Terraform commands casually.
• Do not treat generated Terraform config as final without manual review.
• Do not commit real secrets, credentials, or local state.
• Keep one-resource-per-file patterns where already established in Terraform subdirectories.
• Prefer shaping outputs for documentation/tooling consumption over dumping raw provider objects.

See docs/source-of-truth.md and docs/terraform-workflows.md for concrete do/don't guidance.

---

High-level architecture

flowchart TB
  Internet((Internet Clients)) -->|HTTPS 443 / HTTP 80| Traefik[Traefik Ingress\nACME TLS + Security Middlewares]

  subgraph DockerHost[Primary Docker Host]
    Traefik
    Authelia[Authelia SSO / ForwardAuth]
    CrowdSec[CrowdSec + Traefik Bouncer]
    ErrPages[Error Pages Fallback]

    subgraph Apps[Business / User Applications]
      Nextcloud[Nextcloud]
      Passbolt[Passbolt]
      Gitea[Gitea]
      FamilyTree[Gramps Web]
      Searxng[SearXNG]
    end

    subgraph Ops[Operations & Monitoring]
      Grafana[Grafana]
      Prometheus[Prometheus]
      InfluxDB[InfluxDB]
      NodeRED[Node-RED]
      Portainer[Portainer]
      UptimeKuma[Uptime Kuma]
      Gotify[Gotify Notifications]
    end
  end

  Traefik --> Apps
  Traefik --> Ops
  Traefik -->|ForwardAuth for selected routes| Authelia
  Traefik -->|Threat decisions| CrowdSec
  Traefik -->|4xx/5xx fallback| ErrPages

  Prometheus --> Grafana
  Prometheus --> Gotify

For request-flow and network detail, see docs/architecture.md.