commit 072dbb7426c222b62fb1c0810c87c87efba2c526
Author: Hofmann Engineer <hofmann.engineer@gmail.com>
Date:   Tue Dec 2 03:33:26 2025 +0000

    Initial commit: RP5 Homelab Infrastructure documentation
    
    - Architecture overview with network diagram
    - Service documentation (HA, Portainer, AdGuard, ttyd)
    - WireGuard VPN setup and configuration
    - Tailscale/Headscale mesh VPN details
    - Docker compose files
    - Maintenance and troubleshooting guides
    
    🤖 Generated with Claude Code (https://claude.com/claude-code)
    
    Co-Authored-By: Claude <noreply@anthropic.com>

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8b2964f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,258 @@
+# 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)
+
+```yaml
+# ~/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)
+
+```caddyfile
+# /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
+
+```bash
+# View all containers
+docker ps -a
+
+# Restart Home Assistant
+docker restart homeassistant
+
+# View logs
+docker logs -f homeassistant
+
+# Portainer logs
+docker logs portainer
+```
+
+### Tailscale
+
+```bash
+# Check status
+tailscale status
+
+# Check IP
+tailscale ip
+
+# Ping device
+tailscale ping <hostname>
+```
+
+### WireGuard (on hofmanns.ai)
+
+```bash
+# 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
+
+```bash
+# 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
+```bash
+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
+```bash
+# 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