# 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](docs/source-of-truth.md)** first.

---

## Quick navigation

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

Terraform subtrees:

- Terraform root docs: [infrastructure/terraform/README.md](infrastructure/terraform/README.md)
- Terraform Docker mirror: [infrastructure/terraform/docker/README.md](infrastructure/terraform/docker/README.md)
- Terraform Proxmox inventory: [infrastructure/terraform/proxmox/README.md](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](docs/source-of-truth.md) and [docs/terraform-workflows.md](docs/terraform-workflows.md) for concrete do/don't guidance.

---

## High-level architecture

```mermaid
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](docs/architecture.md).