Skip to content

Current architecture

Last broad verification: 2026-07-17. Volatile values belong in the linked canonical reference pages.

Purpose

KH3 uses one Proxmox host for on-premises compute. OPNsense is the routed security boundary. Dedicated LXCs separate DNS, public ingress, applications, subnet routing, and remote-support infrastructure. A public VPS provides the Headscale control plane.

flowchart LR
    Internet --> FW["OPNsense VM 100"]
    Admin["LAN / tailnet administrators"] --> FW
    FW --> DMZ["DMZ 192.168.2.0/24"]
    PVE["Proxmox pve"] --> FW
    PVE --> Apps["CT 101 rootless Podman"]
    PVE --> DNS["CT 102 Technitium"]
    PVE --> Ingress["CT 103 Caddy ingress"]
    PVE --> Site["CT 104 khysite"]
    PVE --> Router["CT 105 ts-router"]
    PVE --> RD["CT 106 RustDesk"]
    Ingress --> Apps
    Apps --> Data["PostgreSQL + application data"]
    Apps --> Docs["docs-static :30084"]
    Ingress --> Docs
    VPS["ovps-me: Headscale + Headplane + Caddy"] --> Router

Architectural layers

Layer Current implementation Canonical record
Physical compute Dell OptiPlex 7040 Hardware inventory
Virtualization Proxmox VE pve Inventory
Routing and policy OPNsense VM 100 Network
Application runtime Rootless Podman as podsvc in CT 101 Podman standard
DNS Technitium in CT 102 Technitium
HTTP ingress Caddy in CT 103 Caddy operations
Remote network Headscale VPS and CT 105 subnet router Remote access
Documentation Forgejo Actions, shared publish volume, static Caddy backend Publishing

Why the layers are separate

  • Rootless Podman limits application processes to the podsvc user and keeps application data under /opt/podman.
  • DNS and ingress start independently of the shared application host and bind low ports without broadening CT 101 privileges.
  • CT 105 owns subnet routing so Proxmox is not the normal route-forwarding endpoint.
  • Generated documentation remains with the Forgejo runner data on CT 101; ingress Caddy proxies it instead of mounting another guest's filesystem.

The decisions and alternatives are recorded in ADRs.

Recovery order

  1. Physical power, switching, and upstream connectivity.
  2. Proxmox storage and host networking.
  3. OPNsense routing.
  4. Technitium DNS and CT 105 remote route.
  5. Caddy ingress.
  6. CT 101 PostgreSQL and application services.
  7. Optional and business application services.

Use the dependency map and infrastructure validation runbook during an incident.