====== Network Architecture ======

The AI-Homelab uses a sophisticated network architecture designed for security, performance, and scalability.

===== Network Topology =====

```
Internet
    ↓
[Router/Firewall]
    ├── Port 80 (HTTP) → Traefik (Let's Encrypt)
    ├── Port 443 (HTTPS) → Traefik (SSL Termination)
    └── Port 22 (SSH) → Server (Management)
    ↓
[DuckDNS] Dynamic DNS
    ↓
[Traefik] Reverse Proxy
    ├── Authelia SSO Middleware
    ├── Service Routing
    └── SSL Termination
    ↓
[Docker Networks]
    ├── traefik-network (Web Services)
    ├── homelab-network (Internal)
    ├── media-network (Media Services)
    └── service-specific networks
```

===== Docker Networks =====

**traefik-network (Primary):**
  * **Purpose**: All web-accessible services
  * **Driver**: Bridge
  * **IP Range**: 172.20.0.0/16
  * **External Access**: Yes (via Traefik)

**homelab-network (Internal):**
  * **Purpose**: Internal service communication
  * **Driver**: Bridge
  * **IP Range**: 172.21.0.0/16
  * **External Access**: No

**media-network:**
  * **Purpose**: Media service isolation
  * **Driver**: Bridge
  * **IP Range**: 172.22.0.0/16
  * **External Access**: Via Traefik

**dockerproxy-network:**
  * **Purpose**: Docker socket proxy
  * **Driver**: Bridge
  * **Security**: Restricted access

===== Traefik Routing =====

**Entry Points:**
```yaml
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"
    http:
      tls:
        certResolver: letsencrypt
```

**Router Configuration:**
```yaml
http:
  routers:
    service-router:
      rule: "Host(`service.yourdomain.duckdns.org`)"
      entryPoints:
        - websecure
      service: service-name
      tls:
        certResolver: letsencrypt
      middlewares:
        - authelia@docker
```

**Service Discovery:**
```yaml
http:
  services:
    service-name:
      loadBalancer:
        servers:
          - url: "http://container-name:port"
```

===== SSL/TLS Configuration =====

**Certificate Resolver:**
```yaml
certificatesResolvers:
  letsencrypt:
    acme:
      email: your-email@example.com
      storage: /acme.json
      dnsChallenge:
        provider: duckdns
        delayBeforeCheck: 30
```

**Wildcard Certificate:**
  * **Domain**: `*.yourdomain.duckdns.org`
  * **Provider**: Let's Encrypt
  * **Challenge**: DNS-01 (DuckDNS)
  * **Validity**: 90 days
  * **Renewal**: Automatic

**Security Headers:**
```yaml
middlewares:
  security-headers:
    headers:
      stsSeconds: 31536000
      stsIncludeSubdomains: true
      stsPreload: true
      forceSTSHeader: true
      contentTypeNosniff: true
      browserXssFilter: true
      referrerPolicy: "strict-origin-when-cross-origin"
      permissionsPolicy: "geolocation=(), microphone=(), camera=()"
```

===== Authelia Integration =====

**SSO Middleware:**
```yaml
middlewares:
  authelia:
    forwardAuth:
      address: "http://authelia:9091/api/verify?rd=https://auth.yourdomain.duckdns.org/"
      trustForwardHeader: true
      authResponseHeaders:
        - "Remote-User"
        - "Remote-Groups"
        - "Remote-Name"
        - "Remote-Email"
```

**Access Control Rules:**
```yaml
access_control:
  default_policy: deny
  rules:
    - domain: "*.yourdomain.duckdns.org"
      policy: two_factor
    - domain: "jellyfin.yourdomain.duckdns.org"
      policy: bypass
    - domain: "plex.yourdomain.duckdns.org"
      policy: bypass
```

===== VPN Integration =====

**Gluetun Network Mode:**
```yaml
services:
  qbittorrent:
    network_mode: "service:gluetun"
    depends_on:
      - gluetun
```

**Port Mapping:**
```yaml
gluetun:
  ports:
    - "8080:8080"  # qBittorrent Web UI
    - "6881:6881"  # Torrent port
    - "6881:6881/udp"
```

**VPN Routing:**
  * **Provider**: Surfshark (configurable)
  * **Protocol**: WireGuard/OpenVPN
  * **Kill Switch**: Prevents IP leaks
  * **Port Forwarding**: Automatic

===== Firewall Configuration =====

**UFW Rules (Automatic):**
```bash
# Allow SSH
sudo ufw allow ssh

# Allow HTTP/HTTPS
sudo ufw allow 80
sudo ufw allow 443

# Enable firewall
sudo ufw enable

# Default deny
sudo ufw default deny incoming
sudo ufw default allow outgoing
```

**Docker Security:**
  * **No privileged containers**
  * **Non-root user execution**
  * **Minimal port exposure**
  * **Network isolation**

===== External Service Proxying =====

**Traefik File Provider:**
```yaml
http:
  routers:
    external-service:
      rule: "Host(`external.yourdomain.duckdns.org`)"
      service: external-service
      middlewares:
        - authelia@docker
  services:
    external-service:
      loadBalancer:
        servers:
          - url: "http://192.168.1.100:8123"
```

**Use Cases:**
  * **Home Assistant** on Raspberry Pi
  * **NAS devices** (TrueNAS, Unraid)
  * **Network printers** and IoT devices
  * **Legacy applications**

===== DNS Configuration =====

**DuckDNS Setup:**
  * **Update Interval**: Every 5 minutes
  * **API Token**: Stored in `.env`
  * **Domains**: yourdomain.duckdns.org
  * **Wildcard**: *.yourdomain.duckdns.org

**Pi-hole Integration:**
  * **Upstream DNS**: Quad9, Cloudflare
  * **Ad Blocking**: Enabled
  * **Local DNS**: Service discovery
  * **DHCP**: Optional

===== Network Troubleshooting =====

**Connectivity Issues:**
```bash
# Check network connectivity
ping -c 4 8.8.8.8

# Test DNS resolution
nslookup yourdomain.duckdns.org

# Check port forwarding
curl -I http://your-external-ip
```

**Docker Network Issues:**
```bash
# List networks
docker network ls

# Inspect network
docker network inspect traefik-network

# Check container connectivity
docker exec container-name ping traefik
```

**SSL Certificate Problems:**
```bash
# Check certificate
echo | openssl s_client -connect yourdomain.duckdns.org:443 -servername service.yourdomain.duckdns.org 2>/dev/null | openssl x509 -noout -subject -dates

# View Traefik logs
docker logs traefik | grep certificate
```

**Authelia Issues:**
```bash
# Check Authelia logs
docker logs authelia

# Test authentication
curl -k https://auth.yourdomain.duckdns.org/api/state
```

===== Performance Optimization =====

**Connection Pooling:**
  * **Keep-Alive**: Persistent connections
  * **Connection Reuse**: Reduce overhead
  * **Load Balancing**: Distribute traffic

**Caching:**
  * **Browser Caching**: Static assets
  * **Reverse Proxy**: Dynamic content
  * **DNS Caching**: Pi-hole

**Compression:**
  * **Gzip**: Text compression
  * **Brotli**: Advanced compression
  * **Media**: No compression (already compressed)

===== Monitoring =====

**Network Monitoring:**
  * **Traefik Dashboard**: Routing metrics
  * **Authelia Logs**: Authentication events
  * **Pi-hole Stats**: DNS queries
  * **Uptime Kuma**: Service availability

**Traffic Analysis:**
  * **Request Logs**: Access patterns
  * **Error Rates**: Service health
  * **Response Times**: Performance metrics
  * **Bandwidth Usage**: Network utilization

This network architecture provides secure, efficient, and scalable connectivity for all homelab services.

**Next:** Learn about [[architecture:security|Security Architecture]] or [[architecture:storage|Storage Strategy]].