# securitybits-io/homelab architecture

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

- Interactive diagram: https://gitdiagram.com/securitybits-io/homelab
- Repository: https://github.com/securitybits-io/homelab

## Overview

Securitybits Homelab is infrastructure-as-code and operational configuration for a Proxmox-based home environment. The principal workflow is to provision VM templates and workload VMs with separate Terraform roots, configure hosts with Ansible, then deploy Nomad job specifications and variable files to the cluster. The graph also preserves the documented DNS, retained Compose applications, and workload categories. Relationships are based on the README’s architecture and workflow descriptions; no source excerpts were available to verify implementation details.

Main entry points: [`ansible`](https://github.com/securitybits-io/homelab/tree/main/ansible) (Ansible playbooks), [`terraform`](https://github.com/securitybits-io/homelab/tree/main/terraform) (Workload Terraform), [`apps`](https://github.com/securitybits-io/homelab/tree/main/apps) (Retained Compose apps), [`templates`](https://github.com/securitybits-io/homelab/tree/main/templates) (Template Terraform)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provisioning["VM provisioning"]
  node_template_tf["Template Terraform"]
  node_debian_template["Debian VM template"]
  node_workload_tf["Workload Terraform"]
  node_proxmox["Proxmox cluster"]
  node_hashistack_vms["Hashistack VMs"]
  node_legacy_vms["Legacy VMs"]
  node_dns["Namecheap DNS"]
end

subgraph group_configuration["Host configuration"]
  node_ansible["Ansible playbooks"]
  node_ansible_roles["Host configuration roles"]
  node_nomad_vars["Nomad variable files"]
end

subgraph group_orchestration["Nomad orchestration"]
  node_nomad["Nomad cluster"]
  node_job_specs["Nomad job specs"]
end

subgraph group_workloads["Workloads and services"]
  node_app_jobs["Application jobs"]
  node_service_jobs["Service jobs"]
  node_support_jobs["Support jobs"]
  node_dev_jobs["Development jobs"]
  node_retained_apps["Retained Compose apps"]
  node_monitoring["Monitoring stack"]
  node_stash["Stash app"]
end

node_operator(("Homelab operator"))

node_operator -->|"manages template"| node_template_tf
node_operator -->|"manages infrastructure"| node_workload_tf
node_template_tf -->|"creates template"| node_debian_template
node_debian_template -->|"runs on"| node_proxmox
node_workload_tf -->|"provisions"| node_hashistack_vms
node_workload_tf -->|"provisions"| node_legacy_vms
node_hashistack_vms -->|"runs on"| node_proxmox
node_legacy_vms -->|"runs on"| node_proxmox
node_workload_tf -->|"manages DNS"| node_dns
node_operator -->|"runs playbooks"| node_ansible
node_ansible -->|"configures hosts"| node_hashistack_vms
node_ansible -->|"configures hosts"| node_legacy_vms
node_ansible -->|"applies roles"| node_ansible_roles
node_ansible -->|"copies job specs"| node_job_specs
node_ansible -->|"deploys variables"| node_nomad_vars
node_nomad_vars -->|"configures variables"| node_nomad
node_job_specs -->|"submits jobs"| node_nomad
node_nomad -->|"runs workloads"| node_app_jobs
node_nomad -->|"runs workloads"| node_service_jobs
node_nomad -->|"runs workloads"| node_support_jobs
node_nomad -->|"runs workloads"| node_dev_jobs
node_operator -->|"maintains applications"| node_retained_apps
node_retained_apps -->|"includes"| node_monitoring
node_retained_apps -->|"includes"| node_stash

click node_template_tf "https://github.com/securitybits-io/homelab/tree/main/templates"
click node_debian_template "https://github.com/securitybits-io/homelab/tree/main/templates"
click node_workload_tf "https://github.com/securitybits-io/homelab/tree/main/terraform"
click node_hashistack_vms "https://github.com/securitybits-io/homelab/tree/main/terraform"
click node_legacy_vms "https://github.com/securitybits-io/homelab/tree/main/terraform"
click node_ansible "https://github.com/securitybits-io/homelab/tree/main/ansible"
click node_ansible_roles "https://github.com/securitybits-io/homelab/tree/main/ansible/roles"
click node_nomad_vars "https://github.com/securitybits-io/homelab/tree/main/ansible/host_vars/nomad/jobs-vars"
click node_job_specs "https://github.com/securitybits-io/homelab/tree/main/jobs"
click node_app_jobs "https://github.com/securitybits-io/homelab/tree/main/jobs/hashilab-apps"
click node_service_jobs "https://github.com/securitybits-io/homelab/tree/main/jobs/hashilab-services"
click node_support_jobs "https://github.com/securitybits-io/homelab/tree/main/jobs/hashilab-support"
click node_dev_jobs "https://github.com/securitybits-io/homelab/tree/main/jobs/hashilab-dev"
click node_retained_apps "https://github.com/securitybits-io/homelab/tree/main/apps"
click node_monitoring "https://github.com/securitybits-io/homelab/tree/main/apps/monitoring"
click node_stash "https://github.com/securitybits-io/homelab/tree/main/apps/stash"

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_template_tf,node_debian_template,node_workload_tf,node_proxmox,node_hashistack_vms,node_legacy_vms,node_dns toneBlue
class node_ansible,node_ansible_roles,node_nomad_vars toneAmber
class node_nomad,node_job_specs toneMint
class node_app_jobs,node_service_jobs,node_support_jobs,node_dev_jobs,node_retained_apps,node_monitoring,node_stash toneRose
class node_operator toneIndigo
```

## Components

### VM provisioning

- [Template Terraform](https://github.com/securitybits-io/homelab/tree/main/templates): `templates`
- [Debian VM template](https://github.com/securitybits-io/homelab/tree/main/templates): `templates`
- [Workload Terraform](https://github.com/securitybits-io/homelab/tree/main/terraform): `terraform`
- **Proxmox cluster**
- [Hashistack VMs](https://github.com/securitybits-io/homelab/tree/main/terraform): `terraform`
- [Legacy VMs](https://github.com/securitybits-io/homelab/tree/main/terraform): `terraform`
- **Namecheap DNS**

### Host configuration

- [Ansible playbooks](https://github.com/securitybits-io/homelab/tree/main/ansible): `ansible`
- [Host configuration roles](https://github.com/securitybits-io/homelab/tree/main/ansible/roles): `ansible/roles`
- [Nomad variable files](https://github.com/securitybits-io/homelab/tree/main/ansible/host_vars/nomad/jobs-vars): `ansible/host_vars/nomad/jobs-vars`

### Nomad orchestration

- **Nomad cluster**
- [Nomad job specs](https://github.com/securitybits-io/homelab/tree/main/jobs): `jobs`

### Workloads and services

- [Application jobs](https://github.com/securitybits-io/homelab/tree/main/jobs/hashilab-apps): `jobs/hashilab-apps`
- [Service jobs](https://github.com/securitybits-io/homelab/tree/main/jobs/hashilab-services): `jobs/hashilab-services`
- [Support jobs](https://github.com/securitybits-io/homelab/tree/main/jobs/hashilab-support): `jobs/hashilab-support`
- [Development jobs](https://github.com/securitybits-io/homelab/tree/main/jobs/hashilab-dev): `jobs/hashilab-dev`
- [Retained Compose apps](https://github.com/securitybits-io/homelab/tree/main/apps): `apps`
- [Monitoring stack](https://github.com/securitybits-io/homelab/tree/main/apps/monitoring): `apps/monitoring`
- [Stash app](https://github.com/securitybits-io/homelab/tree/main/apps/stash): `apps/stash`

### Other components

- **Homelab operator**

## Connections

- Homelab operator → Template Terraform: manages template (evidence: `README.md`)
- Homelab operator → Workload Terraform: manages infrastructure (evidence: `README.md`)
- Template Terraform → Debian VM template: creates template (evidence: `README.md`)
- Debian VM template → Proxmox cluster: runs on (evidence: `README.md`)
- Workload Terraform → Hashistack VMs: provisions (evidence: `README.md`)
- Workload Terraform → Legacy VMs: provisions (evidence: `README.md`)
- Hashistack VMs → Proxmox cluster: runs on (evidence: `README.md`)
- Legacy VMs → Proxmox cluster: runs on (evidence: `README.md`)
- Workload Terraform → Namecheap DNS: manages DNS (evidence: `README.md`)
- Homelab operator → Ansible playbooks: runs playbooks (evidence: `README.md`)
- Ansible playbooks → Hashistack VMs: configures hosts (evidence: `README.md`)
- Ansible playbooks → Legacy VMs: configures hosts (evidence: `README.md`)
- Ansible playbooks → Host configuration roles: applies roles (evidence: `README.md`)
- Ansible playbooks → Nomad job specs: copies job specs (evidence: `README.md`)
- Ansible playbooks → Nomad variable files: deploys variables (evidence: `README.md`)
- Nomad variable files → Nomad cluster: configures variables (evidence: `README.md`)
- Nomad job specs → Nomad cluster: submits jobs (evidence: `README.md`)
- Nomad cluster → Application jobs: runs workloads (evidence: `README.md`)
- Nomad cluster → Service jobs: runs workloads (evidence: `README.md`)
- Nomad cluster → Support jobs: runs workloads (evidence: `README.md`)
- Nomad cluster → Development jobs: runs workloads (evidence: `README.md`)
- Homelab operator → Retained Compose apps: maintains applications (evidence: `README.md`)
- Retained Compose apps → Monitoring stack: includes (evidence: `README.md`)
- Retained Compose apps → Stash app: includes (evidence: `README.md`)