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.
- 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.
The key components of this infrastructure include:
- 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.
- Authelia: Provides authentication and single sign-on capabilities.
- Guacamole: A web-based remote desktop and SSH access solution.
- Homepage: A dashboard for managing and accessing various services.
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 | Optional, for remote access |
| 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 |
| Homepage Icons | Icon set for the services | Optional, hosted on a CDN. TODO: host locally |
The recommended configuration is to set up Proxmox VE and install a Debian- or Ubuntu-based VM to host the Docker services.
-> See Getting Started
All development dependencies are available in the devcontainer or can be set up with an Ansible role.
Some development workflows:
Code quality scanning tools are set up via pre-commit.
Perform the checks by running task lint (or pre-commit run --all-files).
Create/update example .env files: task docker:update-example-env.
- 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
A crowd-sourced guide to help techs help their non-tech spouses / partners / parents / kids when we are at the end-of-life.