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>
This commit is contained in:
commit
072dbb7426
258
README.md
Normal file
258
README.md
Normal file
|
|
@ -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
|
||||||
Loading…
Reference in a new issue