homelab-optimized/docs/infrastructure/network-architecture.md

Network Architecture

Homelab network topology and configuration

---

Overview

The homelab uses a multi-layered network architecture with external access via Cloudflare, internal services through Nginx Proxy Manager, and mesh VPN for secure remote access.

---

Network Topology

┌────────────────────────────────────────────────────────────────────┐
│                           INTERNET                                  │
│                   (Public IP via ISP)                              │
└────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌────────────────────────────────────────────────────────────────────┐
│                      CLOUDFLARE                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                │
│  │   DNS       │  │   Proxy     │  │   Tunnels   │                │
│  │   vish.gg   │  │   vish.gg   │  │   (if used) │                │
│  └─────────────┘  └─────────────┘  └─────────────┘                │
└────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌────────────────────────────────────────────────────────────────────┐
│                      HOME NETWORK                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                │
│  │   Router    │  │   Switch    │  │   WiFi AP   │                │
│  │ (Gateway)   │  │  (Managed)  │  │  (Ubiquiti) │                │
│  └─────────────┘  └─────────────┘  └─────────────┘                │
│        │                                        │                  │
│        └──────────────────┬────────────────────┘                  │
│                            │                                         │
│                     ┌──────┴──────┐                                 │
│                     │  VLANs      │                                 │
│                     │  10 (MGMT)  │                                 │
│                     │  20 (IOT)   │                                 │
│                     │  30 (MAIN)  │                                 │
│                     └─────────────┘                                 │
└────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
            ┌───────────┐   ┌───────────┐   ┌───────────┐
            │ ATLANTIS  │   │  CALYPSO  │   │   NUC     │
            │  (NAS)    │   │  (NAS)    │   │  (HA)     │
            └───────────┘   └───────────┘   └───────────┘

---

IP Address Scheme

Subnet Configuration

VLAN	Network	Gateway	DHCP Range	Purpose
10 (MGMT)	192.168.0.0/24	.1	.100-.150	Infrastructure
20 (IOT)	192.168.1.0/24	.1	.100-.200	Smart home
30 (GUEST)	192.168.2.0/24	.1	.100-.150	Guest access

Static Assignments

Host	IP	MAC	Purpose
Atlantis	192.168.0.10	AA:BB:CC:DD:EE:FF	Primary NAS
Calypso	192.168.0.11	AA:BB:CC:DD:EE:FF	Secondary NAS
Concord NUC	192.168.0.20	AA:BB:CC:DD:EE:FF	Home Assistant
Homelab VM	192.168.0.210	-	Monitoring
RPi5	192.168.0.50	-	Edge
Pi-hole	192.168.0.53	-	DNS Primary
AdGuard	192.168.0.54	-	DNS Secondary

---

Port Forwarding

External Access

Service	External Port	Internal IP	Internal Port	Protocol
NPM HTTP	80	192.168.0.11	80	HTTP
NPM HTTPS	443	192.168.0.11	443	HTTPS
WireGuard	51820	192.168.0.11	51820	UDP
Plex	32400	192.168.0.10	32400	TCP

Internal Only (No Port Forward)

Service	Internal IP	Port	Access Method
Grafana	192.168.0.210	3000	VPN only
Prometheus	192.168.0.210	9090	VPN only
Home Assistant	192.168.0.20	8123	VPN only
Authentik	192.168.0.11	9000	VPN only
Vaultwarden	192.168.0.10	8080	VPN only

---

DNS Configuration

Primary: Pi-hole / AdGuard

Upstream DNS:
- 1.1.1.1 (Cloudflare)
- 8.8.8.8 (Google)

Local Domains:
- vish.local
- vish.gg

Local DNS Entries

Hostname	IP	Description
atlantis	192.168.0.10	Primary NAS
calypso	192.168.0.11	Secondary NAS
concord-nuc	192.168.0.20	Intel NUC
homelab	192.168.0.210	Proxmox VM
rpi5	192.168.0.50	Raspberry Pi
pihole	192.168.0.53	Pi-hole
adguard	192.168.0.54	AdGuard

---

Reverse Proxy Flow

External Request (vish.gg)

1. User → https://service.vish.gg
2. Cloudflare DNS → resolves to home IP
3. Home Router → forwards to 192.168.0.11:443
4. NPM (Calypso) → terminates SSL
5. Authentik (if SSO) → authenticates
6. Backend service → responds
7. NPM → returns to user

Internal Request

1. User → http://service.local (or IP)
2. Pi-hole/AdGuard → resolves to internal IP
3. NPM (optional) or direct → service
4. Response → user

---

VPN Configuration

WireGuard (Primary)

Setting	Value
Server	calypso.vish.local:51820
Interface	10.0.0.1/24
Clients	Dynamic (pre-shared key)
Persistent Keepalive	25 seconds

Headscale (Mesh)

Setting	Value
Control Server	headscale.vish.local
Namespace	homelab
DERP Servers	Enabled
Exit Node	Enabled

Tailscale (Backup)

Setting	Value
Control	tailscale.io
ACL	Defined in headscale
Subnet Router	Enabled

---

VLAN Configuration

Management VLAN (10)

• Devices: NAS, switches, APs
• Access: Admin only
• Internet: Full

IoT VLAN (20)

• Devices: Smart home, cameras
• Access: Restricted
• Internet: Filtered (Pi-hole)
• Isolation: Yes

Main VLAN (30)

• Devices: Personal devices
• Access: Full
• Internet: Full

---

Firewall Rules

Router (UFW/iptables)

# Allow established connections
iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# Allow SSH
iptables -A INPUT -p tcp --dport 22 -j ACCEPT

# Allow HTTP/HTTPS
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT

# Allow WireGuard
iptables -A INPUT -p udp --dport 51820 -j ACCEPT

# Drop everything else
iptables -A INPUT -j DROP

Docker Network

# docker-compose.yml
networks:
  default:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/24

---

Monitoring

Network Metrics

Metric	Source	Dashboard
Bandwidth	Node Exporter	Network
Packet loss	Prometheus	Network
DNS queries	Pi-hole	DNS
VPN connections	WireGuard	VPN

---

Troubleshooting

Cannot Access Service

1. Check DNS: nslookup service.vish.local
2. Check connectivity: ping 192.168.0.x
3. Check port: nc -zv 192.168.0.x 443
4. Check service: curl -I http://localhost:PORT
5. Check firewall: sudo iptables -L

Slow Network

1. Check bandwidth: iperf3 -c 192.168.0.x
2. Check for interference (WiFi)
3. Check switch port speed
4. Check for broadcast storms

VPN Issues

1. Check WireGuard status: wg show
2. Check Headscale nodes: headscale nodes list
3. Verify firewall allows UDP 51820
4. Check NAT traversal

---

Links

• Cloudflare Setup
• WireGuard Guide
• Headscale Setup
• Port Forwarding