rp5-homelab/README.md

RP5 Homelab Infrastructure

A comprehensive home automation and network management setup running on Raspberry Pi 5.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        INTERNET                                  │
└─────────────────────────┬───────────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────────┐
│              hofmanns.ai (185.143.102.153)                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Caddy     │  │  WireGuard  │  │      Headscale          │  │
│  │  (HTTPS)    │  │    Easy     │  │   (Tailscale Server)    │  │
│  │  :80/:443   │  │  :51820/udp │  │                         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────┬───────────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │ WireGuard VPN   │   Tailscale     │
        │                 │                 │
┌───────▼─────────────────▼─────────────────▼─────────────────────┐
│                    Router (192.168.1.1)                          │
└─────────────────────────┬───────────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────────┐
│              Raspberry Pi 5 (192.168.1.50)                       │
│                    rp5.hofmanns.net                              │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                     Docker Services                          ││
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       ││
│  │  │Home Assistant│  │   Portainer  │  │  AdGuard Home│       ││
│  │  │    :8123     │  │ :9000/:9443  │  │  :3000/:53   │       ││
│  │  └──────────────┘  └──────────────┘  └──────────────┘       ││
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       ││
│  │  │    Caddy     │  │  Media Hub   │  │    ttyd      │       ││
│  │  │   :80/:443   │  │    :3001     │  │    :7681     │       ││
│  │  └──────────────┘  └──────────────┘  └──────────────┘       ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                    Tailscale Client                          ││
│  │              100.64.0.1 (pike-crocodile.ts.net)              ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Services

Local Services (RP5 - 192.168.1.50)

Service	Port	URL	Description
Home Assistant	8123	http://192.168.1.50:8123	Home automation platform
Portainer	9000/9443	http://192.168.1.50:9000	Docker management UI
AdGuard Home	3000	http://192.168.1.50:3000	DNS-based ad blocking
ttyd	7681	http://192.168.1.50:7681	Web-based terminal
Caddy	80/443	-	Reverse proxy
Media Hub	3001	http://192.168.1.50:3001	Media aggregator

Remote Services (hofmanns.ai - 185.143.102.153)

Service	Port	URL	Description
WireGuard Easy	51820/udp	-	VPN server
WireGuard UI	51821	https://vpn.hofmanns.tech	VPN management
Caddy	80/443	https://hofmanns.tech	Reverse proxy

VPN Access

WireGuard (Primary VPN)

• Admin UI: https://vpn.hofmanns.tech
• Password: HofmannVPN2024!
• Server: 185.143.102.153:51820/udp
• DNS: 1.1.1.1, 8.8.8.8

Adding a new client:

1. Open https://vpn.hofmanns.tech
2. Click "New Client"
3. Enter device name (e.g., "Pixel", "Laptop")
4. Scan QR code with WireGuard app or download config

Tailscale (Mesh VPN)

• Network: hofmanns.net (self-hosted Headscale)
• RP5 Hostname: rp5.hofmanns.net
• Tailscale IP: 100.64.0.1

Home Assistant Dashboards

System Admin Dashboard (/admin)

The System Admin dashboard provides centralized management with embedded iframes:

• Terminal: Web-based SSH via ttyd
• Router Admin: Direct access to router config
• Portainer: Docker container management
• AdGuard Home: DNS and ad-blocking settings

Other Dashboards

• Home (/home): Main dashboard
• Media Hub (/media): Streaming services aggregator
• Bluetooth Manager (/bluetooth): BT device control

Docker Compose Files

WireGuard Easy (hofmanns.ai)

# ~/wg-easy/docker-compose.yml
services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy
    container_name: wg-easy
    environment:
      - LANG=de
      - WG_HOST=185.143.102.153
      - PASSWORD_HASH=$2a$12$ZoO7nm4N8HfYnSyU/ghA0eIFc4YkEqa1oX0qzAv.0Wm/./uNZwnGm
      - WG_DEFAULT_DNS=1.1.1.1,8.8.8.8
      - WG_PERSISTENT_KEEPALIVE=25
      - UI_TRAFFIC_STATS=true
      - UI_CHART_TYPE=1
    volumes:
      - ./config:/etc/wireguard
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped

Caddy Configuration (hofmanns.ai)

# /etc/caddy/Caddyfile
hofmanns.tech {
    reverse_proxy localhost:8080
}

vpn.hofmanns.tech {
    reverse_proxy localhost:51821
}

Network Configuration

DNS Resolution

• Primary DNS: AdGuard Home (192.168.1.50:53)
• Tailscale DNS: 100.100.100.100 (MagicDNS)
• Search Domain: hofmanns.net

IP Addresses

Device	IP	Tailscale IP
Router	192.168.1.1	-
RP5	192.168.1.50	100.64.0.1
hofmanns.ai	185.143.102.153	-

Quick Commands

Docker Management

# View all containers
docker ps -a

# Restart Home Assistant
docker restart homeassistant

# View logs
docker logs -f homeassistant

# Portainer logs
docker logs portainer

Tailscale

# Check status
tailscale status

# Check IP
tailscale ip

# Ping device
tailscale ping <hostname>

WireGuard (on hofmanns.ai)

# Check VPN status
docker logs wg-easy

# Restart VPN
cd ~/wg-easy && docker compose restart

Maintenance

Backup Locations

• Home Assistant config: /var/lib/docker/volumes/homeassistant_config/_data/
• WireGuard config: ~/wg-easy/config/ (on hofmanns.ai)
• AdGuard config: /opt/AdGuardHome/

Updates

# Update all Docker containers
docker compose pull && docker compose up -d

# Update Home Assistant
docker pull ghcr.io/home-assistant/home-assistant:stable
docker restart homeassistant

Troubleshooting

Home Assistant not loading

docker logs homeassistant --tail 50
docker restart homeassistant

VPN not connecting

1. Check server status: ssh ubuntu@hofmanns.ai "docker ps | grep wg-easy"
2. Verify port is open: nc -zvu 185.143.102.153 51820
3. Check logs: ssh ubuntu@hofmanns.ai "docker logs wg-easy"

DNS issues

# Test DNS resolution
dig @192.168.1.50 google.com
nslookup google.com 100.100.100.100

---

Project Info

• Created: 2025-12-02
• Author: Claude Code (Anthropic)
• Location: Raspberry Pi 5 Homelab
• Repository: hofmanns.ai:~/projects/rp5-homelab