# 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, 66.63.182.168)
  - 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: 66.63.182.168 (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 → 66.63.182.168
  ↓
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:** 66.63.182.168
- **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 (66.63.182.168)

**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*