Expand deployment docs and streamline README links

Author: oegedijk

README.md

@@ -548,67 +548,19 @@ For platform-specific guides, see:
 and
 [Deploying to Hugging Face Spaces](https://explainerdashboard.readthedocs.io/en/latest/deployment.html#deploying-to-hugging-face-spaces).
 and
-[Deploying to Azure Web Apps](#deploying-to-azure-web-apps).
-
-### Deploying to Azure Web Apps
-
-If your app gets stuck on the dashboard `Loading...` screen on Azure, the most common
-issue is that the dashboard HTML is returned, but Dash endpoints such as
-`/_dash-layout`, `/_dash-dependencies`, or `/_dash-component-suites/*` are not mounted
-on the same Flask server and base path.
-
-Use a single WSGI app (`app = db.flask_server()`) and run it with `gunicorn`.
-Also avoid re-building the model/explainer inside a Flask request handler.
-
-**dashboard.py**:
-```python
-import os
-from explainerdashboard import ClassifierExplainer, ExplainerDashboard
-
-# Build/load these once at startup:
-# model = ...
-# X_test = ...
-# y_test = ...
-
-explainer = ClassifierExplainer(model, X_test, y_test)
-
-# If your app is mounted under a subpath, e.g. "/dashboard/",
-# set APP_BASE_PATH=/dashboard/ in Azure App Settings.
-base_path = os.getenv("APP_BASE_PATH", "/")
-if not base_path.startswith("/"):
-    base_path = "/" + base_path
-if not base_path.endswith("/"):
-    base_path = base_path + "/"
-
-db = ExplainerDashboard(
-    explainer,
-    url_base_pathname=base_path,
-    routes_pathname_prefix=base_path,
-    requests_pathname_prefix=base_path,
-    title="Model Explainer",
-)
-
-app = db.flask_server()
-```
-
-**requirements.txt** should include at least:
-```txt
-explainerdashboard
-gunicorn
-```
-
-Set your Azure Web App startup command to:
-
-```bash
-gunicorn --bind=0.0.0.0:${PORT:-8000} dashboard:app
-```
-
-Troubleshooting checklist:
+[Deploying to Azure Web Apps](https://explainerdashboard.readthedocs.io/en/latest/deployment.html#deploying-to-azure-web-apps),
+[Deploying behind reverse proxies and path prefixes](https://explainerdashboard.readthedocs.io/en/latest/deployment.html#deploying-behind-reverse-proxies-and-path-prefixes),
+[Deploying to Google Cloud Run](https://explainerdashboard.readthedocs.io/en/latest/deployment.html#deploying-to-google-cloud-run),
+[Deploying to Kubernetes (Ingress)](https://explainerdashboard.readthedocs.io/en/latest/deployment.html#deploying-to-kubernetes-ingress),
+[Deploying in Databricks notebooks](https://explainerdashboard.readthedocs.io/en/latest/deployment.html#deploying-in-databricks-notebooks),
+and
+[Deploying in Kaggle notebooks](https://explainerdashboard.readthedocs.io/en/latest/deployment.html#deploying-in-kaggle-notebooks).
 
-1. Open browser dev tools and check network requests to `/_dash-layout` and `/_dash-dependencies`.
-2. If those requests return `404`, fix your base path prefixes (or set `APP_BASE_PATH=/`).
-3. If initial page load is very slow, make sure model training and data loading are not done per request.
-4. Check App Service logs for worker timeouts and increase plan/resources if needed.
+For a concise production pattern, expose a single WSGI app and run with `gunicorn`:
+`app = db.flask_server()` and `gunicorn --bind=0.0.0.0:${PORT:-8000} dashboard:app`.
+If your deployment runs behind a proxy/path prefix and you see `Loading...`, check
+the deployment docs above and align `url_base_pathname`, `routes_pathname_prefix`,
+and `requests_pathname_prefix`.
 
 It can be helpful to store your `explainer` and dashboard layout to disk, and
 then reload, e.g.:

docs/source/deployment.rst

@@ -179,6 +179,133 @@ on ``ExplainerDashboard``.
 
 .. highlight:: python
 
+Deploying behind reverse proxies and path prefixes
+==================================================
+
+For any platform behind a reverse proxy or ingress (Azure, Kubernetes, AWS ALB, etc),
+the key requirement is that Dash base paths and proxy routing agree.
+
+Use a shared base path (for example ``/dashboard/``) for all three settings::
+
+    db = ExplainerDashboard(
+        explainer,
+        url_base_pathname="/dashboard/",
+        routes_pathname_prefix="/dashboard/",
+        requests_pathname_prefix="/dashboard/",
+    )
+    app = db.flask_server()
+
+Quick checks:
+
+1. The page is served from the same base path as Dash API calls.
+2. ``/_dash-layout`` and ``/_dash-dependencies`` return ``200`` (not ``404``).
+3. ``/_dash-component-suites/*`` assets are reachable.
+4. The app binds to ``0.0.0.0:$PORT`` in production.
+
+Deploying to Google Cloud Run
+=============================
+
+Cloud Run works well with ``gunicorn`` and a containerized app.
+
+**dashboard.py**::
+
+    from explainerdashboard import ExplainerDashboard
+
+    db = ExplainerDashboard.from_config("dashboard.yaml")
+    app = db.flask_server()
+
+**Dockerfile**::
+
+    FROM python:3.11-slim
+
+    WORKDIR /app
+    COPY requirements.txt .
+    RUN pip install --no-cache-dir -r requirements.txt
+    COPY . .
+
+    CMD ["sh", "-c", "gunicorn dashboard:app --bind 0.0.0.0:${PORT}"]
+
+Notes:
+
+1. Keep startup fast (load prebuilt explainer, do not retrain on request).
+2. If served under a path prefix, set the three Dash pathname prefixes as above.
+
+Deploying to Kubernetes (Ingress)
+=================================
+
+For Kubernetes with ingress path routing, avoid path rewrites unless your Dash prefixes
+match the rewritten path exactly.
+
+Example deployment env var:
+
+.. code-block:: yaml
+
+    env:
+      - name: APP_BASE_PATH
+        value: /dashboard/
+
+Example app setup:
+
+.. highlight:: python
+
+::
+
+    import os
+    from explainerdashboard import ExplainerDashboard
+
+    base_path = os.getenv("APP_BASE_PATH", "/")
+    db = ExplainerDashboard(
+        explainer,
+        url_base_pathname=base_path,
+        routes_pathname_prefix=base_path,
+        requests_pathname_prefix=base_path,
+    )
+    app = db.flask_server()
+
+If you see ``Loading...`` with ``404`` responses on ``/_dash-*``, fix ingress
+path rules and Dash prefixes first.
+
+.. highlight:: python
+
+Deploying in Databricks notebooks
+=================================
+
+For model exploration in Databricks, run the dashboard in notebook context and make
+sure all Dash pathname prefixes match the Databricks proxy path.
+
+Example::
+
+    from explainerdashboard import ExplainerDashboard
+
+    port = 8050
+    # Replace this with your workspace-specific Databricks proxy base path:
+    base_path = f"/driver-proxy/o/<org-id>/<cluster-id>/{port}/"
+
+    db = ExplainerDashboard(
+        explainer,
+        mode="external",
+        url_base_pathname=base_path,
+        routes_pathname_prefix=base_path,
+        requests_pathname_prefix=base_path,
+    )
+    db.run(port=port)
+
+If you get ``Loading...``, check network requests for ``/_dash-layout`` and
+``/_dash-dependencies``; ``404`` usually means proxy prefix mismatch.
+
+Deploying in Kaggle notebooks
+=============================
+
+Kaggle is best suited for interactive exploration in notebook sessions, not durable
+hosting of a long-running web app.
+
+Recommended pattern:
+
+1. Run in notebook mode (``mode="inline"`` or ``mode="external"``).
+2. Keep it lightweight for notebook resources (for example lower ``plot_sample``,
+   disable expensive tabs such as ``shap_interaction``).
+3. Share results with ``db.save_html("dashboard.html")`` when you need a portable artifact.
+
 Deploying to Hugging Face Spaces
 ================================