# 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.200 | - | Primary NAS (DS1823xs+) |
| Calypso | 192.168.0.250 | - | Secondary NAS (DS723+), runs NPM |
| Guava | 192.168.0.100 | - | TrueNAS Scale workstation |
| PVE | 192.168.0.205 | - | Proxmox hypervisor |
| Pi-5 | 192.168.0.66 | - | Raspberry Pi 5 |
| Homelab VM | 192.168.0.210 | - | Proxmox VM, monitoring |

---

## Port Forwarding

### External Access

| Service | External Port | Internal IP | Internal Port | Protocol |
|---------|---------------|-------------|----------------|----------|
| NPM HTTP | 80 | 192.168.0.250 | 80 | HTTP |
| NPM HTTPS | 443 | 192.168.0.250 | 443 | HTTPS |
| Headscale | 8443 | 192.168.0.250 | 8085 | TCP (control server) |
| Plex | 32400 | 192.168.0.200 | 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.12.202 | 8123 | VPN only (via GL-MT3000 subnet) |
| Authentik | 192.168.0.250 | 9000 | VPN only |
| Vaultwarden | 192.168.0.200 | 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.200 | Primary NAS (DS1823xs+) |
| calypso | 192.168.0.250 | Secondary NAS (DS723+) |
| guava | 192.168.0.100 | TrueNAS Scale |
| pve | 192.168.0.205 | Proxmox host |
| homelab | 192.168.0.210 | Proxmox VM |
| pi-5 | 192.168.0.66 | Raspberry Pi 5 |

---

## 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.250: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

### Headscale (Primary Mesh VPN)

All nodes use the Tailscale client pointed at the self-hosted Headscale control server.

| Setting | Value |
|---------|-------|
| Control Server | `headscale.vish.gg:8443` |
| Host | Calypso (192.168.0.250) |
| Admin UI | Headplane (via NPM at :8443/admin) |
| DERP Servers | Tailscale public DERP map |
| MagicDNS suffix | `tail.vish.gg` |
| IP Range | 100.64.0.0/10 |
| Exit Nodes | atlantis, calypso, setillo, vish-concord-nuc, seattle, homeassistant |

### WireGuard (Point-to-Point, Secondary)

| Setting | Value |
|---------|-------|
| Server | Concord NUC (wg-easy, port 51820) |
| Interface | Dynamic |
| Use Case | Clients that can't run Tailscale |

---

## 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)

```bash
# 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

```yaml
# 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](../infrastructure/cloudflare-dns.md)
- [WireGuard Guide](../services/individual/wg-easy.md)
- [Headscale Setup](../infrastructure/tailscale-setup-guide.md)
- [Port Forwarding](../infrastructure/port-forwarding-configuration.md)
