mirror of
https://github.com/JamesTheGiblet/BuddAI.git
synced 2026-01-08 21:58:40 +00:00
69 lines
3.4 KiB
Markdown
69 lines
3.4 KiB
Markdown
# Remote Access Implementation Log
|
|
|
|
This document records the troubleshooting steps, failures, and solutions implemented to enable remote access (Ngrok & Tailscale) for the BuddAI system.
|
|
|
|
## 1. Ngrok Execution Failures
|
|
|
|
### Fail: "The term '.\ngrok' is not recognized"
|
|
|
|
**Cause:** The script assumed `ngrok.exe` was in the current folder, but it wasn't, or it wasn't in the system PATH.
|
|
**Fix:** Updated `run_buddai.ps1` to check both the global PATH (`ngrok`) and the local folder (`.\ngrok.exe`).
|
|
|
|
### Fail: "Start-Process : The system cannot find the file specified"
|
|
|
|
**Cause:** PowerShell's `Start-Process` command failed when using a relative path like `.\ngrok.exe`.
|
|
**Fix:** Implemented `Resolve-Path` to convert the relative path to an absolute path before execution.
|
|
|
|
## 2. Tunnel Timing Issues
|
|
|
|
### Fail: Empty URL returned
|
|
|
|
**Cause:** The script attempted to fetch the public URL from the Ngrok API immediately after starting the process. The tunnel takes a few seconds to establish.
|
|
**Fix:** Added a **retry loop** in PowerShell that polls `http://localhost:4040/api/tunnels` every second for up to 15 seconds.
|
|
|
|
## 3. Dependency Issues
|
|
|
|
### Fail: "ModuleNotFoundError: No module named 'PIL'"
|
|
|
|
**Cause:** The `qrcode` library was added to generate QR codes, but it relies on `pillow` (PIL) for image generation, which was missing.
|
|
**Fix:** Added `pillow` to `requirements.txt` and wrapped the import in `main.py` with a `try/except` block to prevent server crashes.
|
|
|
|
### Fail: PowerShell Parsing Errors
|
|
|
|
**Cause:** Complex one-liner Python commands inside PowerShell strings caused syntax errors (specifically with parentheses and quoting).
|
|
**Fix:** Refactored the Python QR code generation call to be cleaner and safer within the script.
|
|
|
|
## 4. Network & Firewall
|
|
|
|
### Fail: "Run as Administrator to enable LAN/VPN access"
|
|
|
|
**Cause:** Windows Firewall blocks incoming connections to port 8000 by default, preventing LAN and Tailscale access.
|
|
**Fix:** Added automatic detection of the missing firewall rule. The script now prompts the user to press 'A' to restart as Administrator and applies the rule automatically using `New-NetFirewallRule`.
|
|
|
|
### Fail: Tailscale IP Not Detected
|
|
|
|
**Cause:** The script looked specifically for a network interface named "Tailscale", but on some systems, the adapter name differs.
|
|
**Fix:** Added a fallback detection method that scans for any active IPv4 address in the `100.x.x.x` range (Carrier Grade NAT), which Tailscale uses.
|
|
|
|
## 5. User Experience (UX) Friction
|
|
|
|
### Fail: Annoying Ngrok Prompt
|
|
|
|
**Cause:** Users with Tailscale (which is always on) were forced to wait 3 seconds or press a key to skip the Ngrok prompt every time.
|
|
**Fix:** Added logic to **auto-detect Tailscale**. If a Tailscale IP is found, the script now automatically skips the Ngrok prompt and defaults to the private VPN URL.
|
|
|
|
### Fail: "How do I view this on mobile?"
|
|
|
|
**Cause:** Users had to manually type long IP addresses or URLs into their phone.
|
|
**Fix:**
|
|
|
|
1. Integrated a **QR Code Generator** directly into the Python backend (`/api/utils/qrcode`).
|
|
2. Updated the root dashboard (`/`) to dynamically display the active IP (LAN, Tailscale, or Ngrok) and a scannable QR code.
|
|
|
|
## Final Status
|
|
|
|
The system now supports three robust access methods:
|
|
|
|
1. **Local Network (LAN):** Auto-configured via Firewall rules.
|
|
2. **Private VPN (Tailscale):** Auto-detected with priority handling.
|
|
3. **Public Tunnel (Ngrok):** Optional fallback with secure/public modes.
|