Home Infra
This repository contains the Infrastructure as Code (IaC) configuration and documentation for a home infrastructure setup. The main goals are:
- Creating a local, self-hosted environment for various services and applications, minimizing reliance on external cloud providers.
- Learning and organizing knowledge, best practices, and tool documentation into a single repository.
Table of Contents
Principles
- Automate Everything: Embrace the “cattle, not pets” approach by automating as much as possible to ensure consistency and reproducibility.
- Prioritize Local Functionality: While cloud services may be utilized, the focus is on minimizing external dependencies and enabling local, cloud-independent functionality.
- Minimal and Energy-efficient Hardware: Favor energy-efficient hardware solutions to reduce environmental impact and operational costs.
- Avoid Overcomplication: Maintain a lightweight and straightforward setup by avoiding unnecessary complexities.
- Extensibility and Easy Configuration: Ensure that the infrastructure is easily extensible and configurable to accommodate future changes and requirements.
- Security-minded: Prioritize security best practices and implement appropriate measures to protect the infrastructure and data.
Key Software Components & Services
The key components of this infrastructure include:
Local Infrastructure Components
- Proxmox Virtual Environment: A Type 1 hypervisor for managing virtual machines and containers.
- Ubuntu Server: The host OS for running Docker containers and administrative tools.
- Ansible: Used for configuring the host OS and deploying required software.
- Docker Compose: For defining and managing Docker container configurations.
- Traefik: A reverse proxy with TLS certificate management.
- Authentik: Central identity provider for Google federation, native OIDC, and Traefik ForwardAuth, with local recovery accounts.
- Guacamole: A web-based remote desktop and SSH access solution.
- Homepage: A dashboard for managing and accessing various services.
Cloud Services (External Dependencies)
The long-term goal is to reduce these dependencies and provide offline alternatives.
| Name | Description | Remarks |
|---|---|---|
| Docker images | All services run as containers | Downloaded on first use |
| Plugins, Modules (e.g., CrowdSec) | Various plugins for services | Downloaded on first use. TODO: create inventory |
| Large Language Models | Optional, used by Ollama | Downloaded on first use |
| OVHcloud (or other registrar) | Domain name registration | Required for remote access and TLS certificates. TODO: document fallback |
| Cloudflare | DNS zone administration, tunnel | DNS administration is required by the documented TLS setup; tunnels are optional |
| Let’s Encrypt | TLS certificates (managed by Traefik) | Required. TODO: document local CA setup for fallback |
| Backblaze B2 | Backup storage | Optional, local backup also configured |
| CrowdSec | Crowd-sourced IP blocklist | Optional, security service, can be disabled |
| Azure | Temporary VM, storage | Optional, not used by any lab components |
| AWS | EC2 VM, persistent EBS storage | Optional, cloud deployment target |
| Homepage Icons | Icon set for the services | Optional, hosted on a CDN. TODO: host locally |
Getting Started
Choose either bootstrap target explicitly; neither is the default. Follow the selected guide’s prerequisites before running initialization:
| Target | Start | Installation guide |
|---|---|---|
| AWS | task bootstrap:init TARGET=aws | AWS installation |
| Proxmox | task bootstrap:init TARGET=proxmox | Proxmox installation |
Both use native provisioning and configurable ordered Ansible roles, with
one private operator-edited bootstrap.yaml, automatically converted to native
inputs under generated/. Templates select Docker/Traefik/Homepage; set services: []
for a host without those applications and select only its needed roles.
Service secrets are excluded from Terraform inputs. Pass the same TARGET on
subsequent bootstrap commands; each target has its own default input/state directory.
See configuration and safety.
The underlying AWS EC2 Terraform configuration also
supports standalone use.
Repository Layout
| Path | Purpose |
|---|---|
ansible/ | Host playbooks, roles and public inventory defaults |
docker/ | Service Compose files, organized by category |
docs/ | Installation, configuration and operations guides |
terraform/ | Standalone AWS and Azure provisioning templates |
vm/ | VM provisioning scripts and hypervisor documentation |
scripts/ | Service-management and maintenance utilities |
tests/ | Offline regression tests |
config/ | Ignored, host-specific inputs and private configuration |
config-example/ | Configuration templates with placeholder values |
Development
All development dependencies are available in the devcontainer or can be set up with an Ansible role.
Run commands from the repository root:
| Command | Purpose |
|---|---|
task --list-all | Discover the available tasks |
task ui | Open the TaskUI task selector |
task test | Run the Python unit tests |
task bootstrap:test | Run only bootstrap Python and Proxmox shell tests |
task lint | Run all pre-commit checks |
task build | Run tests/lint, regenerate Docker examples and build the documentation image |
task clean | Remove generated documentation, Terraform caches/plans and Python virtual environments |
Inspect Taskfile.yaml and its included task files before running
build, cleanup or operational tasks: they can modify files and require Docker or
host-specific inputs. For focused changes, run the relevant tests and
pre-commit run --files <changed-files> instead of the full build.
For a single bootstrap check, use
uv run --with-requirements scripts/requirements.txt python3 -m unittest tests.test_bootstrap.<Class>.<test_method>.
task test runs all Python tests; task build runs those plus the Proxmox shell
tests before linting and build steps.
Pre-commit checks shell scripts, YAML, Python, Ansible,
Terraform and Dockerfiles, plus secrets and infrastructure security. The exact
hooks are defined in .pre-commit-config.yaml.
Docker configuration, image updates and example .env generation are documented
in Docker services. For operational utilities, see
Usage.
GitHub automations
- Workflows configured (see in
.github/workflows): - Updating the container images and other components is automated with Renovate
- GitHub Marketplace App
- Configured with
renovate.json - Free for public and private repositories
- AI Code Review for MRs is done with Code Rabbit
- GitHub Marketplace App
- Configured with
.coderabbit.yaml - Free for public repositories
EOL
A crowd-sourced guide to help techs help their non-tech spouses / partners / parents / kids when we are at the end-of-life.