Make the Grafana metrics link runtime configurable

.gitignore

@@ -1,5 +1,6 @@
 # Ignore environment files
 .env
+infra/compose/prometheus/openrag_token
 
 # generated files and folders
 .files/

docs/assets/env_example.env

@@ -105,8 +105,14 @@ CHAINLIT_AUTH_SECRET=openrag-dev-secret
 # API/auth, so it is the OIDC front door. Zero-config otherwise (same-origin, no
 # CORS); VITE_* build-time options are documented in the env vars reference.
 # ADMIN_UI_PORT=8081
-
-
+# GRAFANA_ADMIN_USER=admin
+# GRAFANA_ADMIN_PASSWORD=replace-with-a-strong-password
+# Direct Grafana access:
+# GRAFANA_URL=http://localhost:3000/d/openrag-http/openrag-http-metrics
+# Or through the Admin UI proxy:
+# GRAFANA_URL=http://localhost:8081/grafana/d/openrag-http/openrag-http-metrics
+# GF_SERVER_ROOT_URL=http://localhost:8081/grafana/
+# GF_SERVER_SERVE_FROM_SUB_PATH=true
 
 # ── Ray (kept as-is by the compose stack; see the docs for what each does) ───
 RAY_DEDUP_LOGS=0
@@ -117,4 +123,4 @@ RAY_ENABLE_UV_RUN_RUNTIME_ENV=0
 # RAY_memory_monitor_refresh_ms=0
 
 # ── Logging (DEBUG on dev, INFO on prod) ──
-LOG_LEVEL=DEBUG
+LOG_LEVEL=DEBUG

docs/assets/env_linux_gpu.env

@@ -52,7 +52,16 @@ RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 # critical with the newest version of UV
 ## replace X.X.X.X with localhost (local) or your server IP, and APP_PORT with your FastAPI port
 
 # ADMIN_UI_PORT=8081                            # Host port for the admin UI (nginx). Default is 8081.
+# GRAFANA_ADMIN_USER=admin                      # Grafana login used on first startup.
+# GRAFANA_ADMIN_PASSWORD=replace-with-a-strong-password
+# Direct Grafana access:
+# GRAFANA_URL=http://localhost:3000/d/openrag-http/openrag-http-metrics
+#                                               # Runtime dashboard link. Restart the API after changing it.
+# Or through the Admin UI proxy:
+# GRAFANA_URL=http://localhost:8081/grafana/d/openrag-http/openrag-http-metrics
+# GF_SERVER_ROOT_URL=http://localhost:8081/grafana/
+# GF_SERVER_SERVE_FROM_SUB_PATH=true             # Serve Grafana through the admin UI's /grafana/ path.
 # VITE_API_BASE_URL=                            # API base baked into the SPA. EMPTY (default) = same-origin via
 #                                               # nginx (no CORS). Only set for a browser-direct build.
-# VITE_GRAFANA_URL=                             # Optional Grafana dashboard link on the admin "System" page.
-# VITE_APP_NAME=OpenRAG                         # App display name used in the UI branding.
+# VITE_GRAFANA_URL=                             # Optional build-time fallback for older API deployments.
+# VITE_APP_NAME=OpenRAG                         # App display name used in the UI branding.

docs/content/docs/documentation/env_vars.md

@@ -641,9 +641,10 @@ flowchart TD
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
 | `ADMIN_UI_PORT` | `number` | `8081` | Host port the admin UI (nginx) is published on. Serves `/app/` and reverse-proxies `/auth`, `/v1`, `/chainlit`, … to the backend, so it is the OIDC front door (`OIDC_REDIRECT_URI` targets this port). Deploy-time (not a `VITE_*` build arg). |
+| `GRAFANA_URL` | `string` | `""` | Runtime, browser-reachable URL for the Grafana dashboard opened from **System → Metrics**. Restart the API after changing it. When this is empty or invalid, the action explains how to configure the dashboard instead of opening it. |
 | `VITE_API_BASE_URL` | `string` | `""` (same-origin) | API base baked into the SPA. **Empty (default) = same-origin**: nginx reverse-proxies the API over the Docker network, so the UI works on any host/IP with no CORS. Set to an absolute URL only for a browser-direct build — then list the UI's origin in `CORS_EXTRA_ORIGINS`. |
 | `VITE_BASE_PATH` | `string` | `/app/` | Sub-path the SPA is served under; must match the nginx `location`. |
-| `VITE_GRAFANA_URL` | `string` | `""` | Optional Grafana dashboard link shown on the admin **System** page. |
+| `VITE_GRAFANA_URL` | `string` | `""` | Build-time fallback for deployments whose API does not expose `GRAFANA_URL`. New deployments should use the runtime setting instead. |
 | `VITE_APP_NAME` | `string` | `OpenRAG` | Application display name used in the UI branding. |
 | `VITE_MOCK_API` | `boolean` | `false` | Development only — serves in-browser MSW API mocks when `true`. Ignored in production builds. |
 
@@ -712,3 +713,5 @@ Read only by the opt-in monitoring compose file (`infra/compose/monitoring.docke
 |----------|------|---------|-------------|
 | `GRAFANA_ADMIN_USER` | `str` | `admin` | Grafana admin username. |
 | `GRAFANA_ADMIN_PASSWORD` | `str` | _(required)_ | Grafana admin password — compose refuses to start the monitoring profile if unset. |
+| `GF_SERVER_ROOT_URL` | `str` | `http://localhost:3000` | Browser-facing Grafana root URL. Set this to the admin UI's `/grafana/` URL when using its proxy. |
+| `GF_SERVER_SERVE_FROM_SUB_PATH` | `bool` | `false` | Set to `true` when `GF_SERVER_ROOT_URL` includes the `/grafana/` subpath. |

docs/content/docs/installation/docker.mdx

@@ -13,3 +13,61 @@ The OpenRAG docker image is available on [DockerHub](https://hub.docker.com/r/rc
 
 OpenRAG requires several services to run, which can be orchestrated using Docker Compose.
 
+## Grafana monitoring
+
+The optional monitoring stack provides ready-to-use dashboards for OpenRAG HTTP
+traffic, host resources, and NVIDIA GPUs. It is separate from the default stack
+so deployments that do not need monitoring keep the same footprint.
+
+Before starting it, set a strong `GRAFANA_ADMIN_PASSWORD` in `.env`. The
+`GRAFANA_ADMIN_USER` defaults to `admin`. Create the Prometheus token file from
+the same `AUTH_TOKEN` used by OpenRAG:
+
+```bash
+cd infra/compose
+compose_environment="$(docker compose --env-file .env config --environment)"
+AUTH_TOKEN="$(printf '%s\n' "$compose_environment" | sed -n 's/^AUTH_TOKEN=//p')"
+allow_no_auth="$(
+  printf '%s\n' "$compose_environment" |
+    sed -n 's/^ALLOW_NO_AUTH=//p' |
+    tr '[:upper:]' '[:lower:]' |
+    sed 's/^[[:space:]]*//;s/[[:space:]]*$//'
+)"
+if [ -z "$AUTH_TOKEN" ] && [ "$allow_no_auth" != "true" ]; then
+  echo "AUTH_TOKEN must be set unless ALLOW_NO_AUTH=true." >&2
+  exit 1
+fi
+printf '%s' "$AUTH_TOKEN" | sudo tee prometheus/openrag_token >/dev/null
+sudo chown 65534:65534 prometheus/openrag_token
+sudo chmod 0400 prometheus/openrag_token
+```
+
+Start OpenRAG with the monitoring overlay:
+
+```bash
+export SHARED_ENV="$PWD/.env"
+docker compose --env-file .env \
+  -f docker-compose.yaml \
+  -f monitoring.docker-compose.yaml \
+  up -d
+```
+
+`GRAFANA_URL` controls where **System > Metrics** opens. It must be reachable
+from the user's browser. For direct local access, use:
+
+```dotenv
+GRAFANA_URL=http://localhost:3000/d/openrag-http/openrag-http-metrics
+```
+
+For remote deployments, expose Grafana through the Admin UI proxy and configure
+its subpath:
+
+```dotenv
+GRAFANA_URL=https://openrag.example.com/grafana/d/openrag-http/openrag-http-metrics
+GF_SERVER_ROOT_URL=https://openrag.example.com/grafana/
+GF_SERVER_SERVE_FROM_SUB_PATH=true
+```
+
+Grafana has its own login. Its admin password is initialized when the persistent
+Grafana volume is created; changing the environment variable later does not
+reset an existing password.

infra/charts/openrag-stack/values.yaml

@@ -334,6 +334,7 @@ env:
     ENABLE_RAY_SERVE: "true"
     RAY_SERVE_NUM_REPLICAS: "4"
     RAY_SERVE_PORT: "80"
+    GRAFANA_URL: ""
 
     WITH_CHAINLIT_UI: "false"
     SAVE_UPLOADED_FILES: "false"

infra/compose/.env.example

@@ -105,8 +105,14 @@ CHAINLIT_AUTH_SECRET=openrag-dev-secret
 # API/auth, so it is the OIDC front door. Zero-config otherwise (same-origin, no
 # CORS); VITE_* build-time options are documented in the env vars reference.
 # ADMIN_UI_PORT=8081
-
-
+# GRAFANA_ADMIN_USER=admin
+# GRAFANA_ADMIN_PASSWORD=replace-with-a-strong-password
+# Direct Grafana access:
+# GRAFANA_URL=http://localhost:3000/d/openrag-http/openrag-http-metrics
+# Or through the Admin UI proxy:
+# GRAFANA_URL=http://localhost:8081/grafana/d/openrag-http/openrag-http-metrics
+# GF_SERVER_ROOT_URL=http://localhost:8081/grafana/
+# GF_SERVER_SERVE_FROM_SUB_PATH=true
 
 # ── Ray (kept as-is by the compose stack; see the docs for what each does) ───
 RAY_DEDUP_LOGS=0
@@ -117,4 +123,4 @@ RAY_ENABLE_UV_RUN_RUNTIME_ENV=0
 # RAY_memory_monitor_refresh_ms=0
 
 # ── Logging (DEBUG on dev, INFO on prod) ──
-LOG_LEVEL=DEBUG
+LOG_LEVEL=DEBUG

infra/compose/docker-compose.yaml

@@ -125,7 +125,7 @@ services:
         # to CORS_EXTRA_ORIGINS on the API.
         VITE_API_BASE_URL: ${VITE_API_BASE_URL:-}
         VITE_BASE_PATH: "/app/"
-        # Optional Grafana dashboard link on the admin "System" page; branding name.
+        # Build-time Grafana fallback; prefer runtime GRAFANA_URL in .env.
         VITE_GRAFANA_URL: ${VITE_GRAFANA_URL:-}
         VITE_APP_NAME: ${VITE_APP_NAME:-OpenRAG}
     restart: unless-stopped