homelab-docs/docs/NETWORK-ARCHITECTURE.md

Network Architecture - Fred's Homelab

Last Updated: 2026-02-06 02:17 UTC
Documented by: Funky (OpenClaw)

---

Network Overview

Fred's homelab uses a multi-layer network architecture with WireGuard VPN connecting the external VPS to the internal network via a UniFi Cloud Gateway Ultra.

---

Network Subnets

10.0.10.0/24 - Main Homelab Network

Gateway: UCG Ultra (UniFi Cloud Gateway) Purpose: Internal services, Proxmox hosts, LXC containers, VMs

Key IPs:

• 10.0.10.2 - router-pve (Proxmox host)
• 10.0.10.3 - main-pve (Proxmox host)
• 10.0.10.4 - pve-storage (Proxmox host)
• 10.0.10.5 - OMV (OpenMediaVault NAS)
• 10.0.10.11 - Fred's iMac (OpenClaw node)
• 10.0.10.15-50 - Services (see SERVICE-MAP.md)

10.0.9.0/24 - WireGuard VPN

Purpose: Secure tunnel between VPS and homelab

Peers:

• 10.0.9.1 - VPS (vps.nianticbooks.com, 51.222.12.162)

  • WireGuard server
  • Runs Caddy for *.nianticbooks.com and *.deadeyeg4ming.vip

• 10.0.9.2 - UCG Ultra (UniFi Cloud Gateway)

  • WireGuard client mode
  • Routes traffic between 10.0.9.0/24 ↔ 10.0.10.0/24

---

Traffic Flow

External Request to Internal Service

Internet User
  ↓
DNS Resolution (*.nianticbooks.com or *.deadeyeg4ming.vip)
  ↓
VPS: 51.222.12.162 (Caddy reverse proxy)
  ↓ WireGuard tunnel
10.0.9.1 (VPS) → 10.0.9.2 (UCG Ultra)
  ↓ Internal routing
10.0.10.x (Internal service - Proxmox LXC/VM)
  ↓ Response back through same path
Internet User

Example: Minecraft Server (atmons.deadeyeg4ming.vip)

Player connects to atmons.deadeyeg4ming.vip
  ↓
DNS → 51.222.12.162
  ↓
VPS Caddy reverse_proxy 10.0.10.46:25567
  ↓ WireGuard
10.0.9.1 → 10.0.9.2 (UCG Ultra)
  ↓
10.0.10.46:25567 (Pterodactyl Wings - Minecraft server)

---

Network Equipment

UCG Ultra (UniFi Cloud Gateway)

• Model: UniFi Cloud Gateway Ultra
• Role: Primary gateway/router for homelab
• WireGuard: Client mode connecting to VPS (10.0.9.1)
• Internal IP: 10.0.10.1 (assumed gateway)
• WireGuard IP: 10.0.9.2
• Routing: Bridges 10.0.9.0/24 ↔ 10.0.10.0/24

VPS (vps.nianticbooks.com)

• Public IP: 51.222.12.162
• Provider: (Unknown - document later)
• WireGuard IP: 10.0.9.1
• Services:
  • Caddy reverse proxy
  • WireGuard VPN server
  • LetsEncrypt SSL termination

---

Caddy Reverse Proxy Configuration

Current Domains

• *.nianticbooks.com - Fred's primary domain
• *.deadeyeg4ming.vip - Gaming/personal domain

Known Subdomains

(Document as they're added)

Example configuration for new subdomain:

atmons.deadeyeg4ming.vip {
    reverse_proxy 10.0.10.46:25567
}

Note: VPS can reach any IP on 10.0.10.0/24 via WireGuard → UCG Ultra routing.

---

Security Notes

WireGuard VPN

• ✅ Traffic between VPS and homelab is encrypted
• ✅ Only authorized WireGuard peers can access homelab
• ✅ Proper network segmentation (10.0.9.x separate from 10.0.10.x)

SSL/TLS

• External: LetsEncrypt via Caddy on VPS (automatic renewal)
• Internal: Step-CA (10.0.10.15) provides internal certificates

Access Control

• UCG Ultra manages firewall rules (document separately)
• WireGuard provides authentication via public/private keys
• No direct port forwarding on public IP (all via VPN tunnel)

---

Deprecated Networks (DO NOT USE)

❌ 10.0.8.0/24

• Old VPN network from previous VPS setup
• Status: DEPRECATED
• Reason: Migrated to 10.0.9.0/24 with current VPS

❌ Old VPS (55.XX.X.X)

• Old peer: 10.0.9.3
• Status: DECOMMISSIONED
• Reason: Replaced with current VPS (51.222.12.162)

Action: Remove any references to 10.0.8.0/24 or old VPS from documentation and configs.

---

Future Considerations

Potential Improvements

1. Document Caddy configuration - SSH into VPS and document current Caddyfile
2. UCG Ultra firewall rules - Document current rules for reference
3. Additional VPN peers - If adding more WireGuard clients, use 10.0.9.3+
4. IPv6 - Consider if needed for future services

Monitoring

• Monitor WireGuard tunnel health
• Alert if VPN connection drops
• Track bandwidth usage on VPN tunnel

---

Quick Reference

VPS Caddy adds new subdomain:

1. SSH to VPS (need to set up SSH key first!)
2. Edit Caddyfile
3. Add reverse_proxy to internal IP (10.0.10.x)
4. Reload Caddy
5. Update this documentation

Internal service IPs: See SERVICE-MAP.md

---

Maintained by: Funky (OpenClaw AI Agent)
Source: http://10.0.10.2:3000/fred/homelab-docs

---

Port Forwarding (Added 2026-02-06)

Minecraft Server - ATM10

• External: 51.222.12.162:25568
• Internal: 10.0.10.46:25568
• Protocol: TCP + UDP
• Method: iptables DNAT + MASQUERADE
• SRV Record: _minecraft._tcp.atmons.deadeyeg4ming.vip → 51.222.12.162:25568

Players connect to: atmons.deadeyeg4ming.vip (SRV record handles port automatically)

iptables rules:

# Forward incoming traffic
iptables -t nat -A PREROUTING -p tcp --dport 25568 -j DNAT --to-destination 10.0.10.46:25568
iptables -t nat -A PREROUTING -p udp --dport 25568 -j DNAT --to-destination 10.0.10.46:25568

# Masquerade for return traffic
iptables -t nat -A POSTROUTING -d 10.0.10.46 -p tcp --dport 25568 -j MASQUERADE
iptables -t nat -A POSTROUTING -d 10.0.10.46 -p udp --dport 25568 -j MASQUERADE

Rules saved to: /etc/iptables/rules.v4 (persists across reboots)