From de6580c231cd2a56ac2be680ca4f809f492f0f14 Mon Sep 17 00:00:00 2001
From: agessaman <adam@gessaman.com>
Date: Wed, 18 Feb 2026 15:36:09 -0800
Subject: [PATCH] Enhance web viewer troubleshooting documentation

- Added a comprehensive troubleshooting section for accessing the web viewer on devices like Orange Pi and SBCs, detailing configuration checks, process verification, log inspection, firewall settings, and standalone run instructions.
- Updated installation commands to include necessary dependencies for Flask and flask-socketio, improving clarity on setup requirements.
- Revised port conflict resolution steps to include updated commands for checking active ports.
---
 docs/web-viewer.md | 68 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 66 insertions(+), 2 deletions(-)

diff --git a/docs/web-viewer.md b/docs/web-viewer.md
index 04996d5..7eb7ce8 100644
--- a/docs/web-viewer.md
+++ b/docs/web-viewer.md
@@ -147,9 +147,73 @@ You can keep or remove the old `bot_data.db` file after verifying the viewer wor
 
 ## Troubleshooting
 
+### Web viewer not accessible (e.g. Orange Pi / SBC)
+
+If the viewer does not load from another device (e.g. from your phone or PC while the bot runs on an Orange Pi), work through these steps on the Pi.
+
+1. **Confirm config**
+   - In `config.ini` under `[Web_Viewer]`:
+     - `enabled = true`
+     - `auto_start = true` (if you want it to start with the bot)
+     - `host = 0.0.0.0` (required for access from other devices; `127.0.0.1` is localhost only)
+     - `port = 8080` (or another port 1024–65535)
+   - Restart the bot after changing config.
+
+2. **Check that the viewer process is running**
+   ```bash
+   # From project root on the Pi
+   ss -tlnp | grep 8080
+   # or
+   netstat -tlnp | grep 8080
+   ```
+   If nothing listens on your port, the viewer did not start or has exited.
+
+3. **Inspect viewer logs**
+   - When run by the bot, the viewer writes to:
+     - `logs/web_viewer_stdout.log`
+     - `logs/web_viewer_stderr.log`
+   - Look for Python tracebacks, "Address already in use", or missing dependencies (e.g. Flask, flask-socketio).
+   - Optional: run the viewer manually to see errors in the terminal:
+     ```bash
+     cd /path/to/meshcore-bot
+     python3 modules/web_viewer/app.py --config config.ini --host 0.0.0.0 --port 8080
+     ```
+
+4. **Check integration startup**
+   - Bot logs may show: `Web viewer integration failed: ...` or `Web viewer integration initialized`.
+   - If integration failed, the viewer subprocess is never started; fix the error shown (e.g. invalid `host` or `port` in config).
+
+5. **Firewall**
+   - Many SBC images (e.g. Orange Pi, Armbian minimal) do **not** ship with a firewall; if `curl` to localhost works and `host = 0.0.0.0`, the blocker may be network (Wi‑Fi client isolation, different subnet, or router). Check from a device on the same LAN using `http://<PI_IP>:8080`.
+   - If your system uses **ufw**:
+     ```bash
+     sudo ufw status
+     sudo ufw allow 8080/tcp
+     sudo ufw reload
+     ```
+   - If `ufw` is not installed (e.g. `sudo: ufw: command not found`), you may have no host firewall—that’s common on embedded images. To allow the port with **iptables** (often available when ufw is not):
+     ```bash
+     sudo iptables -I INPUT -p tcp --dport 8080 -j ACCEPT
+     ```
+     (Rules may not persist across reboots unless you use a persistence method for your distro.)
+   - If you prefer ufw, install it (e.g. `sudo apt install ufw`) and use the ufw commands above.
+
+6. **Test from the Pi first**
+   ```bash
+   curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8080/
+   ```
+   If this returns `200`, the viewer is running and the issue is binding or firewall. If you use `host = 0.0.0.0`, then try from another device: `http://<PI_IP>:8080`.
+
+7. **Standalone run (no bot)**
+   - To rule out bot integration issues, start the viewer by itself (same config path so it finds the DB):
+     ```bash
+     python3 modules/web_viewer/app.py --config config.ini --host 0.0.0.0 --port 8080
+     ```
+   - If `restart_viewer.sh` is used, note it binds to `127.0.0.1` by default; for network access run the command above with `--host 0.0.0.0` or edit the script.
+
 ### Flask Not Found
 ```bash
-pip3 install flask
+pip3 install flask flask-socketio
 ```
 
 ### Database Not Found
@@ -158,7 +222,7 @@ pip3 install flask
 
 ### Port Already in Use
 - Change the port in `config.ini` or stop the conflicting service
-- Use `lsof -i :5000` to find what's using the port
+- Use `ss -tlnp | grep 8080` or `lsof -i :8080` (if available) to find what's using the port
 
 ### Permission Denied
 ```bash