---

Architecture

Infrastructure

The homelab runs on a Minisforum A2 powered by Proxmox VE.

OpenTofu provisions infrastructure, while Ansible configures the host. Network infrastructure is managed separately in Netlab.

Cloudflare provides public edge services, Resend delivers email through SMTP, and Hetzner Storage Box stores off-site backups.

Platform

Three Fedora CoreOS virtual machines form a Docker Swarm cluster. The platform hosts self-hosted applications, shared data services, identity management, and observability. Services are defined declaratively as Swarm stacks.

All three VMs run on one physical host. The cluster does not provide host-level high availability.

Storage

OpenZFS provides persistent storage, shared with Swarm nodes through VirtioFS. Persistent application data lives outside the VMs and survives their recreation, provided the host datasets remain intact.

Sanoid manages local snapshots. borgmatic backs up Paperless, PostgreSQL, and Vaultwarden data to Hetzner Storage Box using Borg over SSH. These off-site backups do not cover every persistent dataset.

Security

Security takes priority over convenience. The approach favors minimal exposure and simple, explicit controls.

Traefik routes application traffic, with public access through Cloudflare. WireGuard provides remote access to internal services and management interfaces. Authentik provides application single sign-on; applications and infrastructure retain their own permission controls.

Secrets are declared through SecretSpec, stored encrypted with SOPS, and delivered to services as Docker secrets.

The development workflow follows a SecOps approach. CI checks workflows, infrastructure code, secrets, and container images for security issues.

Development

Git stores the desired state, and deployments are triggered manually. Infrastructure and services are provisioned through code and Task workflows. Rebuilding still requires bootstrap access, secrets, infrastructure state, and intact data or usable backups.

Operations

Operational workflows use Task to orchestrate Bash and Python workers from the command line.

Run task to see available operations.

Documentation

Documentation is intentionally minimal. Configuration and executable workflows are the primary reference, with project rules in AGENTS.md.

Open an issue for questions or discussion.

License

Licensed under the MIT License.