Skip to content

Mailing Way Homelab

The Mailing Way Homelab is an Ansible-deployed homelab. Proxmox hosts the virtual machines; a two-node Docker Swarm runs the container stacks. Traefik is the single public entry point on lab.riversfamily.uk, and Authentik is the identity provider.

This site is the reference for what runs, where it runs, how it is configured, and how to deploy it. The source of truth is always the Ansible repository (ansible/); this site is generated from and cross-checked against it (see Keeping this site up to date).

Where to start

  • Services — every service in the stack: what it is, where it runs, how it is configured.
  • Network — IP addressing, hosts, ingress and DNS.
  • Configuration — where each class of setting lives (group_vars, host_vars, role defaults, per-stack templates).
  • Vault variables — every secret the stack needs, what it is for, and how it is delivered to its consumer.
  • Resources — VM and node sizing (cores, memory, disk).
  • Deployment — commands to go from zero to a running stack.
  • Backups — the three backup layers and how to restore.
  • Gotchas — known quirks and footguns worth knowing before you touch the stack.

Architecture at a glance

Physical host (bare metal)
└── swarm-media  Docker Swarm worker, label tier=media
                 runs the Media and Experimental stacks

Proxmox host (pve)
├── VM: swarm-core     Docker Swarm manager, label tier=core
│                      runs the Core and Important (apps) stacks
├── VM: homeassistant  Home Assistant OS (appliance)
├── VM: pihole         DNS (appliance)
├── VM: nextcloud      Nextcloud AIO (appliance)
└── VM: unifi          UniFi OS Server (appliance)
  • Ingress: Traefik is the only service publishing host ports (80/443). Every other service, including the appliance VMs, is reached through Traefik on its own <service>.lab.riversfamily.uk subdomain.
  • Identity: Authentik is the single identity provider. Services that support OIDC/SAML use it natively; everything else sits behind Authentik's Traefik forward-auth middleware. See Services → authentication for the mode each service actually uses.
  • Storage: database and cache volumes are local to the node they run on (never NFS); application/file data and backup archives live on a shared NFS export.
  • Backups: Proxmox VM images, per-service database dumps, and an offsite Duplicati copy. See Backups.

Keeping this site up to date

Adding a stack means adding its page under content/services/<tier>/<name>.md in this site (docs/site/). docs/site/tests/test_service_coverage.sh fails the build if a stack under ansible/stacks/<tier>/<name>/ has no matching page, and docs/site/tests/test_vault_variable_coverage.sh fails it if a vault_* key in ansible/inventory/group_vars/all/vault.yml.example isn't listed on the vault variables page. Run make test in docs/site/ after any stack or vault change.