From 98db3582c8439a1d712c25ee8bc87b79b1300d9a Mon Sep 17 00:00:00 2001 From: Hofmann Engineer Date: Tue, 2 Dec 2025 03:48:02 +0000 Subject: [PATCH] Update README with complete service documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added Forgejo git server info - Quick access table - All credentials and URLs - Docker compose examples - Network overview 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 255 ++++++++++++++++++++++++------------------------------ 1 file changed, 112 insertions(+), 143 deletions(-) diff --git a/README.md b/README.md index 8b2964f..abd8bef 100644 --- a/README.md +++ b/README.md @@ -11,11 +11,11 @@ A comprehensive home automation and network management setup running on Raspberr │ ┌─────────────────────────▼───────────────────────────────────────┐ │ hofmanns.ai (185.143.102.153) │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ -│ │ Caddy │ │ WireGuard │ │ Headscale │ │ -│ │ (HTTPS) │ │ Easy │ │ (Tailscale Server) │ │ -│ │ :80/:443 │ │ :51820/udp │ │ │ │ -│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Caddy │ │ WireGuard │ │ Forgejo │ │ +│ │ (HTTPS) │ │ Easy │ │ (Git UI) │ │ +│ │ :80/:443 │ │ :51820/udp │ │ :3030 │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────┬───────────────────────────────────────┘ │ ┌─────────────────┼─────────────────┐ @@ -48,71 +48,90 @@ A comprehensive home automation and network management setup running on Raspberr └─────────────────────────────────────────────────────────────────┘ ``` +## Quick Access + +| Service | URL | Description | +|---------|-----|-------------| +| **Git** | https://git.hofmanns.tech | Source code & configs | +| **VPN Admin** | https://vpn.hofmanns.tech | WireGuard management | +| **Home Assistant** | http://192.168.1.50:8123 | Home automation | +| **Portainer** | http://192.168.1.50:9000 | Docker management | +| **AdGuard Home** | http://192.168.1.50:3000 | DNS & ad blocking | +| **Terminal** | http://192.168.1.50:7681 | Web SSH (ttyd) | +| **Router** | http://192.168.1.1 | Network config | + ## Services -### Local Services (RP5 - 192.168.1.50) +### Remote (hofmanns.ai - 185.143.102.153) -| 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 | +| Service | Port | URL | +|---------|------|-----| +| Caddy (HTTPS) | 80/443 | https://hofmanns.tech | +| WireGuard Easy | 51820/udp | VPN tunnel | +| WireGuard UI | 51821 | https://vpn.hofmanns.tech | +| Forgejo (Git) | 3030 | https://git.hofmanns.tech | +| Forgejo SSH | 2222 | git@git.hofmanns.tech:2222 | -### Remote Services (hofmanns.ai - 185.143.102.153) +### Local (RP5 - 192.168.1.50) -| 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 | +| Service | Port | Description | +|---------|------|-------------| +| Home Assistant | 8123 | Home automation platform | +| Portainer | 9000/9443 | Docker management UI | +| AdGuard Home | 3000/53 | DNS-based ad blocking | +| ttyd | 7681 | Web-based terminal | +| Caddy | 80/443 | Reverse proxy | +| Media Hub | 3001 | Media aggregator | ## VPN Access -### WireGuard (Primary VPN) +### WireGuard (Primary) -- **Admin UI**: https://vpn.hofmanns.tech -- **Password**: `HofmannVPN2024!` -- **Server**: 185.143.102.153:51820/udp -- **DNS**: 1.1.1.1, 8.8.8.8 +``` +Server: 185.143.102.153:51820/udp +Admin UI: https://vpn.hofmanns.tech +Password: HofmannVPN2024\! +DNS: 1.1.1.1, 8.8.8.8 +``` -**Adding a new client:** -1. Open https://vpn.hofmanns.tech +**Add new client:** +1. Go to 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 +3. Scan QR with WireGuard app -### Tailscale (Mesh VPN) +### Tailscale (Mesh) -- **Network**: hofmanns.net (self-hosted Headscale) -- **RP5 Hostname**: rp5.hofmanns.net -- **Tailscale IP**: 100.64.0.1 +``` +Network: hofmanns.net (Headscale) +RP5: rp5.hofmanns.net (100.64.0.1) +``` ## Home Assistant Dashboards -### System Admin Dashboard (`/admin`) +- **Home** (`/home`) - Main dashboard +- **Media Hub** (`/media`) - Streaming services +- **Bluetooth** (`/bluetooth`) - BT device control +- **System Admin** (`/admin`) - Terminal, Router, Portainer, AdGuard iframes -The System Admin dashboard provides centralized management with embedded iframes: +## Git Repository -- **Terminal**: Web-based SSH via ttyd -- **Router Admin**: Direct access to router config -- **Portainer**: Docker container management -- **AdGuard Home**: DNS and ad-blocking settings +```bash +# Clone via HTTPS +git clone https://git.hofmanns.tech/hofmann/rp5-homelab.git -### Other Dashboards +# Clone via SSH +git clone ssh://git@git.hofmanns.tech:2222/hofmann/rp5-homelab.git -- **Home** (`/home`): Main dashboard -- **Media Hub** (`/media`): Streaming services aggregator -- **Bluetooth Manager** (`/bluetooth`): BT device control +# Git credentials +Username: hofmann +Password: HofmannGit2024\! +``` ## Docker Compose Files -### WireGuard Easy (hofmanns.ai) +### WireGuard Easy ```yaml -# ~/wg-easy/docker-compose.yml services: wg-easy: image: ghcr.io/wg-easy/wg-easy @@ -120,11 +139,10 @@ services: environment: - LANG=de - WG_HOST=185.143.102.153 - - PASSWORD_HASH=$2a$12$ZoO7nm4N8HfYnSyU/ghA0eIFc4YkEqa1oX0qzAv.0Wm/./uNZwnGm + - PASSWORD_HASH=$2a$12$... - 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: @@ -135,14 +153,33 @@ services: - SYS_MODULE sysctls: - net.ipv4.ip_forward=1 - - net.ipv4.conf.all.src_valid_mark=1 restart: unless-stopped ``` -### Caddy Configuration (hofmanns.ai) +### Forgejo (Git) + +```yaml +services: + gitea: + image: codeberg.org/forgejo/forgejo:7 + container_name: gitea + environment: + - USER_UID=1000 + - USER_GID=1000 + - FORGEJO__server__ROOT_URL=https://git.hofmanns.tech/ + - FORGEJO__server__HTTP_PORT=3030 + volumes: + - ./data:/data + - /home/ubuntu/git:/data/git/repositories + ports: + - "3030:3030" + - "2222:22" + restart: unless-stopped +``` + +### Caddy (hofmanns.ai) ```caddyfile -# /etc/caddy/Caddyfile hofmanns.tech { reverse_proxy localhost:8080 } @@ -150,109 +187,41 @@ hofmanns.tech { vpn.hofmanns.tech { reverse_proxy localhost:51821 } + +git.hofmanns.tech { + reverse_proxy localhost:3030 +} ``` -## Network Configuration +## Quick Commands -### DNS Resolution +```bash +# Docker +docker ps -a +docker restart homeassistant +docker logs -f homeassistant -- **Primary DNS**: AdGuard Home (192.168.1.50:53) -- **Tailscale DNS**: 100.100.100.100 (MagicDNS) -- **Search Domain**: hofmanns.net +# Tailscale +tailscale status +tailscale ping rp5 -### IP Addresses +# SSH to hofmanns.ai +ssh -i ~/.ssh/hofmanns_ai_key ubuntu@hofmanns.ai -| Device | IP | Tailscale IP | -|--------|-----|--------------| +# WireGuard status +ssh ubuntu@hofmanns.ai "docker logs wg-easy" +``` + +## Network + +| Device | LAN 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 -``` - -### 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 -``` +**DNS**: AdGuard Home (192.168.1.50:53) / Tailscale MagicDNS (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 +**Created**: 2025-12-02 | **Author**: Claude Code