chore(homelab): add homelab plans, frpc deploy script, odysseus workspace, heretic docs
This commit is contained in:
Patrick Plate
@@ -0,0 +1,262 @@
|
||||
# Homelab Proxy Architecture Plan
|
||||
_plate.software VPS as public face → WireGuard tunnel → TrueNAS.local_
|
||||
|
||||
## Goal
|
||||
|
||||
Use the cheap public VPS (`plate.software` @ 85.214.154.199 / Plesk) as:
|
||||
- Public DNS + TLS termination point
|
||||
- Apache reverse proxy routing subdomains to TrueNAS homelab services
|
||||
- ACME/Let's Encrypt managed by Plesk (already working)
|
||||
|
||||
TrueNAS.local (192.168.188.119) becomes the actual compute host for all Docker services.
|
||||
|
||||
---
|
||||
|
||||
## The Core Problem: TrueNAS is Behind NAT
|
||||
|
||||
TrueNAS lives on a home network. The public VPS cannot reach it directly. A tunnel is required.
|
||||
|
||||
### ⚠️ WireGuard NOT possible — VPS is OpenVZ
|
||||
|
||||
The VPS (`h2970715.stratoserver.net`, Strato) runs on OpenVZ virtualization.
|
||||
WireGuard requires a kernel module — **not loadable in OpenVZ containers**.
|
||||
|
||||
### Recommended Solution: frp (Fast Reverse Proxy)
|
||||
|
||||
```
|
||||
Internet
|
||||
↓ DNS
|
||||
plate.software VPS (85.214.154.199)
|
||||
frps server (port 7000)
|
||||
↓ Apache ProxyPass (HTTP/HTTPS)
|
||||
↓ frp tunnel (TCP, userspace)
|
||||
TrueNAS.local (192.168.188.119)
|
||||
frpc client → connects out to VPS:7000
|
||||
├── Gitea :30008 → git.plate.software → VPS:30008
|
||||
├── WildFly/Java EE :8080 → plate.software → VPS:18080
|
||||
└── Future services :XXXX → app.plate.software
|
||||
```
|
||||
|
||||
**Why frp:**
|
||||
- Pure userspace Go binary — works perfectly on OpenVZ
|
||||
- TrueNAS (frpc) initiates outbound connection — no router port forwarding needed
|
||||
- Encrypted tunnel (TLS optional)
|
||||
- VPS (frps) exposes local ports that Apache proxies to
|
||||
- Zero kernel dependencies
|
||||
|
||||
---
|
||||
|
||||
## Target DNS Routing
|
||||
|
||||
| Domain / Subdomain | Routes to | Notes |
|
||||
|-------------------------|-----------------------------------|-------|
|
||||
| `plate.software` | TrueNAS:8080 (WildFly) | Current customer Java EE project |
|
||||
| `git.plate.software` | TrueNAS:30008 (Gitea) | New — expose homelab Gitea publicly |
|
||||
| `app.plate.software` | TrueNAS:XXXX (future) | Placeholder for future projects |
|
||||
|
||||
All DNS A records point to `85.214.154.199` (VPS). TLS is terminated at the VPS by Plesk/Let's Encrypt.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Phase 1: WireGuard Tunnel (VPS ↔ TrueNAS)
|
||||
|
||||
**On the VPS (root@85.214.154.199):**
|
||||
```bash
|
||||
apt install wireguard
|
||||
wg genkey | tee /etc/wireguard/server_private.key | wg pubkey > /etc/wireguard/server_public.key
|
||||
```
|
||||
|
||||
Create `/etc/wireguard/wg0.conf`:
|
||||
```ini
|
||||
[Interface]
|
||||
Address = 10.100.0.1/24
|
||||
ListenPort = 51820
|
||||
PrivateKey = <server_private_key>
|
||||
|
||||
[Peer]
|
||||
PublicKey = <truenas_public_key>
|
||||
AllowedIPs = 10.100.0.2/32
|
||||
PersistentKeepalive = 25
|
||||
```
|
||||
|
||||
**On TrueNAS (via TrueNAS SCALE UI or shell):**
|
||||
- Apps → Network → WireGuard → Add Interface
|
||||
- Or via shell: same `wg genkey` + `/etc/wireguard/wg0.conf` approach
|
||||
```ini
|
||||
[Interface]
|
||||
Address = 10.100.0.2/24
|
||||
PrivateKey = <truenas_private_key>
|
||||
|
||||
[Peer]
|
||||
PublicKey = <vps_public_key>
|
||||
Endpoint = 85.214.154.199:51820
|
||||
AllowedIPs = 10.100.0.1/32
|
||||
PersistentKeepalive = 25
|
||||
```
|
||||
|
||||
Enable on both:
|
||||
```bash
|
||||
systemctl enable --now wg-quick@wg0
|
||||
```
|
||||
|
||||
Test:
|
||||
```bash
|
||||
# From VPS
|
||||
ping 10.100.0.2
|
||||
curl http://10.100.0.2:30008 # Should reach Gitea
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Firewall — Open WireGuard Port on VPS
|
||||
|
||||
```bash
|
||||
# On VPS
|
||||
ufw allow 51820/udp
|
||||
# Or via iptables if ufw not present
|
||||
iptables -A INPUT -p udp --dport 51820 -j ACCEPT
|
||||
```
|
||||
|
||||
Also ensure TrueNAS router/firewall does NOT need any port forwarding — TrueNAS initiates the tunnel outbound. The VPS listens; TrueNAS connects. No router config needed.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Plesk Apache — Add Subdomain Proxy Rules
|
||||
|
||||
**Add `git.plate.software` as a subdomain in Plesk:**
|
||||
1. Plesk → Domains → Add Subdomain → `git.plate.software`
|
||||
2. Apache & nginx Settings → Additional directives for HTTP:
|
||||
```apache
|
||||
<IfModule mod_proxy.c>
|
||||
ProxyPass /.well-known/acme-challenge/ !
|
||||
ProxyPass / http://10.100.0.2:30008/ retry=0
|
||||
ProxyPassReverse / http://10.100.0.2:30008/
|
||||
ProxyPreserveHost On
|
||||
</IfModule>
|
||||
```
|
||||
3. Issue Let's Encrypt cert for `git.plate.software`
|
||||
4. Configure HTTPS redirect and HTTPS proxy directives the same way
|
||||
|
||||
**Update `plate.software` HTTP directives:**
|
||||
Change the existing WildFly proxy target from `127.0.0.1:8080` to `10.100.0.2:8080` once WildFly is moved to TrueNAS:
|
||||
```apache
|
||||
ProxyPass / http://10.100.0.2:8080/ retry=0
|
||||
```
|
||||
(Keep this as `127.0.0.1:8080` while the Docker container still runs on the VPS)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Migrate WildFly to TrueNAS
|
||||
|
||||
The customer's Java EE app currently runs in Docker on the VPS. Migrate to TrueNAS:
|
||||
|
||||
1. Export/pull the WildFly Docker image
|
||||
2. Copy any persistent volumes/data
|
||||
3. Create `docker-compose.yml` on TrueNAS
|
||||
4. Start container on TrueNAS, verify on `10.100.0.2:8080`
|
||||
5. Update VPS Apache proxy target from `127.0.0.1:8080` → `10.100.0.2:8080`
|
||||
6. Remove the Docker container from VPS
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Gitea Public HTTPS
|
||||
|
||||
For Gitea to work properly behind a proxy, update its config to know its public URL:
|
||||
|
||||
Edit Gitea's `app.ini` (in the Gitea Docker volume on TrueNAS):
|
||||
```ini
|
||||
[server]
|
||||
DOMAIN = git.plate.software
|
||||
ROOT_URL = https://git.plate.software/
|
||||
HTTP_PORT = 30008
|
||||
```
|
||||
|
||||
Also in Plesk HTTPS directives for `git.plate.software`:
|
||||
```apache
|
||||
<IfModule mod_proxy.c>
|
||||
ProxyPass /.well-known/acme-challenge/ !
|
||||
ProxyPass / http://10.100.0.2:30008/ retry=0
|
||||
ProxyPassReverse / http://10.100.0.2:30008/
|
||||
ProxyPreserveHost On
|
||||
RequestHeader set X-Forwarded-Proto "https"
|
||||
RequestHeader set X-Forwarded-Port "443"
|
||||
</IfModule>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Network Topology (Final State)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Internet / DNS │
|
||||
│ *.plate.software → 85.214.154.199 │
|
||||
└──────────────┬──────────────────────┘
|
||||
│ HTTP/HTTPS
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ VPS: plate.software │
|
||||
│ 85.214.154.199 / Plesk / Apache │
|
||||
│ │
|
||||
│ plate.software → proxy:8080 │
|
||||
│ git.plate.software → proxy:30008 │
|
||||
│ app.plate.software → proxy:XXXX │
|
||||
└──────────────┬──────────────────────┘
|
||||
│ WireGuard 10.100.0.0/24
|
||||
│ UDP 51820 (encrypted)
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ TrueNAS.local │
|
||||
│ 192.168.188.119 / WG: 10.100.0.2 │
|
||||
│ │
|
||||
│ :30008 Gitea │
|
||||
│ :8080 WildFly (Java EE) │
|
||||
│ :XXXX Future services │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risks & Notes
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|-----------|
|
||||
| Home ISP outage takes down all services | Acceptable for homelab; add health check monitoring later |
|
||||
| ISP dynamic IP changes (if applicable) | WireGuard peer config uses VPS as endpoint (fixed IP) — TrueNAS initiates tunnel, so home IP change is transparent |
|
||||
| TrueNAS reboot drops tunnel | `systemctl enable wg-quick@wg0` ensures auto-start |
|
||||
| Gitea SSH cloning (port 22/2222) | Need separate SSH port forward or Gitea SSH over different port — HTTP clone still works via HTTPS proxy |
|
||||
| Customer data on VPS → TrueNAS migration | Do at off-peak time; test thoroughly before cutting DNS |
|
||||
|
||||
---
|
||||
|
||||
## Cost Model
|
||||
|
||||
- VPS (plate.software): Keep cheap (~3-5€/month) — CPU/RAM irrelevant, just proxy traffic
|
||||
- TrueNAS: All compute happens here — free (already owned hardware)
|
||||
- Cloudflare (optional): Free plan for DNS + DDoS protection on top of the VPS
|
||||
|
||||
---
|
||||
|
||||
## Alternative: Cloudflare Tunnel (Zero-Config Option)
|
||||
|
||||
If WireGuard setup is too complex, Cloudflare Tunnel (`cloudflared`) is a zero-config alternative:
|
||||
- Run `cloudflared` as a Docker container on TrueNAS
|
||||
- No VPS needed for tunneling — Cloudflare handles the public endpoint
|
||||
- Free for personal use
|
||||
- TrueNAS → Cloudflare edge → DNS → users
|
||||
|
||||
**Downside:** Traffic routes through Cloudflare (not self-hosted end-to-end). VPS still useful for non-Cloudflare domains and the existing customer project.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
1. ✅ Fix plate.software Let's Encrypt (done)
|
||||
2. 🔜 Set up WireGuard tunnel (VPS ↔ TrueNAS)
|
||||
3. 🔜 Add `git.plate.software` subdomain in Plesk + proxy to TrueNAS Gitea
|
||||
4. 🔜 Update Gitea `app.ini` with public URL
|
||||
5. 🔜 Issue Let's Encrypt for `git.plate.software`
|
||||
6. ⏳ Migrate WildFly customer project from VPS → TrueNAS
|
||||
7. ⏳ Decommission VPS Docker container (keep VPS as pure proxy)
|
||||
Reference in New Issue
Block a user