# mradigen/selfhosted architecture

> Architecture diagram of the GitHub repository mradigen/selfhosted, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mradigen/selfhosted
- Repository: https://github.com/mradigen/selfhosted

## Overview

This repository is homelab infrastructure-as-code, not an application: an operator provisions virtual machines, configures hosts, then runs containerized services. The documented workflow uses Packer templates with Terraform on Proxmox; Ansible configures hosts and retrieves Vault secrets into Docker environment files. Docker Compose runs the service definitions. K3s is documented as a planned migration. Service relationships are limited to what the README and file tree support; source excerpts were unavailable.

Main entry points: [`docker`](https://github.com/mradigen/selfhosted/tree/main/docker) (Docker Compose), [`ansible`](https://github.com/mradigen/selfhosted/tree/main/ansible) (Ansible automation), [`terraform`](https://github.com/mradigen/selfhosted/tree/main/terraform) (Terraform), [`packer/debian.pkr.hcl`](https://github.com/mradigen/selfhosted/blob/main/packer/debian.pkr.hcl) (Packer image)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provision["VM provisioning"]
  node_packer["Packer image<br/>[debian.pkr.hcl]"]
  node_templates["VM templates"]
  node_terraform["Terraform"]
end

subgraph group_config["Host configuration"]
  node_ansible["Ansible automation"]
  node_k3s["K3s setup<br/>[k3s.yml]"]
  node_envfiles["Docker env files"]
end

subgraph group_runtime["Container services"]
  node_compose["Docker Compose"]
  node_homeassistant["Home Assistant<br/>[HomeAssistant.tf]"]
  node_borgmatic["Borgmatic<br/>[docker-compose.yml]"]
  node_headscale["Headscale<br/>[docker-compose.yml]"]
  node_immich["Immich<br/>[docker-compose.yml]"]
  node_vaultwarden["Vaultwarden<br/>[docker-compose.yml]"]
  node_traefik["Traefik<br/>[docker-compose.yml]"]
  node_n8n["n8n<br/>[docker-compose.yml]"]
  node_flatnotes["Flatnotes + Syncthing<br/>[docker-compose.yml]"]
  node_paperless["Paperless-ngx<br/>[docker-compose.yml]"]
  node_baikal["Baïkal<br/>[docker-compose.yml]"]
  node_balti["Balti<br/>[docker-compose.yml]"]
  node_minio["Balti MinIO<br/>[docker-compose.yml]"]
end

subgraph group_edge["External infrastructure"]
  node_proxmox["Proxmox"]
  node_vault[("Vault secrets<br/>[docker-compose.yml]")]
end

node_operator(("Operator"))

node_operator -->|"builds images"| node_packer
node_packer -->|"creates"| node_templates
node_operator -->|"provisions VMs"| node_terraform
node_terraform -->|"uses images"| node_templates
node_terraform -->|"provisions on"| node_proxmox
node_operator -->|"runs playbooks"| node_ansible
node_ansible -.->|"configures"| node_k3s
node_ansible -->|"fetches secrets"| node_vault
node_ansible -->|"writes values"| node_envfiles
node_operator -->|"runs services"| node_compose
node_compose -->|"starts"| node_homeassistant
node_compose -->|"starts"| node_borgmatic
node_compose -->|"starts"| node_headscale
node_compose -->|"starts"| node_immich
node_compose -->|"starts"| node_vaultwarden
node_compose -->|"starts"| node_traefik
node_compose -->|"starts"| node_n8n
node_compose -->|"starts"| node_flatnotes
node_compose -->|"starts"| node_paperless
node_compose -->|"starts"| node_baikal
node_compose -->|"starts"| node_balti
node_compose -->|"starts"| node_minio

click node_packer "https://github.com/mradigen/selfhosted/blob/main/packer/debian.pkr.hcl"
click node_templates "https://github.com/mradigen/selfhosted/tree/main/packer"
click node_terraform "https://github.com/mradigen/selfhosted/tree/main/terraform"
click node_ansible "https://github.com/mradigen/selfhosted/tree/main/ansible"
click node_k3s "https://github.com/mradigen/selfhosted/blob/main/ansible/setup/tasks/k3s.yml"
click node_vault "https://github.com/mradigen/selfhosted/blob/main/external/adolf/vault/docker-compose.yml"
click node_envfiles "https://github.com/mradigen/selfhosted/blob/main/ansible/playbooks/tasks/docker-env-vars.yml"
click node_compose "https://github.com/mradigen/selfhosted/tree/main/docker"
click node_homeassistant "https://github.com/mradigen/selfhosted/blob/main/terraform/HomeAssistant.tf"
click node_borgmatic "https://github.com/mradigen/selfhosted/blob/main/docker/borgmatic/docker-compose.yml"
click node_headscale "https://github.com/mradigen/selfhosted/blob/main/docker/headscale/docker-compose.yml"
click node_immich "https://github.com/mradigen/selfhosted/blob/main/docker/immich/docker-compose.yml"
click node_vaultwarden "https://github.com/mradigen/selfhosted/blob/main/docker/vaultwarden/docker-compose.yml"
click node_traefik "https://github.com/mradigen/selfhosted/blob/main/docker/traefik/docker-compose.yml"
click node_n8n "https://github.com/mradigen/selfhosted/blob/main/docker/n8n/docker-compose.yml"
click node_flatnotes "https://github.com/mradigen/selfhosted/blob/main/docker/flatnotes%2Bsyncthing/docker-compose.yml"
click node_paperless "https://github.com/mradigen/selfhosted/blob/main/docker/paperless-ng/docker-compose.yml"
click node_baikal "https://github.com/mradigen/selfhosted/blob/main/docker/baikal/docker-compose.yml"
click node_balti "https://github.com/mradigen/selfhosted/blob/main/docker/balti/docker-compose.yml"
click node_minio "https://github.com/mradigen/selfhosted/blob/main/docker/balti-minio/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_packer,node_templates,node_terraform toneBlue
class node_ansible,node_k3s,node_envfiles toneAmber
class node_compose,node_homeassistant,node_borgmatic,node_headscale,node_immich,node_vaultwarden,node_traefik,node_n8n,node_flatnotes,node_paperless,node_baikal,node_balti,node_minio toneMint
class node_proxmox,node_vault toneRose
class node_operator toneIndigo
```

## Components

### VM provisioning

- [Packer image](https://github.com/mradigen/selfhosted/blob/main/packer/debian.pkr.hcl): `packer/debian.pkr.hcl`
- [VM templates](https://github.com/mradigen/selfhosted/tree/main/packer): `packer`
- [Terraform](https://github.com/mradigen/selfhosted/tree/main/terraform): `terraform`

### Host configuration

- [Ansible automation](https://github.com/mradigen/selfhosted/tree/main/ansible): `ansible`
- [K3s setup](https://github.com/mradigen/selfhosted/blob/main/ansible/setup/tasks/k3s.yml): `ansible/setup/tasks/k3s.yml`
- [Docker env files](https://github.com/mradigen/selfhosted/blob/main/ansible/playbooks/tasks/docker-env-vars.yml): `ansible/playbooks/tasks/docker-env-vars.yml`

### Container services

- [Docker Compose](https://github.com/mradigen/selfhosted/tree/main/docker): `docker`
- [Home Assistant](https://github.com/mradigen/selfhosted/blob/main/terraform/HomeAssistant.tf): `terraform/HomeAssistant.tf`
- [Borgmatic](https://github.com/mradigen/selfhosted/blob/main/docker/borgmatic/docker-compose.yml): `docker/borgmatic/docker-compose.yml`
- [Headscale](https://github.com/mradigen/selfhosted/blob/main/docker/headscale/docker-compose.yml): `docker/headscale/docker-compose.yml`
- [Immich](https://github.com/mradigen/selfhosted/blob/main/docker/immich/docker-compose.yml): `docker/immich/docker-compose.yml`
- [Vaultwarden](https://github.com/mradigen/selfhosted/blob/main/docker/vaultwarden/docker-compose.yml): `docker/vaultwarden/docker-compose.yml`
- [Traefik](https://github.com/mradigen/selfhosted/blob/main/docker/traefik/docker-compose.yml): `docker/traefik/docker-compose.yml`
- [n8n](https://github.com/mradigen/selfhosted/blob/main/docker/n8n/docker-compose.yml): `docker/n8n/docker-compose.yml`
- [Flatnotes + Syncthing](https://github.com/mradigen/selfhosted/blob/main/docker/flatnotes%2Bsyncthing/docker-compose.yml): `docker/flatnotes+syncthing/docker-compose.yml`
- [Paperless-ngx](https://github.com/mradigen/selfhosted/blob/main/docker/paperless-ng/docker-compose.yml): `docker/paperless-ng/docker-compose.yml`
- [Baïkal](https://github.com/mradigen/selfhosted/blob/main/docker/baikal/docker-compose.yml): `docker/baikal/docker-compose.yml`
- [Balti](https://github.com/mradigen/selfhosted/blob/main/docker/balti/docker-compose.yml): `docker/balti/docker-compose.yml`
- [Balti MinIO](https://github.com/mradigen/selfhosted/blob/main/docker/balti-minio/docker-compose.yml): `docker/balti-minio/docker-compose.yml`

### External infrastructure

- **Proxmox**
- [Vault secrets](https://github.com/mradigen/selfhosted/blob/main/external/adolf/vault/docker-compose.yml): `external/adolf/vault/docker-compose.yml`

### Other components

- **Operator**

## Connections

- Operator → Packer image: builds images
- Packer image → VM templates: creates
- Operator → Terraform: provisions VMs
- Terraform → VM templates: uses images
- Terraform → Proxmox: provisions on
- Operator → Ansible automation: runs playbooks
- Ansible automation → K3s setup: configures
- Ansible automation → Vault secrets: fetches secrets
- Ansible automation → Docker env files: writes values
- Operator → Docker Compose: runs services
- Docker Compose → Home Assistant: starts
- Docker Compose → Borgmatic: starts
- Docker Compose → Headscale: starts
- Docker Compose → Immich: starts
- Docker Compose → Vaultwarden: starts
- Docker Compose → Traefik: starts
- Docker Compose → n8n: starts
- Docker Compose → Flatnotes + Syncthing: starts
- Docker Compose → Paperless-ngx: starts
- Docker Compose → Baïkal: starts
- Docker Compose → Balti: starts
- Docker Compose → Balti MinIO: starts