fc603464ee
- Introduced `run_buddai.ps1` to automate the setup and launch of the BuddAI server. - Implemented checks for Docker and Ollama services, ensuring they are running before starting the server. - Added model verification and automatic pulling of required AI models. - Created a Python virtual environment and installed necessary dependencies. - Configured firewall rules for port 8000 and provided options for remote access via ngrok or Tailscale. - Enhanced user experience with informative messages and QR code generation for easy access to the server. - Included logic to determine the best public URL for the server based on available network configurations.
3.4 KiB
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:
- Integrated a QR Code Generator directly into the Python backend (
/api/utils/qrcode). - 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:
- Local Network (LAN): Auto-configured via Firewall rules.
- Private VPN (Tailscale): Auto-detected with priority handling.
- Public Tunnel (Ngrok): Optional fallback with secure/public modes.