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