From cee36d7d31a07252d93993f95efb45e12c1107a0 Mon Sep 17 00:00:00 2001
From: agessaman <adam@gessaman.com>
Date: Sat, 27 Jun 2026 17:00:31 -0700
Subject: [PATCH] docs(web-viewer): add reverse proxy configuration with Nginx
 and basic auth

- Introduced a new section in the web viewer documentation detailing how to set up a reverse proxy using Nginx with basic authentication for enhanced security when exposing the web viewer outside the local network.
- Updated instructions for network access to recommend setting a password or using a reverse proxy for authentication.
- Included example Nginx server block configuration and necessary proxy parameters for proper functionality.
---
 docs/web-viewer.md | 60 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 2 deletions(-)

diff --git a/docs/web-viewer.md b/docs/web-viewer.md
index 0a61800..6917e4d 100644
--- a/docs/web-viewer.md
+++ b/docs/web-viewer.md
@@ -74,6 +74,62 @@ Once started, open your web browser and navigate to:
 - **Local access**: http://localhost:5005 (or your configured port)
 - **Network access**: http://YOUR_BOT_IP:5005 (if host is set to 0.0.0.0)
 
+## Reverse Proxy With Nginx Basic Auth
+
+If you expose the web viewer outside your local network, run it behind HTTPS and authentication. One option is to bind the viewer locally, then put Nginx in front with basic auth:
+
+```ini
+[Web_Viewer]
+enabled = true
+auto_start = true
+host = 127.0.0.1
+port = 8080
+```
+
+Example Nginx server block:
+
+```nginx
+server {
+  # [...]
+  auth_basic           "Login required";
+  auth_basic_user_file /etc/nginx/.meshcore-bot.htpasswd;
+
+  location / {
+    # Local web viewer instance
+    proxy_pass      http://127.0.0.1:8080;
+    proxy_buffering off;
+    include /etc/nginx/proxy_params;
+  }
+
+  # Socket.IO websocket path for live updates
+  location /socket.io/ {
+    if ($http_connection !~* "upgrade") {
+      return 403;
+    }
+    if ($http_upgrade !~* "websocket") {
+      return 403;
+    }
+
+    proxy_pass http://127.0.0.1:8080;
+    include /etc/nginx/proxy_params;
+
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_read_timeout 86400;
+  }
+}
+```
+
+With the config above, `/etc/nginx/proxy_params` should include the standard forwarded headers:
+
+```nginx
+proxy_set_header Host $http_host;
+proxy_set_header X-Real-IP $remote_addr;
+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+proxy_set_header X-Forwarded-Proto $scheme;
+```
+
 ## Pages Overview
 
 ### Dashboard
@@ -238,7 +294,7 @@ chmod +x restart_viewer.sh
 - The web viewer is designed for local network use
 - Set `host = 127.0.0.1` for localhost-only access
 - Set `host = 0.0.0.0` for network access (use with caution)
-- No authentication is implemented - consider firewall rules for production use
+- For network access, set `web_viewer_password` or use a reverse proxy with authentication and firewall rules
 
 ## Future Enhancements
 
@@ -246,5 +302,5 @@ chmod +x restart_viewer.sh
 - Real-time message monitoring
 - Interactive contact management
 - Export functionality
-- Authentication system
+- Additional authentication options
 - Mobile-responsive design improvements