How to Build a Fully Declarative Homelab Stack

Homelabs tend to grow the same way: a Raspberry Pi running Pi-hole turns into a rack of mini PCs and Proxmox nodes, and at some point clicking through hypervisor UIs and re-typing docker compose up on each host stops scaling. The response a growing number of self-hosters converge on is the same shape — infrastructure-as-code for provisioning, a git-backed source of truth for what should be running, and a lightweight identity layer tying the resulting apps together. This piece synthesizes how that stack typically comes together using Terraform, Komodo, Gitea, a secrets manager like Infisical, and PocketID — and why the secrets-sync layer is the piece homelabbers most often end up hand-building themselves.

For background on getting a lab to the point where this level of tooling is worth the overhead, see First Homelab Setup: Hardware, Security & Networking Guide and 2026 Homelab Stack: OPNsense + Proxmox + TrueNAS + 10GbE.

Why Declarative Management Matters Once a Lab Gets Big

A handful of Docker Compose files on one host are easy to keep in your head. Somewhere past a dozen stacks spread across multiple machines, that stops being true — which container is on which host, which .env file has which value, and what changed since last week all become questions instead of known facts. Declarative tooling doesn't eliminate that complexity, but it moves the source of truth from "whatever is currently running" to "whatever is committed to the repo," per the general design philosophy documented by both Terraform and Gitea. That shift is what makes rollbacks, audits, and rebuilding a dead host from scratch tractable instead of a multi-hour reconstruction project.

The tradeoff worth being upfront about: none of this is free. Learning HCL, structuring a git-ops workflow, and standing up an identity provider is real time investment that only pays off once a lab is large enough to feel the pain of manual management. For a lab of two or three services, this is almost certainly overkill — see the tradeoffs discussed in Raspberry Pi 4 8GB vs a Used Mini PC for a 2026 Beginner Homelab for a much lighter starting point.

The Core Toolchain: Terraform, Komodo, and Gitea

Terraform (or OpenTofu) for provisioning

Terraform's role in this stack is provisioning the compute layer itself — VMs on Proxmox, LXC containers, or bare-metal nodes — rather than managing what runs inside them. Community Proxmox providers let a .tf file describe a VM's CPU, RAM, disk, and network config, and terraform apply reconciles the running infrastructure against that description. Homelabbers wary of licensing changes to Terraform's core often point to OpenTofu, the Linux Foundation-backed fork, as a drop-in alternative that speaks the same HCL syntax.

The operational risk with either tool is the state file: it's the record of what Terraform believes exists, and if it's lost or corrupted, a subsequent apply can attempt destructive changes to reconcile reality with a state Terraform no longer trusts. Regular backups of the state file — not just the .tf source — are non-negotiable once real infrastructure depends on it.

Komodo for stack orchestration

Where Terraform stops at the VM/container-host boundary, Komodo picks up container and Compose-stack management. Per its project documentation, Komodo provides a web UI over Docker, tracks stack definitions in git, and can coordinate deployments across multiple hosts from a single control plane — closer to a lightweight Portainer-plus-GitOps hybrid than a full Kubernetes replacement. For labs that don't want Kubernetes's operational overhead but have outgrown SSHing into each box to run docker compose pull && up -d, this is the layer that turns "deploy" into a git push.

Gitea as the source of truth

Gitea sits underneath both of the above as the self-hosted git server holding Terraform configs and Komodo stack definitions. Per Gitea's own documentation, it supports the same webhook and Actions patterns as GitHub, which is what lets a commit trigger a Komodo deployment automatically rather than requiring a manual pull. Keeping infrastructure definitions in a self-hosted Gitea instance rather than a third-party SaaS git host is also the piece that keeps the whole stack independent of any single cloud provider's uptime.

Secrets Management: Where Off-the-Shelf Tools Fall Short

Infisical covers the baseline self-hosted secrets-manager use case well — versioned secrets, per-environment scoping, and an API/CLI for pulling values into a deployment. The gap that shows up in practice is integration breadth: not every orchestration tool has a native Infisical plugin, and Komodo's secret injection model doesn't map one-to-one onto Infisical's project/environment structure out of the box.

This is the point in the stack where a lot of homelabbers end up writing a small bridging service rather than adopting a heavier commercial secrets platform: a script or lightweight daemon that pulls secrets from Infisical's API on a schedule or webhook and writes them into the format Komodo (or a raw Compose .env file) expects. It's a narrow, purpose-built tool rather than a general secrets manager — closer to glue code than infrastructure — but it's the piece that makes the rest of the pipeline actually declarative instead of requiring a manual step every time a secret rotates. Anyone hitting this same gap should check Infisical's own integration roadmap before building from scratch, since native support for less-common orchestration tools does get added over time.

Identity and Access: PocketID for Self-Hosted SSO

PocketID is a lightweight, passkey-first OIDC provider aimed specifically at self-hosted environments, per its project documentation — a narrower, lower-overhead alternative to Keycloak for labs that don't need enterprise-grade identity federation. Wiring PocketID in as the OIDC provider for Komodo, Gitea, and other self-hosted apps that support OIDC login means one set of credentials (and one MFA/passkey enrollment) covers the whole stack, rather than separate local accounts scattered across every service's admin panel.

The practical payoff is fewer places an old password lingers after a security review — every app defers to the same identity provider, so revoking access in one place revokes it everywhere. For a broader look at homelab security posture beyond identity, see How Secure Is My Homelab Compared to Big Companies?.

Common Pitfalls When Scaling Past a Handful of Stacks

• State file sprawl. Multiple Terraform state files across different modules without a shared backend (or at minimum a disciplined backup routine) is the single most common way homelabbers lose track of infrastructure they provisioned months ago.
• Webhook drift. Gitea webhooks pointing at a Komodo instance that's been moved to a new IP or port silently stop firing — worth checking after any network re-architecture.
• Secrets rotation gaps. A custom Infisical-to-Komodo bridge that isn't monitored can silently stop syncing, leaving stale credentials in place long after they've been rotated at the source.
• Over-indexing on tooling before the lab needs it. Standing up this entire stack for three Docker containers adds more maintenance burden than it removes. For smaller labs, see what's changed as labs grow past their original scope in Homelab Changes You Wish You'd Made Sooner.

Storage Considerations for State Files and Backups

Terraform state, Gitea repo mirrors, and Infisical's own database backups are all small individually but critical to have redundant copies of. A dedicated local or portable SSD kept separate from the primary Proxmox/TrueNAS pool is a common pattern for this kind of "infrastructure of the infrastructure" backup:

Prices reflect catalog data at publication time and may vary — check the current listing before buying.

Is This Stack Right for Your Homelab?

The honest answer scales with lab size. A single Raspberry Pi or one mini PC running a few containers doesn't need Terraform, git-ops, or a dedicated identity provider — see the comparison in Raspberry Pi 4 8GB vs Ryzen 5 5600G: Which Homelab Box Wins in 2026? for what a minimal setup looks like. Once a lab spans multiple hosts and enough services that manual tracking becomes error-prone, the Terraform-Komodo-Gitea-PocketID combination (with a secrets bridge filling the Infisical integration gap) is a well-trodden path documented across the self-hosting community. Before investing the setup time, it's also worth checking whether existing hardware — including anything sitting unused, as covered in Downsized Your Homelab? Here's What It's Worth — can be repurposed for the control-plane host rather than buying new.

Anyone with older enclosures already on hand should also weigh whether it's worth reviving before buying new gear, as discussed in Old Massive Chieftec Full Tower: Homelab Gem or Junk?.

Citations and sources

• Terraform documentation
• OpenTofu project
• Gitea documentation
• Gitea project site
• Infisical
• Infisical GitHub repository
• Komodo GitHub repository
• Komodo project site
• PocketID GitHub repository
• PocketID project site

This piece is editorial synthesis based on publicly available information. No independent first-party benchmarking is reported.