analysis on using subprocess instead of gunicorn and removing references to virtual path in env files

Author: FionaDmello

.env.example

@@ -36,16 +36,6 @@ NGINX_PORT=
 #   - acme-companion: Requests SSL certificate for this domain from Let's Encrypt
 HOST=
 
-# Path on the domain where the dashboard is accessible
-# If set, the dashboard will ONLY be accessible at this specific path
-# Examples:
-#   - VIRTUAL_PATH=/survey-dashboard → https://your-domain.com/survey-dashboard
-#   - VIRTUAL_PATH=/dashboard → https://your-domain.com/dashboard
-#   - Leave empty for root path → https://your-domain.com/
-# IMPORTANT: Must start with / (forward slash)
-# All other paths on this domain will return 404
-VIRTUAL_PATH=
-
 # ============================================================================
 # SSL/HTTPS Configuration (Let's Encrypt)
 # ============================================================================

.env.local.example

@@ -33,12 +33,6 @@ NGINX_PORT=80
 # You can only test HTTP locally
 HOST=localhost
 
-# Path on the domain where the dashboard is accessible
-# Test the same path you'll use in production
-# Example: VIRTUAL_PATH=/2021community
-# Leave empty to serve from root: http://localhost/
-VIRTUAL_PATH=/2021community
-
 # ============================================================================
 # SSL/HTTPS Configuration (Let's Encrypt)
 # ============================================================================

survey_dashboard/scripts.py

@@ -11,6 +11,44 @@
 ###############################################################################
 """
 Command line scripts for the survey dashboard.
+
+DEPLOYMENT ARCHITECTURE:
+========================
+This application uses Panel's built-in server (via `panel serve`) rather than
+traditional WSGI servers like Gunicorn. This is the CORRECT and RECOMMENDED
+approach for Panel applications.
+
+Why subprocess + `panel serve` instead of Gunicorn:
+----------------------------------------------------
+1. **WebSocket Support**: Panel apps require WebSocket connections for real-time
+   interactivity. Panel is built on Bokeh Server which uses Tornado's WebSocket
+   implementation. Standard WSGI servers like Gunicorn don't natively support
+   WebSockets in the same way.
+
+2. **State Management**: Panel/Bokeh Server manages application state and sessions
+   in a specific way that requires Tornado's event loop. Gunicorn's worker model
+   doesn't provide this.
+
+3. **Bokeh Protocol**: The Bokeh Server protocol handles bidirectional communication
+   between Python and JavaScript using a custom protocol over WebSockets. This is
+   deeply integrated with Tornado.
+
+4. **Official Recommendation**: The Panel documentation recommends using `panel serve`
+   for production deployments. See: https://panel.holoviz.org/how_to/deployment/
+
+5. **Built-in Production Features**: `panel serve` includes production-ready features:
+   - Multi-process scaling via --num-procs
+   - WebSocket origin validation via --allow-websocket-origin
+   - Static file serving
+   - Load balancing across worker processes
+
+Alternative Approaches (Not Recommended):
+-----------------------------------------
+- **Gunicorn + Flask wrapper**: Possible but adds unnecessary complexity and
+  requires careful configuration of worker types (gevent/eventlet)
+- **Embedding Panel in ASGI**: Possible with Daphne/Uvicorn but adds overhead
+
+For more details, see DEPLOYMENT.md in the project root.
 """
 
 import argparse
@@ -23,6 +61,17 @@ def run_app():
     """Run the survey dashboard application using Panel serve.
 
     Supports both development and production modes via command-line arguments.
+
+    Kubernetes Deployment Note:
+    ---------------------------
+    For Kubernetes deployments, each pod should run a single process (no --num-procs).
+    Kubernetes handles scaling via pod replicas and load balancing via Services.
+
+    Example production deployment:
+        survey-dashboard --production --host 0.0.0.0 --port 5006
+
+    Then scale in Kubernetes:
+        kubectl scale deployment survey-dashboard --replicas=3
     """
     # Parse command-line arguments
     parser = argparse.ArgumentParser(description="Run the HMC Survey Dashboard")