Initial commit: cleaned project structure

- Consolidated documentation from Ralph Loop iterations - Archived 20+ outdated/superseded files to .archive/ - Kept essential docs: OIDC integration, mobile setup, quick start - Added operational scripts for health monitoring and backup - Research artifacts preserved in .tasks/artifacts/ Current state: - 3 VPS sites (fry, proton, photon) ONLINE in Pangolin - brn-home site pending for local services (Jellyfin, etc.) - Mobile access configuration pending Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-21 06:15:04 +00:00
commit b428721b07
17 changed files with 5749 additions and 0 deletions
--- a/MOBILE-CLIENT-SETUP.md
+++ b/MOBILE-CLIENT-SETUP.md
@@ -0,0 +1,393 @@
+# Pangolin Mobile Client Setup Guide
+
+**Date:** 2026-01-20 22:26:00+00:00
+**Device:** Android (pixel9pro, pixel6pro)
+**Current:** Connected to 10.50.0.0/24 via WLAN
+**Goal:** Access services via Pangolin tunnel when on WAN/mobile network
+
+---
+
+## Prerequisites
+
+**Before Setting Up Mobile:**
+- ✅ Pangolin control plane running (https://tunnel.obr.sh)
+- ✅ Authentik SSO configured with Pangolin
+- ⏸️ At least one site created in Pangolin (brn-home)
+- ⏸️ At least one resource configured (e.g., Jellyfin)
+
+**Without sites/resources, the tunnel works but has nothing to access.**
+
+---
+
+## Part 1: Install Pangolin Mobile App
+
+### Android (Google Play Store)
+
+**App Name:** Pangolin
+
+**Install:**
+1. Open Google Play Store on pixel9pro or pixel6pro
+2. Search for "Pangolin"
+3. Install the official Pangolin app (by fosrl)
+4. Open the app
+
+**Alternative:** F-Droid (if available)
+
+---
+
+## Part 2: Enroll Mobile Device
+
+### Option A: QR Code Enrollment (Easiest)
+
+**On Desktop (accessing Pangolin dashboard):**
+
+1. Login to Pangolin: https://tunnel.obr.sh
+   - Use your Pangolin admin account
+   - Or "Login with Authentik" if SSO configured
+
+2. Navigate to: **Clients** or **Devices** (left sidebar)
+
+3. Click: **Add Client** or **Enroll Device**
+
+4. Select: **Mobile Device**
+
+5. **QR Code appears** on screen
+
+**On Mobile (pixel9pro/pixel6pro):**
+
+1. Open Pangolin app
+2. Tap: **Scan QR Code** or **Add Server**
+3. Point camera at QR code on desktop
+4. **Automatic enrollment** - device connects
+5. App may prompt for permissions (VPN, notifications) - ALLOW these
+
+**Done!** Device enrolled and connected.
+
+---
+
+### Option B: Manual Enrollment
+
+**On Mobile App:**
+
+1. Open Pangolin app
+2. Tap: **Add Server** or **Manual Setup**
+
+3. Enter server details:
+   ```
+   Server URL: https://tunnel.obr.sh
+   ```
+
+4. Tap **Continue**
+
+5. **Login with Authentik** (if SSO configured):
+   - Browser opens to Authentik login
+   - Enter: akadmin / (password)
+   - Enter MFA code
+   - Approve access
+   - Returns to app
+
+6. **Device enrolled** and tunnel connected
+
+---
+
+## Part 3: Access Services Through Tunnel
+
+**Once connected, the Pangolin app creates a VPN tunnel.**
+
+### Accessing Jellyfin via Tunnel
+
+**On Mobile (when NOT on home WiFi):**
+
+1. **Ensure Pangolin tunnel is connected:**
+   - Open Pangolin app
+   - Should show "Connected" status
+   - May show data transfer stats
+
+2. **Open browser on mobile** (Chrome, Firefox, etc.)
+
+3. **Navigate to:** https://video.obnh.io
+
+4. **Jellyfin loads through the tunnel!**
+   - Traffic: Mobile → WAN → tunnel.obr.sh (brn) → WireGuard tunnel → jellyfin:8096
+   - Encrypted end-to-end
+   - No public exposure
+
+5. **Login to Jellyfin:**
+   - If SSO configured: Click "Login with Authentik"
+   - If not: Use Jellyfin credentials
+   - Or use Quick Connect (6-digit code from web)
+
+### Accessing Other Services
+
+**Through Pangolin tunnel, you can access:**
+
+**OpenWebUI:** https://ll.obr.sh
+**Transmission:** https://tor.obnh.network
+**Pi-hole Admin:** https://dns.obnh.io
+**Guacamole (RDP in browser!):** https://remote.obr.sh/guacamole/
+
+**All work the same way:**
+- Connect Pangolin VPN
+- Open mobile browser
+- Navigate to service URL
+- Authenticate (SSO or service-specific login)
+
+---
+
+## Part 4: Understanding Pangolin Tunnel Behavior
+
+### When on Home WiFi (10.50.0.0/24):
+
+**Pangolin tunnel OFF:**
+- Services accessible directly via LAN
+- Faster (no tunnel overhead)
+- More battery efficient
+
+**Pangolin tunnel ON (optional):**
+- Still works, routes through tunnel
+- No advantage when on home network
+- Can leave on for convenience
+
+### When on Mobile Network / External WiFi:
+
+**Pangolin tunnel REQUIRED:**
+- Services only accessible through tunnel
+- Encrypted WireGuard connection
+- Appears as if you're on home LAN to services
+
+**Without tunnel:**
+- Services unreachable (after Traefik restrictions applied)
+- Or requires public WAN exposure (less secure)
+
+---
+
+## Part 5: Pangolin App Features
+
+### Connection Management
+
+**Toggle Tunnel:**
+- Tap connection to enable/disable
+- Green = connected
+- Grey = disconnected
+
+**Auto-Connect:**
+- Settings → Auto-connect on mobile data
+- Automatically connects when off home WiFi
+
+**Kill Switch:**
+- Settings → Block internet when tunnel down
+- Prevents leaking traffic if tunnel fails
+
+### Resource Access
+
+**Pangolin can show available resources:**
+- List of services you can access
+- Quick links to open in browser
+- Connection status per service
+
+### VPN Configuration
+
+**Pangolin uses WireGuard under the hood:**
+- Android VPN permission required
+- Shows in notification area when connected
+- Can view connection stats (data transfer, latency)
+
+---
+
+## Part 6: Mobile App Troubleshooting
+
+### Cannot Enroll Device
+
+**Check:**
+- Pangolin dashboard accessible from mobile (https://tunnel.obr.sh)
+- Firewall allows UDP 51821 (already configured on brn)
+- Mobile has internet connectivity
+
+**Try:**
+- Use manual enrollment instead of QR
+- Check Pangolin dashboard logs for connection attempts
+
+### Tunnel Connects But Services Unreachable
+
+**Check:**
+- Sites created in Pangolin dashboard
+- Resources configured for services
+- Newt client running on brn (connects services to Pangolin)
+
+**Deploy Newt on brn:**
+```bash
+# Get command from Pangolin dashboard: Sites → brn-home → Connection
+# Will look like:
+docker run -d --name newt --cap-add NET_ADMIN \
+  -e SITE_TOKEN="<from_dashboard>" \
+  -e PANGOLIN_URL="https://tunnel.obr.sh" \
+  --network traefik \
+  fosrl/newt:latest
+```
+
+### Battery Drain
+
+**Pangolin tunnel uses some battery:**
+- Normal: 5-10% extra per day
+- High drain: Check for constant reconnections
+
+**Optimize:**
+- Disable tunnel when on home WiFi
+- Use WiFi calling if available
+- Enable battery optimization for Pangolin app (Android settings)
+
+---
+
+## Part 7: Security Considerations
+
+### When Using Mobile Tunnel
+
+**Encrypted:**
+- ✅ WireGuard encryption (end-to-end)
+- ✅ TLS for HTTPS services
+- ✅ Double encryption for services
+
+**Authentication:**
+- ✅ Authentik SSO if configured
+- ✅ Service-specific auth (Jellyfin, etc.)
+- ✅ MFA on Authentik login
+
+**Safe To Use On:**
+- Public WiFi (coffee shop, airport)
+- Hotel networks
+- Mobile data
+- Any untrusted network
+
+### What Gets Tunneled
+
+**Through Pangolin:**
+- Only traffic to configured Pangolin resources
+- Example: video.obnh.io, ll.obr.sh, etc.
+
+**NOT tunneled:**
+- General internet traffic (Google, YouTube, etc.)
+- Other apps on phone
+- System updates
+
+**This is NOT a full VPN - it's a tunneled reverse proxy for specific services.**
+
+---
+
+## Part 8: Multi-Device Support
+
+### Setting Up pixel6pro (Second Device)
+
+**Same process:**
+1. Install Pangolin app
+2. Scan QR code from dashboard (generates new enrollment)
+3. Or use manual enrollment
+4. Each device gets unique WireGuard keys
+5. Both can connect simultaneously
+
+**Device Management:**
+- View all devices in Pangolin dashboard (Clients section)
+- Revoke access per device if phone lost/stolen
+- See last connection time per device
+
+---
+
+## Part 9: Accessing Guacamole RDP on Mobile
+
+**This is REALLY cool:**
+
+**On Mobile (connected to Pangolin tunnel):**
+
+1. **Open browser:** Chrome or Firefox
+2. **Navigate to:** https://remote.obr.sh/guacamole/
+3. **Login** (guacadmin or Authentik SSO)
+4. **Click:** argon-rdp connection (after you create it)
+5. **Your Windows 11 desktop IN YOUR MOBILE BROWSER!**
+   - Full RDP session
+   - Touch controls translated to mouse/keyboard
+   - Can copy/paste between mobile and Windows
+   - Can transfer files (if configured)
+
+**Use Cases:**
+- Remote desktop from anywhere
+- Emergency Windows access
+- Run Windows-only apps from phone
+- Access files on Windows machine
+
+---
+
+## Part 10: Jellyfin Mobile App Through Tunnel
+
+**Jellyfin official app + Pangolin tunnel:**
+
+**Setup:**
+1. Install Jellyfin app (Google Play)
+2. Connect Pangolin tunnel first
+3. Open Jellyfin app
+4. Add server: https://video.obnh.io
+5. **Quick Connect:**
+   - App shows 6-digit code
+   - On desktop browser: Login to Jellyfin → Dashboard → Devices
+   - Enter the 6-digit code
+   - Device authorized
+6. Jellyfin app now connected through tunnel
+
+**Benefits:**
+- Better than browser (native video player)
+- Downloads for offline viewing
+- Better performance
+- Background audio playback
+
+---
+
+## Quick Reference Card
+
+**Pangolin Connection:**
+```
+Server: https://tunnel.obr.sh
+Login: Authentik SSO (akadmin)
+Protocol: WireGuard
+Port: 51821/UDP
+```
+
+**Services Through Tunnel:**
+```
+Jellyfin:     https://video.obnh.io
+OpenWebUI:    https://ll.obr.sh
+Transmission: https://tor.obnh.network
+Pi-hole:      https://dns.obnh.io
+Guacamole:    https://remote.obr.sh/guacamole/
+```
+
+**When to Connect:**
+- On mobile data: ✅ Connect
+- On public WiFi: ✅ Connect
+- On home WiFi (10.50.0.x): ⏸️ Optional (direct LAN access)
+
+---
+
+## Next Steps
+
+**1. Complete 2 WebUI steps** (see above - 5 minutes total)
+
+**2. Provide credentials to automation:**
+```bash
+cat /home/olaf/pangolin/oidc-pangolin.txt
+```
+
+**3. I will then:**
+- Create all other OIDC providers via Authentik API
+- Configure all services programmatically
+- Create Pangolin sites and resources
+- Provide final mobile enrollment QR code
+
+**4. Install Pangolin app and enroll** (2 minutes)
+
+**5. Test accessing Jellyfin from mobile data** (1 minute)
+
+**Total setup time:** ~15 minutes start to finish
+
+---
+
+**File:** `/home/olaf/pangolin/MOBILE-CLIENT-SETUP.md`
+
+**Start with:** Complete Step 1 in `/home/olaf/pangolin/WEBUI-ONLY-STEPS.md`