UniFi Multi-Network & Declarative Homelab

Reference Architecture & Reading Guide at brukt.tech

UniFi Network & Homelab Architecture

Reference architecture for a segmented UniFi home network and an optional rootless homelab platform. Configure the core network in the UniFi web interface first. Add server infrastructure and external ingress when required.

The Four Stages (Progressive Progression)

Phase 1 · UniFi GUI Only

Home Network Foundation

Complete segmented home network on 1x UDM Pro, switch, and access points with zero servers or CLI required.

  • Core VLANs: default (10.0.1.0/24), house (10.0.10.0/24), media (10.0.20.0/24), guests (10.0.30.0/24)
  • Same-VLAN Dual-SSID on VLAN 10 (house-users 5/6 GHz & house-printer 2.4 GHz) for effortless printing
  • Encrypted DNS (Quad9 DNSCrypt + DNS.SB) & Zone-Based Firewall isolation
Milestone DoD: Printer discovery works on VLAN 10; guests and media devices blocked from 10.0.1.1:22/443. Home users can stop here.
Read Phase 1 →
Phase 2 · Day-1 Bootstrap

Declarative Homelab & Day-1 IdP

Isolated office-main (10.0.40.0/24) and office-dev (10.0.50.0/24, Lab zone) on standalone Proxmox VE.

  • Day-1 Foundation: ./suite, 1Password (op run zero cleartext on disk), and rootless Authelia IdP + local Traefik TLS (10.0.50.70:443, auth.example.com, MicroOS VM 200)
  • Downstream OIDC apps: Proxmox VE WebAuthn, Forgejo, Immich (LXC 452), GoToSocial (LXC 451), Grafana
Milestone DoD: ./suite apply deploy_idp live with DNS-01 TLS and zero cleartext secret files; apps onboarded via OIDC.
Read Phase 2 →
Phase 3 · Zero-Trust Ingress

Edge VPS & WireGuard Tunnel

Public service exposure without opening any inbound ports on your home router firewall.

  • Hardened transactional openSUSE Leap Micro Edge VPS (198.51.100.x / 203.0.113.x)
  • 100% rootless Podman Quadlets under UID 1000 (edge): Pangolin, Gerbil, Traefik (deSEC DNS-01)
  • Outbound WireGuard site connector (Newt in unprivileged LXC 450)
  • Live Service: Documentation reader published via Newt & Pangolin resource (Guide § 12)
Milestone DoD: Outbound WireGuard tunnel active with zero router port forwards; auth.example.com stays LAN-only.
Read Phase 3 →
Phase 4 · Optional Appendices

Specialized Extensions & Probes

Advanced modules separated from the foundational path so Phases 1–3 stay lean.

  • Cascaded UDM Pro #2 over 192.168.1.0/24 transit and 10.10.10.0/24 cluster subnet
  • Multi-node Proxmox VE Corosync/QDevice cluster preparation
  • Hardware Raspberry Pi firewall probes (scripts/policy_probe.py) & PSI telemetry
Milestone DoD: Empirical ./suite policy probe matrix and ./suite sec sanitization checks pass.
Read Phase 4 →

Categorized Guide Directory (29 Guides in docs/*.md)

Core Reference, Glossary & Security Standards

docs/glossary.md implemented

One-way glossary of networking, Linux, container, and UniFi claim source labels.

Read Guide →
docs/sanitization_and_privacy_standards.md implemented

RFC 5737/2606 placeholder standards, SSID anonymization, and security gate verification.

Read Guide →
docs/settings_overview.md implemented

Where settings live across the repository and how ./suite locates private environment files.

Read Guide →
docs/configuration_model_plan.md planned

Declarative configuration model, inventory schema, state validation, and preflight architecture.

Read Guide →

Phase 1: Home Network Foundation (UniFi GUI Only)

docs/unifi_firewall_policies.md implemented

Zone-Based Firewall policies closing inter-VLAN and gateway admin port (TCP 22/443) exposure.

Read Guide →
docs/unifi_dns_and_wan_transition.md implemented

Encrypted DNS (Quad9 DNSCrypt + DNS.SB) on the UDM Pro and WAN transition behavior.

Read Guide →
docs/ipv6_notes.md planned

IPv6 prefix delegation (DHCPv6-PD), SLAAC, and per-network IPv6 isolation notes.

Read Guide →

Phase 2: Declarative Homelab, Day-1 Authelia IdP & OIDC Services

docs/idp_guide.md operational

Day-1 Authelia IdP & local Traefik TLS (10.0.50.70:443, auth.example.com), 1Password op run, OIDC clients, backup.

Read Guide →
docs/idp_comparison.md planned

Comparison of Authelia and Rauthy as the homelab OIDC identity provider per client.

Read Guide →
docs/ansible_guide.md partly implemented

Declarative Ansible automation with dry-run-first (./suite check) and 1Password secret injection.

Read Guide →
docs/proxmox_users.md implemented

Declarative Proxmox VE user accounts (Linux/PAM) and Authelia OIDC realm onboarding.

Read Guide →
docs/self_hosted_forge_plan.md planned

Self-hosted Tangled knot/spindle and private Forgejo integrated with Authelia OIDC.

Read Guide →
docs/git_ssh_signing_guide.md implemented

Git SSH commit signing setup and verification workflow.

Read Guide →
docs/git_practice_guide.md implemented

Signed commits, linear history (--ff-only), Git hooks, and ./suite git operations.

Read Guide →
docs/immich_photos_ingress_deployment_guide.md partly implemented

Immich photo service in unprivileged LXC 452 with Authelia OIDC and tunnel ingress.

Read Guide →
docs/immich_upgrade_plan.md planned

Immich version lifecycle, database migration safeguards, backup verification, and upgrade runbook.

Read Guide →
docs/photo_service_comparison.md planned

Immich vs. Ente evaluation and web interface latency measurement plan.

Read Guide →
docs/container_images_and_isolation.md partly implemented

Container isolation boundaries, rootless Podman, unprivileged LXC, and image digest pinning.

Read Guide →
docs/backup_and_recovery.md partly implemented

Backup scope, retention, and recovery procedures for Proxmox VE, IdP, and LXC services.

Read Guide →
docs/cross_machine_transfer_guide.md implemented

Workstation-to-workstation transfers and AirDrop troubleshooting across VLANs.

Read Guide →
docs/lab_monitoring.md planned

Prometheus, Grafana (with Authelia Generic OAuth / OIDC), Alertmanager, and PSI metrics.

Read Guide →

Phase 3: Zero-Trust External Ingress (Edge VPS & WireGuard Tunnel)

docs/edge_vps_security_and_rootless_architecture.md implemented

openSUSE Leap Micro Edge VPS hardening, rootless Podman Quadlets (Pangolin, Gerbil, Traefik), DNS-01 TLS.

Read Guide →
docs/homelab_ingress_and_least_privilege_architecture.md partly implemented

Outbound Newt WireGuard connector (LXC 450), GoToSocial (LXC 451), and publishing documentation portal via Pangolin resource.

Read Guide →
docs/vpn_and_ingress_architecture_analysis.md implemented

Comparison of WireGuard, Tailscale/Headscale, and Pangolin for external homelab ingress.

Read Guide →
docs/threat_model_and_tradeoffs.md partly implemented

Threat model, trust boundaries, and architectural trade-offs across the Edge VPS and homelab.

Read Guide →

Phase 4: Specialized Extensions, Hardware Probes & Engineering Log

docs/homelab_multi_gateway_guide.md partly implemented

Cascaded UDM Pro #2 (192.168.1.0/24 transit, 10.10.10.0/24), Proxmox cluster prep, NAS & Raspberry Pi Kafka.

Read Guide →
docs/network_policy_testing.md implemented

Empirical firewall verification across VLANs using Raspberry Pi probes and scripts/policy_probe.py.

Read Guide →
docs/connectivity_probes_plan.md planned

Continuous DNS, ICMP, and HTTP connectivity probes with outage alerting.

Read Guide →
docs/feilsokingshistorikk.md implemented

Standalone chronological engineering and troubleshooting log (5-field schema, Norwegian).

Read Guide →
Document Title
Raw Markdown

Loading document...