# akshaypradheep/homelab-iaac architecture

> Architecture diagram of the GitHub repository akshaypradheep/homelab-iaac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshaypradheep/homelab-iaac
- Repository: https://github.com/akshaypradheep/homelab-iaac

## Overview

homelab-IaaC provisions Proxmox VMs and configures them with Ansible, using Terraform’s generated inventory as the handoff between the two. The principal workflow is to declare servers, create or update them, configure hosts, and deploy opted-in Compose stacks. Ansible also provides host-specific capabilities such as filesystem and USB setup. The README documents these major handoffs and the common-to-packages-to-Docker role order; no source excerpts were provided, so relationships beyond those documented are omitted.

Main entry points: [`terraform/main.tf`](https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/main.tf) (VM provisioning), [`ansible/playbooks/site.yml`](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/playbooks/site.yml) (Site playbook), [`ansible/inventory/hosts.static.yml`](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/inventory/hosts.static.yml) (Ansible inventory), [`compose`](https://github.com/akshaypradheep/homelab-iaac/tree/main/compose) (Compose stacks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provisioning["VM provisioning"]
  node_server_declarations["Server declarations"]
  node_terraform["VM provisioning<br/>[main.tf]"]
  node_server_module["Server module<br/>[main.tf]"]
  node_inventory_template["Inventory template<br/>[inventory.tpl]"]
end

subgraph group_configuration["Host configuration"]
  node_ansible_inventory["Ansible inventory<br/>[hosts.static.yml]"]
  node_site_playbook["Site playbook<br/>[site.yml]"]
  node_common_role["Common setup<br/>[main.yml]"]
  node_packages_role["Package setup<br/>[main.yml]"]
  node_docker_role["Docker setup<br/>[main.yml]"]
  node_host_variables["Layered host settings<br/>[all.yml]"]
  node_filesystem_setup["Filesystem setup<br/>[main.yml]"]
  node_usb_setup["USB mount setup<br/>[main.yml]"]
  node_app_roles["Application roles"]
end

subgraph group_services["Compose services"]
  node_compose_stacks["Compose stacks"]
  node_monitoring_stack["Monitoring stack<br/>[docker-compose.yml]"]
end

node_operator(("Homelab operator"))
node_proxmox["Proxmox"]

node_operator -->|"declares servers"| node_server_declarations
node_operator -->|"runs apply"| node_terraform
node_terraform -->|"creates VMs"| node_proxmox
node_terraform -.->|"uses module"| node_server_module
node_terraform -->|"renders inventory"| node_inventory_template
node_terraform -->|"generates inventory"| node_ansible_inventory
node_ansible_inventory -->|"supplies hosts"| node_site_playbook
node_site_playbook -->|"runs first"| node_common_role
node_site_playbook -->|"runs next"| node_packages_role
node_site_playbook -->|"runs last"| node_docker_role
node_host_variables -->|"configures hosts"| node_site_playbook
node_operator -->|"can configure"| node_filesystem_setup
node_operator -->|"can configure"| node_usb_setup
node_operator -->|"can install apps"| node_app_roles
node_operator -->|"deploys opted-in"| node_compose_stacks
node_compose_stacks -.->|"includes"| node_monitoring_stack

click node_server_declarations "https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/servers.auto.tfvars.example"
click node_terraform "https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/main.tf"
click node_server_module "https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/modules/server/main.tf"
click node_inventory_template "https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/templates/inventory.tpl"
click node_ansible_inventory "https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/inventory/hosts.static.yml"
click node_site_playbook "https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/playbooks/site.yml"
click node_common_role "https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/common/tasks/main.yml"
click node_packages_role "https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/packages/tasks/main.yml"
click node_docker_role "https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/docker/tasks/main.yml"
click node_host_variables "https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/inventory/group_vars/all.yml"
click node_filesystem_setup "https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/filesystems/tasks/main.yml"
click node_usb_setup "https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/usb-mounts/tasks/main.yml"
click node_app_roles "https://github.com/akshaypradheep/homelab-iaac/tree/main/ansible/roles"
click node_compose_stacks "https://github.com/akshaypradheep/homelab-iaac/tree/main/compose"
click node_monitoring_stack "https://github.com/akshaypradheep/homelab-iaac/blob/main/compose/monitoring/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_declarations,node_terraform,node_server_module,node_inventory_template toneBlue
class node_ansible_inventory,node_site_playbook,node_common_role,node_packages_role,node_docker_role,node_host_variables,node_filesystem_setup,node_usb_setup,node_app_roles toneAmber
class node_compose_stacks,node_monitoring_stack toneMint
class node_operator,node_proxmox toneIndigo
```

## Components

### VM provisioning

- [Server declarations](https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/servers.auto.tfvars.example): `terraform/servers.auto.tfvars.example`
- [VM provisioning](https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/main.tf): `terraform/main.tf`
- [Server module](https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/modules/server/main.tf): `terraform/modules/server/main.tf`
- [Inventory template](https://github.com/akshaypradheep/homelab-iaac/blob/main/terraform/templates/inventory.tpl): `terraform/templates/inventory.tpl`

### Host configuration

- [Ansible inventory](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/inventory/hosts.static.yml): `ansible/inventory/hosts.static.yml`
- [Site playbook](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/playbooks/site.yml): `ansible/playbooks/site.yml`
- [Common setup](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/common/tasks/main.yml): `ansible/roles/common/tasks/main.yml`
- [Package setup](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/packages/tasks/main.yml): `ansible/roles/packages/tasks/main.yml`
- [Docker setup](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/docker/tasks/main.yml): `ansible/roles/docker/tasks/main.yml`
- [Layered host settings](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/inventory/group_vars/all.yml): `ansible/inventory/group_vars/all.yml`
- [Filesystem setup](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/filesystems/tasks/main.yml): `ansible/roles/filesystems/tasks/main.yml`
- [USB mount setup](https://github.com/akshaypradheep/homelab-iaac/blob/main/ansible/roles/usb-mounts/tasks/main.yml): `ansible/roles/usb-mounts/tasks/main.yml`
- [Application roles](https://github.com/akshaypradheep/homelab-iaac/tree/main/ansible/roles): `ansible/roles`

### Compose services

- [Compose stacks](https://github.com/akshaypradheep/homelab-iaac/tree/main/compose): `compose`
- [Monitoring stack](https://github.com/akshaypradheep/homelab-iaac/blob/main/compose/monitoring/docker-compose.yml): `compose/monitoring/docker-compose.yml`

### Other components

- **Homelab operator**
- **Proxmox**

## Connections

- Homelab operator → Server declarations: declares servers (evidence: `README.md`)
- Homelab operator → VM provisioning: runs apply (evidence: `README.md`)
- VM provisioning → Proxmox: creates VMs (evidence: `README.md`)
- VM provisioning → Server module: uses module
- VM provisioning → Inventory template: renders inventory (evidence: `README.md`)
- VM provisioning → Ansible inventory: generates inventory (evidence: `README.md`)
- Ansible inventory → Site playbook: supplies hosts (evidence: `README.md`)
- Site playbook → Common setup: runs first (evidence: `README.md`)
- Site playbook → Package setup: runs next (evidence: `README.md`)
- Site playbook → Docker setup: runs last (evidence: `README.md`)
- Layered host settings → Site playbook: configures hosts (evidence: `README.md`)
- Homelab operator → Filesystem setup: can configure (evidence: `README.md`)
- Homelab operator → USB mount setup: can configure (evidence: `README.md`)
- Homelab operator → Application roles: can install apps (evidence: `README.md`)
- Homelab operator → Compose stacks: deploys opted-in (evidence: `README.md`)
- Compose stacks → Monitoring stack: includes
