release: v7.1.0 — observability stack (Prometheus + Grafana opt-in profile)

Opt-in. `docker compose --profile observability up -d` deploys
Prometheus (scrape /api/metrics every 15s, 7-day retention) +
Grafana 11.3 (pre-provisioned datasource + 8-panel dashboard).

Standalone users: zero impact. Default `docker compose up -d`
remains unchanged.

What ships:

  docker/observability/
    ├── prometheus.yml                              — scrape config
    └── grafana/
        ├── provisioning/
        │   ├── datasources/prometheus.yml          — auto-wired DS
        │   └── dashboards/docker-dash.yml          — provider config
        └── dashboards/
            └── docker-dash-overview.json           — 8-panel dashboard

  docker-compose.yml
    prometheus (v3.0.1) + grafana (11.3.0) services behind
    observability profile. no-new-privileges, named volumes,
    Prometheus not exposed to host by default.

  docs/features/observability.md (~3,200 words)
    Panel reference, 6 recommended PromQL alerts, integration with
    existing Prometheus/Grafana, security hardening (7 items),
    deployment recommendations (resource limits, retention, HA
    scrape via static targets or Docker SD).

Dashboard works in both modes. HA-specific panels (cluster role,
Redis connected) show meaningful values in HA, "down / N/A" in
standalone. All 8 panel types: stat with value mapping, timeseries
line, timeseries bars, timeseries stacked.

Staging soak:
  - prometheus UP scraping app:8101/api/metrics
  - Grafana 11.3.0 health ok
  - Datasource auto-registered: Prometheus uid=docker-dash-prom
  - Dashboard auto-imported: "Docker Dash — Overview" in
    Docker Dash folder, 8 panels present
  - Live query verified: cluster_role=0 (standalone),
    HTTP rate 0.025 req/s GET/2xx

v7.2.0 roadmap: in-app wizard to detect existing Prometheus/Grafana
and offer 3 paths (integrate existing / deploy ours / point to
external). Compose profile + dashboard JSON become wizard primitives.

No app code changes. No dependencies added. npm audit unchanged.
Tests 879/4/57 (unchanged).

Author: bogdanpricop

CHANGELOG.md

@@ -2,6 +2,115 @@
 
 All notable changes to Docker Dash are documented here.
 
+## [7.1.0] - 2026-04-22 — "Observability stack — Prometheus + Grafana opt-in profile"
+
+Opt-in observability: `docker compose --profile observability up -d` adds Prometheus (scraping `/api/metrics` every 15s) + Grafana (pre-provisioned data source + 8-panel overview dashboard) alongside the app. Zero UI config — the dashboard populates within 30s of first scrape.
+
+**Standalone users: zero impact.** Default `docker compose up -d` is unchanged; the observability stack only comes up when explicitly requested via `--profile observability`.
+
+### Added — `docker/observability/` directory
+
+Four files that drive the entire stack:
+
+- **[`docker/observability/prometheus.yml`](docker/observability/prometheus.yml)** — scrape config: `app:8101/api/metrics` every 15s, 10s timeout. Includes Prometheus self-scrape.
+- **[`docker/observability/grafana/provisioning/datasources/prometheus.yml`](docker/observability/grafana/provisioning/datasources/prometheus.yml)** — auto-registers Prometheus at `http://prometheus:9090` with UID `docker-dash-prom`, proxy access, 15s time interval, POST method (handles long queries).
+- **[`docker/observability/grafana/provisioning/dashboards/docker-dash.yml`](docker/observability/grafana/provisioning/dashboards/docker-dash.yml)** — dashboard provider: watches `/etc/grafana/dashboards/` and auto-imports `.json` files every 30s. Puts them in a "Docker Dash" folder.
+- **[`docker/observability/grafana/dashboards/docker-dash-overview.json`](docker/observability/grafana/dashboards/docker-dash-overview.json)** — the overview dashboard (below).
+
+### Added — Overview dashboard (8 panels)
+
+Works in both standalone and HA mode. HA-specific panels show "down / N/A" in standalone (intentional — mode is detectable from the cluster role panel).
+
+| # | Panel | Type | Query |
+|:-:|-------|------|-------|
+| 1 | Cluster role | Stat (value mapping) | `docker_dash_cluster_role` — maps 0/1/2/-1 → standalone/leader/reader/unknown |
+| 2 | Redis (HA only) | Stat (value mapping) | `docker_dash_cluster_redis_connected` — red/green |
+| 3 | Active WS connections | Stat (area sparkline) | `sum(docker_dash_ws_connections_active)` |
+| 4 | Containers managed | Stat (area) | `docker_dash_containers_total` |
+| 5 | HTTP request rate | Timeseries (line, legend table) | `sum by(method,status) (rate(docker_dash_http_requests_total[5m]))` |
+| 6 | Avg HTTP latency | Timeseries (thresholded 500/2000ms) | `sum(rate(...duration_ms)) / sum(rate(...requests_total))` per method × status class |
+| 7 | Background job runs | Timeseries (bars) | `sum by(job) (rate(docker_dash_background_job_runs_total[15m]))` |
+| 8 | HTTP errors by status | Timeseries (stacked area) | `sum by(status) (rate(docker_dash_http_errors_total[5m]))` — shows 429/5xx spikes |
+
+Default refresh 30s, time range `now-1h`. Grafana version target: 11.x (schema 39).
+
+### Added — `docker-compose.yml` `--profile observability`
+
+Two new services behind the `observability` profile:
+
+```yaml
+prometheus:
+  image: prom/prometheus:v3.0.1
+  command: --storage.tsdb.retention.time=7d  # ...
+  # Not exposed to host by default — Grafana reaches it internally.
+
+grafana:
+  image: grafana/grafana:11.3.0
+  ports: ["${GRAFANA_PORT:-3001}:3000"]
+  environment:
+    GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:-admin}   # override for automation
+    GF_AUTH_ANONYMOUS_ENABLED: false
+    GF_USERS_ALLOW_SIGN_UP: false
+```
+
+Both with `no-new-privileges:true`, named volumes for data persistence (`docker-dash-prometheus-data`, `docker-dash-grafana-data`). Prometheus **not exposed to host** by default — defense in depth; operators who need external scrape can uncomment the `ports:` block.
+
+### Added — [`docs/features/observability.md`](docs/features/observability.md) (3,200 words)
+
+Operator reference covering:
+
+1. What's in the stack (service table, resource expectations)
+2. Enabling (quick + with custom credentials + with custom port)
+3. Dashboard panels reference (what each shows, why it matters)
+4. Recommended alerts (6 PromQL-ready alert expressions)
+5. **Integrating with existing Prometheus/Grafana** (two paths: scrape config append + dashboard JSON import via UI or API)
+6. Security hardening checklist (7 items — change default password, don't expose Prometheus, HTTPS, disable anonymous access, SSO integration, data-source proxy mode)
+7. **Common-sense deployment recommendations** — persistent storage, resource limits, retention vs disk trade-off, scaling considerations (single-instance Prometheus caveat, HA replica scrape via static targets OR Docker SD)
+8. Teardown (keep vs drop data volumes)
+9. Known limitations (no histograms — counters + gauges only; no per-container rollup; per-replica scrape cardinality bound)
+10. See also (source files + related docs)
+
+### Staging soak
+
+Deployed on staging, verified end-to-end:
+
+1. ✓ `docker compose --profile observability up -d` starts both services cleanly
+2. ✓ Prometheus scrapes `app:8101/api/metrics` with `up=1`
+3. ✓ Grafana health check returns `{"database":"ok","version":"11.3.0"}`
+4. ✓ Data source auto-registered: `Prometheus (prometheus) url=http://prometheus:9090 uid=docker-dash-prom`
+5. ✓ Dashboard auto-imported: `Docker Dash — Overview uid=docker-dash-overview folder=Docker Dash`
+6. ✓ All 8 panels present by title and type
+7. ✓ Live queries return real data: `docker_dash_cluster_role = 0` (standalone), HTTP rate ~0.025 req/s GET/2xx with GET/3xx + GET/4xx active
+
+### Changed — README
+
+- Feature Reference section adds "Observability Stack" link
+- Version badge 7.0.0 → 7.1.0
+
+### No dependency changes
+
+Prometheus + Grafana are Docker images pulled by the compose profile. `package.json` unchanged. `npm audit` remains clean.
+
+### Tests
+
+- **879 passing + 4 skipped / 57 suites** (unchanged — observability is Docker-side, no JS code added to the main app)
+- Lint: 0 warnings / 0 errors
+
+### Files touched
+
+- `docker/observability/` — 4 files (new)
+- `docker/observability/grafana/dashboards/docker-dash-overview.json` — 8-panel dashboard JSON
+- `docker-compose.yml` — `prometheus` + `grafana` services behind `observability` profile, 2 new named volumes
+- `docs/features/observability.md` — 3,200-word operator guide (new)
+- `README.md` — feature reference + version
+- `package.json`, `src/version.js` — 7.1.0
+
+### v7.2.0 roadmap (next)
+
+In-app wizard: detect existing Prometheus / Grafana in the Docker environment → offer three paths (integrate existing · deploy ours · point to external). The compose profile + dashboard JSON shipped here become the primitives the wizard executes. See `plans/deep-spec-observability-wizard.md` (to be written when scoped).
+
+---
+
 ## [7.0.0] - 2026-04-22 — "HA mode production-ready — observability + runbook + LB configs"
 
 **Major release.** HA mode (shipped incrementally across v6.17.0 → v6.17.2) is now **production-ready**. v7.0.0 adds the operational layer: cluster introspection endpoints, Prometheus metrics, a detailed failover runbook, and copy-paste LB configs for the 4 most common load balancers.

README.md

@@ -10,7 +10,7 @@
     <a href="https://github.com/bogdanpricop/docker-dash/releases/latest"><img src="https://img.shields.io/github/v/release/bogdanpricop/docker-dash?color=blue" alt="Release"></a>
     <a href="LICENSE"><img src="https://img.shields.io/github/license/bogdanpricop/docker-dash" alt="License"></a>
     <a href="https://github.com/bogdanpricop/docker-dash/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-879%20passing%20(100%25)-brightgreen" alt="Tests"></a>
-    <img src="https://img.shields.io/badge/version-7.0.0-blue" alt="Version">
+    <img src="https://img.shields.io/badge/version-7.1.0-blue" alt="Version">
     <a href="SECURITY.md#security-audit-history"><img src="https://img.shields.io/badge/production%20readiness-9.8%2F10-brightgreen" alt="Production Readiness"></a>
     <a href="SECURITY.md"><img src="https://img.shields.io/badge/security-audited-brightgreen" alt="Security Audited"></a>
     <img src="https://img.shields.io/badge/Docker-~80MB-blue" alt="Image Size">
@@ -269,6 +269,7 @@ Dedicated reference docs for the deeper features, in [docs/features/](docs/featu
 - **[HA Mode](docs/features/ha-mode.md)** — optional Redis-backed redundancy (production-ready in v7.0.0); architecture, trade-offs, when NOT to use it
 - **[HA Failover Runbook](docs/features/ha-failover-runbook.md)** — operator procedures: leader death, rolling restart, Redis failure, split-brain detection, recovery checklist
 - **[HA Load Balancer Configs](docs/features/ha-lb-configs.md)** — copy-paste examples for Caddy + Traefik + HAProxy + nginx with sticky-session + WS upgrade + health checks
+- **[Observability Stack (v7.1.0)](docs/features/observability.md)** — opt-in Prometheus + Grafana via `docker compose --profile observability up -d`, 8-panel dashboard auto-provisioned, recommended alerts, integration with existing Prometheus/Grafana
 
 ## Where to start
 

docker-compose.yml

@@ -4,8 +4,8 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        APP_VERSION: "${APP_VERSION:-7.0.0}"
-    image: docker-dash:${APP_VERSION:-7.0.0}
+        APP_VERSION: "${APP_VERSION:-7.1.0}"
+    image: docker-dash:${APP_VERSION:-7.1.0}
     container_name: docker-dash
     restart: unless-stopped
     env_file:
@@ -54,7 +54,7 @@ services:
   dd-egress-filter:
     build:
       context: ./docker/egress-filter
-    image: docker-dash-egress-filter:${APP_VERSION:-7.0.0}
+    image: docker-dash-egress-filter:${APP_VERSION:-7.1.0}
     container_name: dd-egress-filter
     restart: unless-stopped
     # Uses the default bridge so target containers on the default bridge can
@@ -83,14 +83,14 @@ services:
   #   DD_MODE=ha
   #   REDIS_URL=redis://redis:6379
   #
-  # v7.0.0 ships the foundation (Redis-backed rate limiter + cluster abstraction).
+  # v7.1.0 ships the foundation (Redis-backed rate limiter + cluster abstraction).
   # DO NOT run multi-replica in HA mode yet — WS pub/sub + cron leader election
-  # land in v7.0.0-alpha.1 / v7.0.0-rc.1. Running v7.0.0 HA with 2+ replicas
+  # land in v7.1.0-alpha.1 / v7.1.0-rc.1. Running v7.1.0 HA with 2+ replicas
   # causes duplicate cron execution (duplicate backups, concurrent VACUUM).
   #
   # Single-instance HA (1 replica + Redis) is useful for warming up operational
   # tooling (Prometheus scrape of Redis, sticky-session LB config drill, etc.)
-  # before rolling out true multi-replica in v7.0.0.
+  # before rolling out true multi-replica in v7.1.0.
   redis:
     image: redis:7-alpine
     container_name: docker-dash-redis
@@ -108,6 +108,68 @@ services:
     profiles:
       - ha
 
+  # Optional observability stack (v7.1.0) — enable with:
+  #   docker compose --profile observability up -d
+  #
+  # Ships Prometheus (scrape /api/metrics every 15s) + Grafana (auto-provisioned
+  # datasource + "Docker Dash — Overview" dashboard). Works in BOTH standalone
+  # and HA mode — the dashboard panels gate HA-only metrics (cluster role,
+  # Redis connected) via value mappings.
+  #
+  # Grafana default: admin / admin (forced change on first login).
+  # Grafana exposed on :${GRAFANA_PORT:-3001}; Prometheus NOT exposed externally.
+  # See docs/features/observability.md for hardening + integration with
+  # existing Prometheus / Grafana installs.
+  prometheus:
+    image: prom/prometheus:v3.0.1
+    container_name: docker-dash-prometheus
+    restart: unless-stopped
+    command:
+      - --config.file=/etc/prometheus/prometheus.yml
+      - --storage.tsdb.path=/prometheus
+      - --storage.tsdb.retention.time=7d
+      - --web.enable-lifecycle
+    volumes:
+      - ./docker/observability/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus-data:/prometheus
+    # Not exposed to host by default — Grafana reaches it on the internal
+    # network. Uncomment to expose for external scraping.
+    # ports:
+    #   - "${PROMETHEUS_PORT:-9091}:9090"
+    security_opt:
+      - no-new-privileges:true
+    profiles:
+      - observability
+
+  grafana:
+    image: grafana/grafana:11.3.0
+    container_name: docker-dash-grafana
+    restart: unless-stopped
+    ports:
+      - "${GRAFANA_PORT:-3001}:3000"
+    volumes:
+      - ./docker/observability/grafana/provisioning:/etc/grafana/provisioning:ro
+      - ./docker/observability/grafana/dashboards:/etc/grafana/dashboards:ro
+      - grafana-data:/var/lib/grafana
+    environment:
+      # Default admin / admin — Grafana FORCES change on first login.
+      # For automated provisioning, set GF_SECURITY_ADMIN_PASSWORD in .env
+      # so the first-login password change is pre-applied.
+      - GF_SECURITY_ADMIN_USER=${GRAFANA_ADMIN_USER:-admin}
+      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:-admin}
+      # Disable anonymous access — operators must log in. Flip to true +
+      # set Viewer role if you want the dashboard publicly visible.
+      - GF_AUTH_ANONYMOUS_ENABLED=false
+      # Disable user sign-up / email invites on this self-hosted install.
+      - GF_USERS_ALLOW_SIGN_UP=false
+      - GF_USERS_ALLOW_ORG_CREATE=false
+    depends_on:
+      - prometheus
+    security_opt:
+      - no-new-privileges:true
+    profiles:
+      - observability
+
   # Optional HTTPS reverse proxy — enable with: docker compose --profile tls up -d
   # Configure via Docker Dash UI: System → SSL/TLS → Enable HTTPS
   caddy:
@@ -143,3 +205,7 @@ volumes:
     name: docker-dash-egress-logs
   redis-data:
     name: docker-dash-redis-data
+  prometheus-data:
+    name: docker-dash-prometheus-data
+  grafana-data:
+    name: docker-dash-grafana-data