release: v6.17.0 — HA mode preview (Redis rate limiter + cluster abstraction)

Opt-in HA via DD_MODE=ha. Closes BACKLOG F30 partially. Standalone
users: zero impact (ioredis is optionalDependencies, cluster.js
lazy-evaluates to no-ops, no env var changes).

New:
  - src/services/cluster.js — HA abstraction. Standalone mode
    every method is a cheap no-op; HA mode lazy-connects to
    Redis (REDIS_URL default redis://redis:6379).
  - src/services/rate-limiter-memory.js — extracted sliding-window
    limiter from middleware. Clean delegation contract.
  - src/middleware/rateLimit.js — rewritten to delegate via
    cluster.rateLimitTick. Fail-open on Redis errors (warn log).
    Adds X-RateLimit-Remaining response header.
  - docker-compose --profile ha with redis:7-alpine (128MB cap,
    LRU, snapshot persistence, no exposed ports).
  - docs/features/ha-mode.md — operator reference including
    "when NOT to use HA mode".

Tests: 843/55 → 866/57 (+23). 9 memory-limiter tests, 14 cluster
tests via ioredis-mock (no real Redis needed).

Deps:
  - ioredis ^5.10.1 → optionalDependencies
  - ioredis-mock ^8.13.1 → devDependencies
  npm audit clean.

v6.17.0 preview limitations (loudly documented):
  - Don't run multi-replica in HA mode yet — every replica runs
    every cron job, duplicate backups + concurrent VACUUM risk.
  - WS broadcasts still per-replica.
  Fixed in v7.0.0: alpha.1 = WS pub/sub, rc.1 = leader election.

Single-replica HA today is useful for operational drill (sticky-LB
config, Prometheus scrape of Redis) before v7.0 rolls out multi-replica.

Lint 0/0. Rollback = single-commit revert.

Author: bogdanpricop

BACKLOG.md

@@ -25,19 +25,24 @@ This is the single source of truth for deferred work. Each item lists WHY it's d
 
 **Enterprise LDAP users:** test on staging before updating production. Confidence is medium (code correct per docs, but unverified against a live server).
 
-### F30 — Distributed rate limiter (Redis-backed)
+### F30 — Distributed rate limiter (Redis-backed) — opt-in HA mode
 
-**Why deferred:** Current rate limiter is in-memory per-process. Works perfectly for single-instance deploys (the default). Horizontal-scale (multi-pod) breaks: each pod has its own counter, so a `10 req/min` limit becomes `10 × N pods` effectively.
+**Status (updated 2026-04-22):** 🟡 Partial — foundation shipped in v6.17.0 (preview).
 
-**Why not fix now:** Docker Dash's product positioning is single-instance deploy. Horizontal scale requires:
-- Redis container in compose
-- Shared session store (currently SQLite-backed sessions, same issue)
-- Sticky routing OR full session-sharing via Redis
+**v6.17.0 (shipped):**
+- `src/services/cluster.js` — HA abstraction with `DD_MODE=ha` opt-in. Zero overhead for standalone users.
+- Redis-backed rate limiter via `INCR + PEXPIRE` fixed-window (2× looser than standalone sliding-window at bucket boundaries — documented trade-off).
+- `docker-compose --profile ha` with `redis:7-alpine` service (optional, off by default).
+- `ioredis` as `optionalDependencies` (not `dependencies`). Standalone installs don't pull it.
+- 23 new tests via `ioredis-mock` (no real Redis needed to run the suite).
+- `docs/features/ha-mode.md` — operator-facing reference.
 
-All of the above = 3-5 days of infra work. Out of scope for a single-box product.
+**Still deferred for v7.0.0 (per [`plans/deep-spec-ha-mode.md`](plans/deep-spec-ha-mode.md)):**
+- v7.0.0-alpha.1 — WebSocket pub/sub via Redis (fix "user on replica A misses events from replica B")
+- v7.0.0-rc.1 — Leader election via `SET NX PX` for the 13 cron jobs, Docker event stream, SSH tunnels, git polling
+- v7.0.0 stable — failover runbook, sticky-session LB docs, staging soak
 
-**Estimated effort:** 4-5 days.
-**Proposed approach:** release as v7.0 "HA mode" with opt-in `DD_MODE=ha` env var; default stays single-instance.
+**Known v6.17.0 limitations (loudly documented):** **don't run multi-replica in HA mode yet.** Every replica runs every cron job → duplicate backups, concurrent `VACUUM` risk. Single-replica HA mode is only useful for operational drill (Prometheus scrape, LB config) before v7.0 rolls out true multi-replica.
 
 ---
 

CHANGELOG.md

@@ -2,6 +2,102 @@
 
 All notable changes to Docker Dash are documented here.
 
+## [6.17.0] - 2026-04-22 — "HA mode preview — Redis-backed rate limiter + cluster foundation"
+
+**Opt-in HA** — closes BACKLOG F30 partially. `DD_MODE=ha` + Redis unlocks cross-replica rate limiting; the rest of the HA story (WS pub/sub, cron leader election) lands in v7.0.0. Standalone users: **zero impact** — default unchanged, `ioredis` is in `optionalDependencies` (not `dependencies`), no new env vars required.
+
+Full background and architecture: [`plans/research-ha-mode-optional.md`](plans/research-ha-mode-optional.md) + [`plans/deep-spec-ha-mode.md`](plans/deep-spec-ha-mode.md) (local/gitignored).
+
+### Added — `src/services/cluster.js` HA abstraction
+
+New service module ([`src/services/cluster.js`](src/services/cluster.js)) that every HA-eligible subsystem imports. Standalone mode: every method is a cheap no-op or falls through to in-process state (zero runtime overhead). HA mode: lazy-connects to Redis via `REDIS_URL`.
+
+Public API:
+- `cluster.isHa()` / `cluster.nodeId()` — mode introspection
+- `cluster.redis()` — ioredis client in HA, null in standalone
+- `cluster.rateLimitTick(key, maxReqs, windowMs)` — returns `{ allowed, remaining, retryAfterSec }`
+- `cluster.publish(ch, payload)` / `cluster.subscribe(ch, handler)` — stubbed in v6.17.0, wired in v7.0.0-alpha.1
+- `cluster.isLeader()` — returns `true` in v6.17.0 (stub), real election in v7.0.0-rc.1
+
+### Added — Redis-backed rate limiter
+
+Extracted the existing in-memory `Map`-based limiter into `src/services/rate-limiter-memory.js` (sliding window, same semantics as before). New HA path in `cluster.rateLimitTick` uses Redis `INCR` + `PEXPIRE` (fixed window — 2× looser at bucket boundaries, documented trade-off in `docs/features/ha-mode.md` §"Rate-limiter semantics").
+
+`src/middleware/rateLimit.js` rewritten to delegate. **Fail-open on Redis errors** — a mid-request Redis outage lets the request through with a `warn` log, prioritizing availability over strict quota.
+
+### Added — `docker-compose --profile ha` + `redis:7-alpine` service
+
+Opt-in HA profile in [`docker-compose.yml`](docker-compose.yml):
+```bash
+docker compose --profile ha up -d
+# Then .env: DD_MODE=ha, REDIS_URL=redis://redis:6379
+```
+
+Redis configured with:
+- `--save 60 1000` — snapshot persistence on ≥1000 writes / 60s
+- `--maxmemory 128mb --maxmemory-policy allkeys-lru` — hard cap
+- `no-new-privileges:true` — matches the rest of the compose security posture
+- No exposed ports — only reachable via the Docker network
+
+### Added — Tests (23 new, all pass via `ioredis-mock` — no real Redis needed)
+
+- [`src/__tests__/rate-limiter-memory.test.js`](src/__tests__/rate-limiter-memory.test.js) — 9 tests covering sliding-window semantics, key isolation, expiration, cleanup
+- [`src/__tests__/cluster.test.js`](src/__tests__/cluster.test.js) — 14 tests: 8 standalone (all methods no-op correctly) + 6 HA (Redis path via `jest.doMock('ioredis')` → `ioredis-mock`)
+
+**Test suite: 843/55 → 866/57.**
+
+### Added — `docs/features/ha-mode.md`
+
+Operator reference. Covers: what HA changes, enabling, architecture, Redis keys, rate-limiter semantics, failure modes, monitoring, when NOT to use HA mode, rollback procedure.
+
+### Changed — Dependencies
+
+- `ioredis ^5.10.1` added as **`optionalDependencies`** (not `dependencies`). Standalone installs don't pull it.
+- `ioredis-mock ^8.13.1` added as `devDependencies` for unit tests.
+- `npm audit` clean (0 vulnerabilities).
+
+### ⚠️ v6.17.0 Preview Limitations (loudly documented)
+
+**Don't run multi-replica in HA mode yet.** Every replica runs every cron job → duplicate daily backups, concurrent `VACUUM` (DB corruption risk), N× certificate scans, N× secret rotation checks. This is fixed in v7.0.0-rc.1 via leader election.
+
+**WS broadcasts still per-replica.** User connected to replica A misses events emitted by replica B. Fixed in v7.0.0-alpha.1 via Redis pub/sub.
+
+Single-replica HA mode today is only useful for operational drill — wiring sticky-session load balancers, Prometheus scrape of Redis, Grafana dashboards — before rolling out true multi-replica in v7.0.
+
+### BACKLOG F30 — partial close
+
+Shipped: cluster abstraction + Redis rate limiter + `--profile ha` + docs.
+Remaining for v7.0: WS pub/sub (v7.0.0-alpha.1), cron leader election (v7.0.0-rc.1), failover runbook (v7.0.0 stable).
+
+### Rollback
+
+Single-commit revert. `ioredis` becomes an unused `optionalDependencies` entry (harmless). `--profile ha` becomes a no-op profile.
+
+### Production readiness
+
+Unchanged at 9.7/10 this release. v6.17.0 is about enabling a new deployment mode for enterprise users, not about closing residual standalone gaps. Scorecard moves only when v7.0 stable lands with real multi-replica support + failover tests.
+
+### Files touched
+
+- `src/services/cluster.js` (new, ~110 LOC)
+- `src/services/rate-limiter-memory.js` (new, ~50 LOC — extracted from middleware)
+- `src/middleware/rateLimit.js` — rewritten to delegate via cluster (~45 LOC, was ~55)
+- `src/__tests__/cluster.test.js` (new, 14 tests)
+- `src/__tests__/rate-limiter-memory.test.js` (new, 9 tests)
+- `docker-compose.yml` — `redis:7-alpine` service behind `--profile ha`
+- `docs/features/ha-mode.md` (new)
+- `package.json` — `ioredis` → `optionalDependencies`, `ioredis-mock` → `devDependencies`
+- `BACKLOG.md` — F30 updated with partial-close status
+- `README.md` / `SECURITY.md` / `CONTRIBUTING.md` — test counts + new Feature Reference link
+
+### Tests
+
+- **866 passing + 4 skipped / 57 suites**
+- Lint: 0 warnings / 0 errors
+- `npm audit`: 0 vulnerabilities
+
+---
+
 ## [6.16.1] - 2026-04-22 — "Testing 8.5 → 9.5, Documentation 9 → 9.5 (production readiness 9.5 → 9.7)"
 
 Pure test + docs release. No runtime code changes. Closes two of the three remaining gaps to 10/10 production readiness.

CONTRIBUTING.md

@@ -11,15 +11,15 @@ Looking for where to start? These are great first contributions:
 - **Add a language translation** — copy `public/js/i18n/TEMPLATE.js`, translate values, add one `<script>` tag. Currently: 11 languages (EN, RO, DE, IT, FR, ES, PT, ZH, JA, KO, Klingon).
 - **Add an app template** — add an entry to `src/routes/templates.js` (JSON object with compose YAML). Currently: 33 templates.
 - **Improve i18n coverage** — some pages still have hardcoded English strings (grep for strings not using `i18n.t()`)
-- **Add tests** — 843 tests across 55 suites; more coverage is always welcome, especially integration tests
+- **Add tests** — 866 tests across 57 suites; more coverage is always welcome, especially integration tests
 - **Documentation** — improve README, add examples, write tutorials
 - **Accessibility** — add ARIA attributes, improve screen reader support, test keyboard navigation
 
 ### Project Stats (v5.3.0)
 
 - **24 pages** in the frontend SPA (incl. Swarm, Compare with 8 tools)
 - **230+ API endpoints** (see `/api/docs` for full list)
-- **843 tests** (55 test suites, 100% passing)
+- **866 tests** (57 test suites, 100% passing)
 - **33 app templates** (+ custom user templates)
 - **37 database migrations** (001-037)
 - **11 languages** (EN, RO, DE, IT, FR, ES, PT, ZH, JA, KO, Klingon)

README.md

@@ -8,8 +8,8 @@
     <a href="https://github.com/bogdanpricop/docker-dash/actions/workflows/ci.yml"><img src="https://github.com/bogdanpricop/docker-dash/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
     <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-843%20passing%20(100%25)-brightgreen" alt="Tests"></a>
-    <img src="https://img.shields.io/badge/version-6.16.1-blue" alt="Version">
+    <a href="https://github.com/bogdanpricop/docker-dash/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-866%20passing%20(100%25)-brightgreen" alt="Tests"></a>
+    <img src="https://img.shields.io/badge/version-6.17.0-blue" alt="Version">
     <a href="SECURITY.md#security-audit-history"><img src="https://img.shields.io/badge/production%20readiness-9.7%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">
@@ -26,7 +26,9 @@
   </p>
 </p>
 
-**Zero dependencies to deploy** — just Docker. No external database, no Redis, no build step. Current version: **v6.16.1**
+**Zero dependencies to deploy** — just Docker. No external database, no Redis, no build step. Current version: **v6.17.0**
+
+**New in v6.17.0:** Optional HA mode via `DD_MODE=ha` + Redis. Preview only — Redis-backed rate limiter + cluster abstraction shipped; WS pub/sub + cron leader election land in v7.0. See [docs/features/ha-mode.md](docs/features/ha-mode.md).
 
 ## Screenshots
 
@@ -212,7 +214,7 @@
 - **Self-Reporting Footprint** — Docker Dash memory, uptime, DB size at `/api/footprint`
 - **Let's Encrypt Wizard** — 3-step UI for issuing certs via DNS-01 (Cloudflare, Route53, DigitalOcean, Hetzner, Linode) or HTTP-01. Encrypted credential vault, auto-renewal via Caddy, hash-chained audit trail. Open source — no other Docker UI ships this
 - **Container Remediation Wizard** — 3-step UI that turns Secrets Audit + CIS Benchmark findings into actionable fixes. 20-entry catalog, 4 live-updatable (zero downtime), 16 with compose-recreate + auto-rollback. Git-PR mode for git-backed stacks. No other OSS Docker UI ships this
-- **843 Tests** — 55 test suites covering auth, RBAC, security, CRUD, services, ACME + remediation orchestrators, platform detection, DMI cloud detection, translations, Prometheus metrics, permissions RBAC, settings CRUD, security alert rule evaluation, event notifier dispatch (100% passing)
+- **866 Tests** — 57 test suites covering auth, RBAC, security, CRUD, services, ACME + remediation orchestrators, platform detection, DMI cloud detection, translations, Prometheus metrics, permissions RBAC, settings CRUD, security alert rule evaluation, event notifier dispatch, cluster abstraction (HA mode), rate-limiter memory + Redis paths (100% passing)
 
 ### Feature Reference
 
@@ -221,6 +223,7 @@ Dedicated reference docs for the deeper features, in [docs/features/](docs/featu
 - **[Prometheus Metrics](docs/features/prometheus-metrics.md)** — `/api/metrics` endpoint reference, metric names + types + labels, sample Grafana queries, cardinality notes
 - **[Platform Detection](docs/features/platform-detection.md)** — NAS + cloud + hypervisor detection logic; complete signature list; how to extend
 - **[Translations Tooling](docs/features/translations-tooling.md)** — Google Translate + DeepL integration, quota tracking, review workflow, runtime DB overrides
+- **[HA Mode](docs/features/ha-mode.md)** — optional Redis-backed redundancy (v6.17.0 preview, full in v7.0); architecture, trade-offs, when NOT to use it
 
 ## Where to start
 

SECURITY.md

@@ -88,7 +88,7 @@ If you discover a security vulnerability in Docker Dash, please report it respon
 
 ## Testing
 
-- **843 tests** across 55 test suites (100% passing; 4 skipped are live-Cloudflare integration tests gated on a CI secret)
+- **866 tests** across 57 test suites (100% passing; 4 skipped are live-Cloudflare integration tests gated on a CI secret)
 - Unit tests: crypto round-trip, input validation, shell sanitization, git patterns
 - Integration tests: auth flow (login, session, logout, SSO), API endpoints (supertest), RBAC, security alerts
 - **CI pipeline** — GitHub Actions runs tests + syntax check + npm audit on every push

docker-compose.yml

@@ -4,8 +4,8 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        APP_VERSION: "${APP_VERSION:-6.16.1}"
-    image: docker-dash:${APP_VERSION:-6.16.1}
+        APP_VERSION: "${APP_VERSION:-6.17.0}"
+    image: docker-dash:${APP_VERSION:-6.17.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:-6.16.1}
+    image: docker-dash-egress-filter:${APP_VERSION:-6.17.0}
     container_name: dd-egress-filter
     restart: unless-stopped
     # Uses the default bridge so target containers on the default bridge can
@@ -78,6 +78,36 @@ services:
     profiles:
       - egress
 
+  # Optional Redis for HA mode — enable with: docker compose --profile ha up -d
+  # Then on the `app` service (via .env):
+  #   DD_MODE=ha
+  #   REDIS_URL=redis://redis:6379
+  #
+  # v6.17.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 v6.17.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.
+  redis:
+    image: redis:7-alpine
+    container_name: docker-dash-redis
+    restart: unless-stopped
+    command: redis-server --save 60 1000 --maxmemory 128mb --maxmemory-policy allkeys-lru
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 3
+    security_opt:
+      - no-new-privileges:true
+    profiles:
+      - ha
+
   # Optional HTTPS reverse proxy — enable with: docker compose --profile tls up -d
   # Configure via Docker Dash UI: System → SSL/TLS → Enable HTTPS
   caddy:
@@ -111,3 +141,5 @@ volumes:
     name: docker-dash-egress-policy
   egress-logs:
     name: docker-dash-egress-logs
+  redis-data:
+    name: docker-dash-redis-data