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:
```caddy
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](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:**
```bash
# 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)