simple-homelab

Terraform/OpenTofu-managed infrastructure for the user's Proxmox homelab.

Note

Version numbers are not tracked in this README. For docker-apps services, check the running container directly (Watchtower updates them without committing changes here). For everything else, check the pinned version in that module's main.tf/project.auto.tfvars.

Modules

Host Setup This module and its sub-modules setup the Proxmox host.
OPNsense VM Creates the OPNsense router/firewall VM. WAN attaches untagged to var.wan_bridge (gets its address from upstream, e.g. via DHCP during the test phase). LAN attaches untagged/trunk to var.lan_bridge - OPNsense itself defines VLAN sub-interfaces on top of that one interface.
Samba Setup This module sets up Samba server in an Alpine LXC container using the provided information.
Step-CA Setup This module sets up Step-CA in an Alpine LXC container using the provided information.
PBS LXC Setup This module sets up Proxmox Backup Server in a Debian LXC container, using /mnt/backup/pbs (bind-mounted from the host) as the datastore location. Replaces modules/pbs-vm as the deployed PBS instance -- that module is kept in the repo as a fallback option, but no longer applied.
Docker VM Setup This module sets up a Flatcar Linux VM with Docker.
Backup Jobs Registers Proxmox Backup Server as a PVE storage target, creates one dedicated backup job per guest (VM/LXC primary disks), and one host-level folder backup per entry in var.folders (real data the guest-level jobs never touch - bind-mounted LXC state, the family file shares, PVE's own recovery-relevant config).

Hardware

Not Terraform-managed - present on the network, documented here for reference only.

Flint 2 (GL.iNet / LuCI) A Flint 2 (GL-MT6000) is installed in the network and offers a GLi.net default UI as well as LuCI. The latter can be accessed and customized to meet all the needs (e.g. SNMP, LLDP, VLANs and much more).
Horaco LAN switch

Docker Apps

Note

Deploying a docker-apps service is two steps: tofu apply in the module's own directory, then docker compose -f docker-compose.yml --env-file stack.env up -d on the Docker VM.

External (Docker) resources This module creates resources, that are not supposed to be part of a docker-compose.yml.
Traefik dashboard OIDC This module uses the OIDC module to create the necessary client_id to set up OIDC/OAuth for Traefik (dashboard) with Zitadel.
Zitadel Identity and access management (SSO/OIDC) used by every other docker-apps service
Portainer OIDC This module uses the OIDC module to create the necessary client_id and client_secret to set up OIDC/OAuth in Portainer with Zitadel.
Gitea OIDC Creates the necessary Zitadel resources (project, OIDC app, roles, user grants) for Gitea to authenticate via Zitadel SSO.
Grafana Alloy and Prometheus OIDC This module uses the OIDC module to create the necessary client_id to set up OIDC/OAuth for Grafana Alloy and Prometheus with Zitadel.
Grafana OIDC This module uses the OIDC module to create the necessary client_id to set up OIDC/OAuth in Grafana with Zitadel.
Outline OIDC This module uses the OIDC module to create the necessary client_id and client_secret to set up OIDC/OAuth in Outline with Zitadel.
Jellyfin Web UI OIDC This module uses the OIDC module to create the necessary client_id to set up OIDC/OAuth for Jellyfin (dashboard) with Zitadel.
Grist OIDC This module uses the OIDC module to create the necessary client_id and client_secret to set up OIDC/OAuth in Grist with Zitadel.
Watchtower Automatically restarts containers when a newer image is pushed
MQTT Mosquitto broker for Tasmota smart plugs, exported to Prometheus via mqtt-exporter
Scanopy Automated network topology mapping (L2/L3/workloads) - experimental, unfamiliar tool, evaluate before trusting
Homarr Unified dashboard - container/hardware overview, service bookmarks, per-group boards via SSO

Other modules

common
Pi-hole Setup Not currently in use - superseded by OPNsense's Unbound DNS (blocklists, host overrides, reporting). Kept in the repo as a fallback option, not applied.
Scanopy Daemon (standalone LXC) Runs a standalone scanopy-daemon in a Debian LXC container, dual-homed onto every VLAN (vmbr1.5/10/20/30/40) so it has genuine ARP-level presence on each subnet - unlike SNMP-relayed discovery (via OPNsense's ARP/routing tables), this catches hosts with no open ports and gets real MACs directly.