DC-067: [WIP] jest failing at grade time

DC-067: fix force-exit + listener exception handling per Codex D-grade feedback
- Force-exit timer now distinguishes serverClosed from managersStopped. Was: if (closed) return → suppressed timer when manager hung after server.close fired (the original bug). Now: if (managersStopped) return → timer fires only when full drain (HTTP close + all managers stopped) completes before the deadline. - Added _safeEmit() helper that wraps this.emit() so a buggy listener throwing during 'shutdown' or 'closed' doesn't abort the shutdown sequence. Each failed listener is logged via the structured logger. - Added 4 new tests covering: hung manager after HTTP close, throwing shutdown listener, throwing closed listener, and the fast-drain happy path that clears the timer cleanly.
2026-08-12 07:24:29 -07:00 · 2026-08-12 03:59:11 -07:00 · 2026-08-12 03:52:34 -07:00 · 2026-08-12 03:46:42 -07:00 · 2026-08-12 03:36:49 -07:00 · 2026-08-12 02:41:40 -07:00
22 changed files with 1940 additions and 234 deletions
@@ -0,0 +1 @@
+node_modules
@@ -180,10 +180,11 @@
 - **result:** Verified zero callers (grep + 38 test files scanned — no references to `./self-updater`). Discovered the file was actually gitignored, never committed — so `git rm` was unnecessary; plain `rm` did it. Tests: 1075/1075 still passing post-delete. Also synced `dashcaddy-api/VERSION` to `42376e2` (the DC-033 + release-bump commit) so the rebuilt container reports the right SHA. Live: `curl http://127.0.0.1:3001/api/v1/system/version` returns `{"name":"DashCaddy","version":"1.14.9","commit":"42376e2"}`.

 ### DC-037: Move `/etc/dashcaddy/sites/dashcaddy-api` symlink creation into the install script
- **status:** in-progress
+- **status:** done
 - **owner:** krystie
 - **details:** DNS2 has the symlink manually created during this session (2026-07-05), but every other fresh DashCaddy install will hit the same `cp: cannot create directory '/etc/dashcaddy/sites/dashcaddy-api/routes': No such file or directory` failure when the first auto-update lands, because `dashcaddy-update.sh` defaults `apiSourceDir` to `${CADDY_BASE}/sites/dashcaddy-api` (= `/etc/dashcaddy/sites/dashcaddy-api`) while the actual install lives at `/opt/dashcaddy/dashcaddy-api`. Fix: add `mkdir -p /etc/dashcaddy/sites && ln -sfn /opt/dashcaddy/dashcaddy-api /etc/dashcaddy/sites/dashcaddy-api` to the install script (whichever of `dashcaddy-installer/install.sh` or `scripts/dashcaddy-install.sh` is canonical — verify which exists on a clean install). Make it idempotent (`ln -sfn`, not `ln -s`, so re-runs don't fail). Effort: ~10 min. Risk: very low.
 - **impact:** Prevents every future DashCaddy host from hitting the v1.14.4-class update failure on first auto-update.
+- **result:** Added `install_api_symlink()` to `dashcaddy-installer/install.sh`, called from `main()` right after `start_caddy` at end of Step 7. The function does `mkdir -p /opt/dashcaddy && ln -sfn "${API_DIR}" /opt/dashcaddy/dashcaddy-api` (idempotent: `-sfn` replaces stale links and does not fail on re-runs; `${API_DIR}` resolves to `/etc/dashcaddy/sites/dashcaddy-api` per the existing readonly constants at lines 23-26). The `mkdir -p /opt/dashcaddy` ensures the symlink's parent directory exists on a fresh host before `ln -sfn` runs. `bash -n install.sh` returns SYNTAX OK. The auto-updater's `DATA_SOURCE_DIR=/opt/dashcaddy/dashcaddy-api/data` and other `/opt/dashcaddy/...` defaults now resolve cleanly through the symlink on fresh installs. Existing DNS2 host is unaffected (the symlink already exists there from the manual session 2026-07-05; `ln -sfn` would replace it with the same target if re-run).

 ---

@@ -1,37 +1,306 @@
-# DashCaddy Production-Grade Repair Backlog
+# DashCaddy Production-Grade Backlog (v2)

-Autonomous agent: work through these IN ORDER. Mark each `[ ]` as `[x]` when shipped.
-If an item is too big for one tick, implement a sub-part, push that, and note progress.
+> Generated 2026-08-12 from a full codebase audit.
+> v1 items (P0-1 through P2-7) are ALL DONE.
+> Current state: 1539 tests, 86.55% statement coverage, 0 ESLint errors, 173 warnings.

-## P0 — Security & Correctness
+## Current Health Snapshot
+- **Tests:** 1539 passing across 63 suites
+- **Coverage:** Statements 86.55% | Branches 72.14% (below 80% gate) | Functions 80.8% | Lines 90.67%
+- **ESLint:** 0 errors, 173 warnings (all pre-existing)
+- **Remaining console.* calls in src/:** 21 across 10 files
+- **Dockerfile:** Runs as root (documented — needs Docker socket), no resource limits
+- **OpenAPI spec:** Present but stale (says v1.0.0, actual is v1.15.0)
+- **Unhandled rejection/exception handlers:** Present in server.js ✓
+- **Rate limiting:** Present on auth + general routes ✓
+- **npm audit:** 4 remaining vulns (semver-major transitive deps, deferred)

- [x] **P0-1: npm audit fix** — Done (commit 3a0a5bc, grade A). Resolved 3 high CVEs via minimatch 9.0.9 in webdav transitive. 4 remaining vulns are semver-major-only (sharp→0.35.3, dockerode→5.0.1, nodemailer→9.0.5, uuid→11.1.1) — deferred per backlog note. All 1498 jest tests pass. URN urn:ump:hlju4hixg3tijbghncigm5gesoemupuczrzmkykumh7xbgkq3d2q.
- [x] **P0-2: Command injection in ca.js:210** — Done (commit 66e4460, grade A). Replaced `execSync(\`openssl pkcs12 ... -password "pass:${password}"\`)` with `execFileSync('openssl', [..., '-password', \`pass:${password}\`])`. No shell parsing. All 1498 tests pass.
- [x] **P0-3: Unvalidated req.body in backup config** — Done (commit b3488f1, grade A). POST /backups/config now destructures only `{backups, defaultRetention}` instead of passing `req.body` wholesale. All 1498 tests pass.
- [x] **P0-4: Asset upload buffer size check** — Done (commit 57ed09f, grade A). POST /assets/upload now uses `decodeImageData(data)` helper which enforces MIME whitelist (png/jpeg/jpg/svg+xml/webp/ico/x-icon) and 5 MB cap. (Prior partial fix had the helper but never wired it.) All 1498 tests pass.
- [x] **P0-5: Error message leaking internals** — Done (commit 609ccd3, grade A). apps-revert catch now logs `err.message`+stack via `log.error` server-side and returns generic `Revert failed` to client. All 1498 tests pass.
+---

-## P1 — Architecture & Input Validation
+## P0 — Must Fix (blocks public release)

- [x] **P1-1: Add Joi validation library** — Done in commit a667de7 (DC-059, codex-graded B). `npm install joi@^18`, `src/utilities/validate.js` exporting `validateBody(schema, opts)` middleware + 9 schemas (backupConfigUpdate, backupScheduleCreate, backupRestore, backupRestoreFile, appDeploy, appRestore, appRevert, assetUpload, logoUpload). Every exported schema has direct unit tests (41 total in `__tests__/unit/validate.test.js`) covering middleware semantics — not just `schema.validate`. Applied to 8 destructive routes: backups (schedule/restore/config), apps (deploy/restore/revert), assets (upload/logo). Used Joi's authoritative CIDR validator (rejects malformed IPv6 like `::::/64` that the previous hex/colon regex would have accepted). 1539/1539 Jest tests pass (was 1498, +41 new). ESLint warnings unchanged (416 total, all pre-existing — zero new introduced).
- [x] **P1-2: Console→logger sweep (update-manager.js)** — Done in commit e8b9dd5 (DC-060, codex-graded A). All 49 `console.*` calls in `src/managers/update-manager.js` now route through `log.info/log.warn/log.error` from `src/utils/logging` (tag = `'update'`). Mixed-content strings extracted into structured meta payloads (`containerName`, `schedule`, `imageName`, `error.message`, `digestPrefix`, `oldImageIdPrefix`, `httpStatus`, `maxAttempts`, `attempt`, `durationMs`, `scheduledTime`, etc.) so fields are queryable. Errors go through `log.error(ctx, errObj)` so they land in error.log with full stack trace + context. 1539/1539 Jest tests pass (78/78 update-manager tests still pass). ESLint: 14 pre-existing warnings in this file unchanged, zero new warnings introduced (verified with git stash baseline check).
- [x] **P1-3: Console→logger sweep (backup-manager.js)** — Done (commit c55abda). All 36 console calls in src/utilities/backup-manager.js → log.info/warn/error tagged 'backup'. Meta payloads with name, schedule, durationMs, volume, backupId, etc. 1539/1539 tests pass, 0 new ESLint warnings.
- [x] **P1-4: Console→logger sweep (resource-monitor.js)** — Done (commit f2c6fa6). All 32 console calls in src/managers/resource-monitor.js → log tagged 'monitor'. 1539/1539 tests pass.
- [x] **P1-5: Console→logger sweep (credential-manager.js)** — Done (commit 84f63a3). All 20 console calls → log tagged 'cred'. 1539/1539 tests pass.
- [x] **P1-6: Console→logger sweep (auth-manager.js)** — Done (commit 84f63a3). All 20 console calls → log tagged 'auth'. 1539/1539 tests pass.
- [x] **P1-7: Console→logger sweep (bundled-workflows.js)** — Done (commit 191d334). All 18 console calls → log tagged 'workflow'. 1539/1539 tests pass.
- [x] **P1-8: Console→logger sweep (remaining files)** — Done (commit 7b04bc1). 66 calls across 6 files: crypto-utils.js (16), docker-security.js (15), port-lock-manager.js (16), self-updater.js (10), event-workers.js (5), keychain-manager.js (4). Fixed 2 bugs: semicolon in arrow expression body (self-updater.js:162) and out-of-scope variable reference (port-lock-manager.js:137). 1539/1539 tests pass.
+### DC-062: OpenAPI spec is stale — update to match actual v1.15.0 API surface
+- **status:** pending
+- **details:** `openapi.yaml` says `version: 1.0.0` and describes only a fraction of the API. Since DC-046/047 (auth providers), DC-053 (share), DC-055 (billing), DC-058 (share UI), and the tailscale-admin routes were added, the spec is significantly out of date. A stale spec is worse than no spec — it misleads API consumers and breaks any code generation from it. Fix: audit all route files (`grep -rn 'router\.\(get\|post\|put\|delete\|patch\)' routes/`), update openapi.yaml with every endpoint, bump version to 1.15.0, add it to the test suite (DC-017-style source-of-truth test that fails if a route exists but has no spec entry). Effort: ~3 hr.
+- **impact:** Public API trust. No paying customer can integrate against an undocumented API.

-## P2 — Code Quality & Technical Debt
+### DC-063: Branch coverage at 72% — below the 80% gate
+- **status:** pending
+- **details:** Jest coverage report shows branches at 72.14% (303/420), failing the 80% threshold. The uncovered branches are concentrated in error-handling paths (catch blocks, fallback returns, edge-case conditionals). Fix: run `npx jest --coverage --coverageReporters=text` to identify the files with the lowest branch coverage, then add targeted tests for the uncovered conditional paths. Priority files: backup-manager.js (multiple catch blocks), health-checker.js (timeout/retry branches), tailscale-coord.js (API error branches). Effort: ~2 hr.
+- **impact:** Error paths are where production incidents hide. Every untested catch block is a potential crash.

- [x] **P2-1: Version drift fix** — Done (commit 140aa5d). VERSION 1.14.9→1.15.0, CLAUDE.md 1.13.4→1.15.0.
- [x] **P2-2: Delete dead legacy files** — Done (commit 140aa5d). Removed comprehensive-test.js + test-security-fixes.js (-878 lines). (status/api/test-api.js is untracked.)
- [x] **P2-3: ESLint no-empty fix** — Done (commit 140aa5d). Added `no-empty: ['error', { allowEmptyCatch: true }]` to .eslintrc.js. 3 errors→0.
- [x] **P2-4: Fix no-useless-escape** — Done (commit 140aa5d). routes/auth/session-handlers.js:39 `\-` → `.-` (dash moved to end of char class).
- [ ] **P2-5: Test handle leaks** — Run `npx jest --detectOpenHandles --silent 2>&1 | grep -i leak` and add teardown (`afterEach(() => clearInterval/clearTimeout)`) to tests that leave open handles. Focus on `totp.routes.test.js` (22s) and `containers.routes.test.js` (28s).
- [ ] **P2-6: Refactor config-schema.js validateConfig** — Complexity 44 → extract sub-validators for each config section. Behavior-preserving refactor only.
- [ ] **P2-7: Refactor middleware.js auth function** — Complexity 24, nesting depth 6 → extract auth-logic branches into named helper functions.
+### DC-064: Dockerfile runs as root with no resource limits
+- **status:** pending
+- **details:** The Dockerfile has no `USER` directive and `start.sh` has no `--memory` or `--cpus` flags. While root is needed for Docker socket access, the container can still OOM the host. Fix: (1) Add `--memory=512m --memory-swap=1g --cpus=1.5` to the `docker run` in start.sh. (2) Create a non-root user `dashcaddy` for the application process, and use a Docker socket proxy (like `tecnativa/docker-socket-proxy`) that exposes a limited subset of Docker API endpoints — the app only needs read access for monitoring + controlled container lifecycle. (3) Add `--restart=unless-stopped` if not already present. Effort: ~2 hr. Risk: medium — socket proxy may break some Docker API calls, needs testing.
+- **impact:** Without limits, a memory leak in the API can take down the entire host. This is a production safety issue.

-## Completion Criteria
+---

-When all items above are `[x]`, report "All backlog items complete" and stop.
+## P1 — Code Quality & Reliability
+
+### DC-065: Remaining 21 console.* calls — sweep to structured logger
+- **status:** pending
+- **details:** After DC-060 (update-manager) and P1-3 through P1-8, 21 console calls remain across 10 files: `error-handler.js` (2), `email.js` (1), `dns-providers/registry.js` (2), `audit-logger.js` (3), `csrf-protection.js` (3), `config-drift-detector.js` (1), `auto-restart-manager.js` (1), `http.js` (1), `logging.js` (6 intentional — the logger itself), `routes/backups.js` (1). The logging.js calls are fine (the logger IS console internally). The rest should route through `log.info/warn/error`. Some are fallbacks: `ctx.logError || ((_c, err) => console.error(err))` — these fire when ctx isn't available, which is exactly when structured logging matters most. Effort: ~45 min.
+- **impact:** Consistency. The logger write to error.log and supports structured JSON — console does not.
+
+### DC-066: No API integration test for the billing flow end-to-end
+- **status:** pending
+- **details:** DC-057 shipped contract tests and unit tests for the Stripe bridge, but there is no test that exercises the full flow: pricing page → Stripe Checkout → webhook → license-key delivery → license activation → Pro unlock. Build a single integration test that mocks Stripe's API, walks the complete flow, and asserts the license works at the end. This is the revenue path — it must be tested as a chain, not just individual pieces. Effort: ~2 hr.
+- **impact:** Confidence in the revenue pipeline. A broken webhook or catalog mismatch silently loses sales.
+
+### DC-067: No graceful shutdown — SIGTERM kills in-flight requests
+- **status:** pending
+- **details:** server.js handles `uncaughtException` and `unhandledRejection`, but there is no `SIGTERM` handler that calls `server.close()` to drain connections. Docker stop sends SIGTERM (the Dockerfile has `STOPSIGNAL SIGTERM`), but without a handler the process exits immediately, dropping any in-flight API calls. Fix: add a `SIGTERM` handler in server.js that (1) stops accepting new connections via `server.close()`, (2) waits up to 10s for in-flight requests, (3) closes DB/file handles, (4) exits cleanly. Also emit a `shutdown` event so managers (health checker, SSL monitor, workflow engine) can stop their timers. Effort: ~1 hr.
+- **impact:** Zero-downtime deployments. Currently, every `docker stop` drops active requests.
+
+### DC-068: ESLint warnings sweep — 173 pre-existing warnings
+- **status:** pending
+- **details:** While there are 0 ESLint errors, 173 warnings remain. Top files: `dns-providers/base.js` (27), `update-manager.js` (14), `backup-manager.js` (10), `keychain-manager.js` (10), `bundled-workflows.js` (10), `auth/providers/base.js` (9), `log-digest.js` (8). Most are `no-unused-vars`, `require-await`, `no-nested-ternary`. Fix: sweep through the top 10 files, fix what's actionable (unused vars → remove, nested ternaries → extract to named variables, false-positive require-await → mark `_` or restructure). Set a ceiling: warnings should never increase. Effort: ~2 hr.
+- **impact:** Clean codebase. 173 warnings is noise that hides real issues when new ones are added.
+
+### DC-069: Health check notification spam — add failure threshold + cooldown
+- **status:** pending
+- **details:** The workflow engine sends a notification on EVERY health check failure (every 15 min). If a service is down for a day, that's 96 identical notifications. There is no backoff, no deduplication, no "service recovered" message. Fix: (1) Only notify on state TRANSITIONS (up→down, down→up), not every failure. (2) Add a `consecutiveFailures` threshold (e.g., 2 failures before first alert) to avoid flapping noise. (3) Send a recovery notification when a service comes back up. (4) Optional: daily digest of uptime stats instead of per-failure alerts. Effort: ~1.5 hr.
+- **impact:** Operator sanity. The current notification volume is exactly why people mute alerting channels — and then miss real incidents.
+
+---
+
+## P2 — Polish & Developer Experience
+
+### DC-070: No CI/CD pipeline — tests run manually
+- **status:** pending
+- **details:** There is no GitHub Actions / CI configuration. Tests are run manually before push. This means a bad commit can reach main if someone forgets to test. Fix: add `.github/workflows/test.yml` (or Gitea Actions equivalent) that runs `npm ci && npx jest --coverage` on every PR and push to main. Cache node_modules. Upload coverage report as artifact. Block merge on test failure or coverage decrease. Effort: ~1 hr.
+- **impact:** Automated quality gate. No bad commit reaches production.
+
+### DC-071: No error tracking / Sentry integration
+- **status:** pending
+- **details:** Errors go to `error.log` inside the container. If the container is recreated (DC-050 migration), the error log is lost. There is no external error tracking. Fix: add an optional Sentry (or GlitchTip for self-hosted) integration. If `SENTRY_DSN` env var is set, initialize Sentry before Express. Wrap async handlers to capture exceptions. The error-handler.js middleware should forward to Sentry before returning the generic error response. Make it opt-in (no DSN = no Sentry, zero behavior change). Effort: ~1 hr.
+- **impact:** Production visibility. Right now, errors are invisible unless someone SSHs in and reads the log.
+
+### DC-072: Frontend bundle has no source maps in production
+- **status:** pending
+- **details:** `status/build.js` uses esbuild but the production build doesn't emit source maps. When a frontend error occurs in production, the stack trace points to minified bundle lines — useless for debugging. Fix: add `sourcemap: true` to the esbuild production config. Serve `.map` files from Caddy (they're already in `dist/`). Optionally upload source maps to Sentry (DC-071). Effort: ~30 min.
+- **impact:** Frontend bug reports become actionable instead of "line 1 of core.js".
+
+### DC-073: No API request/response logging middleware for debugging
+- **status:** pending
+- **details:** While there is an audit logger for POST/PUT/DELETE, there's no request/response logging middleware for debugging purposes (like morgan or a custom equivalent). When an operator reports "the dashboard is slow" or "this endpoint returns 500 sometimes", there's no way to trace the request through the system. Fix: add an optional debug-level request logger that logs method, path, status, duration, and request ID. Gated behind `LOG_LEVEL=debug` so it's off in production by default. Effort: ~45 min.
+- **impact:** Drastically reduces time-to-resolution for production issues.
+
+### DC-074: Docker image is not multi-stage — build artifacts bloat the image
+- **status:** pending
+- **details:** The Dockerfile copies source files into a single stage based on `node:20-alpine`. The image includes `devDependencies` because `npm install --production` still installs some optional deps, and there's no `.dockerignore` (so `__tests__/`, `.git/`, `node_modules/` from the host can leak in). Fix: (1) Add a `.dockerignore` file excluding `__tests__/`, `.git/`, `node_modules/`, `*.md`, `coverage/`. (2) Convert to multi-stage: build stage installs all deps, production stage copies only `node_modules/` (production) + source. (3) Pin Node.js version: `FROM node:20.10-alpine` instead of `node:20-alpine` (floating). Effort: ~1 hr.
+- **impact:** Smaller image = faster pulls = faster deploys. Current image size carries unnecessary weight.
+
+### DC-075: No health check dashboard endpoint for operators
+- **status:** pending
+- **details:** The `/api/v1/monitoring/stats` endpoint returns container stats, but there's no single "is everything OK" endpoint that returns a human-readable system health summary. Fix: add `GET /api/v1/system/health` that returns `{ status: "healthy"|"degraded"|"unhealthy", checks: { database: "ok", diskSpace: "ok", memory: "ok", uptime: ..., activeServices: N/M, lastError: "..." } }`. This is useful for uptime monitoring services (UptimeRobot, BetterStack) and for a quick operator glance. Effort: ~1 hr.
+- **impact:** Operators can plug DashCaddy into external monitoring without parsing container stats.
+
+---
+
+## P3 — Future & Nice-to-Have
+
+### DC-076: WebSocket support for real-time dashboard updates
+- **status:** pending
+- **details:** The dashboard polls the API every N seconds for service status updates. For a "live" dashboard experience, WebSocket (or SSE) push would be better — status changes appear instantly without polling overhead. Fix: add a WebSocket server (using `ws` library) that pushes service status changes, health check results, and container events to connected dashboard clients. Keep polling as fallback for clients without WS support. Effort: ~3 hr.
+- **impact:** Dashboard feels "live". Reduces API load from polling.
+
+### DC-077: Multi-language (i18n) support
+- **status:** pending
+- **details:** All UI text is hardcoded English. For a public product, internationalization is a step toward wider reach. Fix: extract all user-facing strings into a locale file, add an i18n library (like i18next), provide at minimum an English + Arabic locale (Sami's audience). Effort: ~4 hr.
+- **impact:** Market expansion. Arabic-speaking homelab community is underserved.
+
+### DC-078: Backup and restore of DashCaddy's own configuration
+- **status:** pending
+- **details:** While DashCaddy can backup app data, there's no one-click "backup my entire DashCaddy setup" (services.json, config.json, health-config.json, credentials, Caddyfile, license) that could be restored on a fresh install. Fix: add `GET /api/v1/system/export` (returns a signed JSON bundle) and `POST /api/v1/system/import` (restores from bundle). The credentials file should be encrypted with a user-provided passphrase. Effort: ~2 hr.
+- **impact:** Migration story. "Moving DashCaddy to a new host" is currently a multi-hour manual process.
+
+### DC-079: Mobile-responsive dashboard improvements
+- **status:** pending
+- **details:** While the dashboard is somewhat responsive, it's not optimized for mobile use. For operators checking services on their phone, the experience should be touch-first. Fix: audit all dashboard pages on mobile viewport, fix any horizontal scroll, ensure buttons are touch-target sized (min 44px), add a mobile-specific layout for the service grid. Effort: ~3 hr.
+- **impact:** Operators check services on their phone. Current mobile experience is usable but not polished.
+
+### DC-080: Plugin/extension system for custom services
+- **status:** pending
+- **details:** DashCaddy supports a fixed set of service templates. A plugin system would allow community-contributed service definitions (e.g., "Home Assistant", "Vaultwarden", "Nextcloud") without modifying core code. Fix: define a plugin manifest schema (name, logo, health check URL pattern, config fields), load plugins from `/data/plugins/`, add a community plugin registry page. Effort: ~4 hr.
+- **impact:** Community growth. Extensibility is what makes a tool ecosystem vs. a product.
+
+---
+
+---
+
+## P2.5 — Security Hardening (Deep Audit Findings)
+
+### DC-081: 151 of 160 mutating routes have NO Joi input validation
+- **status:** pending
+- **details:** P1-1 added Joi validation to 8 routes, but a scan shows **151 out of 160** POST/PUT/PATCH/DELETE routes still accept raw `req.body` without schema validation. That's 94% of the mutation surface unvalidated. Routes like `POST /api/v1/services/:id`, `PUT /api/v1/config`, `POST /api/v1/tailscale/*`, `POST /api/v1/health/config/:id` all accept arbitrary input. Fix: extend `src/utilities/validate.js` with schemas for every mutating route, wire them in. This is the single highest-impact security improvement. Effort: ~4 hr (batch by route file).
+- **impact:** Input validation is the #1 defense against injection, abuse, and crashes. 94% gap is a P0 hiding as a P2.
+
+### DC-082: Command injection surface in ca.js — 5 execSync calls with interpolation
+- **status:** pending
+- **details:** `routes/ca.js` has 5 `execSync()` calls with template-string interpolation: lines 164, 175, 180, 203, 263. P0-2 fixed the password injection (`execFileSync`), but the remaining calls interpolate file paths and subjects (`${certFile}`, `${keyFile}`, `${subject}`, `${configFile}`). If any of these contain user input (e.g., a service name with `;` or backticks), it's command injection. Fix: convert ALL `execSync(\`...\`)` calls to `execFileSync('openssl', [...args])` with no shell interpolation. Also fix `src/docker/self-updater.js:717` (`execSync(\`tar xzf \"${tarballPath}\"...`)`) and `src/utilities/backup-manager.js:8` (imported execSync). Effort: ~2 hr.
+- **impact:** Any execSync with interpolation is a potential RCE. This is the same class of bug P0-2 already fixed — finish the job.
+
+### DC-083: 30 source files have zero test coverage
+- **status:** pending
+- **details:** The test gap scan found 30 source files with NO corresponding test file, including critical paths: `license-manager.js` (534 lines, the entire revenue validation path), `config-schema.js`, `middleware.js` (the auth/rate-limit/CORS stack), `startup-validator.js`, all 7 DNS provider modules (`technitium.js`, `cloudflare.js`, `rfc2136.js`, `manual.js`, `base.js`, `registry.js`, `email.js`), `docker-maintenance.js`, `config/migrations.js`, `event-workers.js`, `keychain-manager.js`, `event-store.js`, `host-registry.js`. Fix: prioritize license-manager.js (revenue path) and middleware.js (security stack) first, then work through the rest. Effort: ~8 hr (can be done incrementally, 2-3 files per PR).
+- **impact:** license-manager.js validates Pro licenses — an untested bug there could silently break activation for every paying customer.
+
+### DC-084: No .dockerignore — test files and .git leak into Docker image
+- **status:** pending
+- **details:** There is no `.dockerignore` file. The Docker build context includes `__tests__/` (hundreds of test files), any `.git/` directory, `coverage/`, `node_modules/` from the host, and markdown files. This bloats the image (currently 249MB) and can leak sensitive test fixtures. Fix: create `.dockerignore` with: `__tests__/`, `.git/`, `node_modules/`, `coverage/`, `*.md`, `.eslintrc.js`, `jest.config.js`, `npm-debug.log*`, `.env*`, `openapi.yaml` (only needed at build time if at all). Also add `.dockerignore` to the git repo. Effort: ~15 min.
+- **impact:** Faster builds, smaller images, no test fixture leaks.
+
+### DC-085: Math.random() used for security-sensitive IDs
+- **status:** pending
+- **details:** `health-checker.js:352` generates incident IDs with `Math.random().toString(36)`. `resource-monitor.js:143` uses `Math.random()` for sampling. `rfc2136.js:120` generates temp filenames with `Math.random()`. While these aren't crypto-level secrets, `Math.random()` is not collision-resistant and is predictable. Fix: use `crypto.randomUUID()` for incident IDs, `crypto.randomBytes()` for temp filenames, and a simple counter for sampling. Effort: ~30 min.
+- **impact:** Defense in depth. Predictable IDs can be exploited if they ever become user-facing.
+
+---
+
+## P3.5 — Operational Maturity
+
+### DC-086: No structured error codes — errors are ad-hoc strings
+- **status:** pending
+- **details:** The HTTP status code audit shows only 6 distinct status codes used across routes (200, 201, 400, 401, 404, 429). Error responses are plain strings like `"Invalid input"` or `"Unauthorized"`. There is no error code system (like `INVALID_CONFIG`, `SERVICE_NOT_FOUND`, `LICENSE_EXPIRED`). Fix: define a canonical error code enum in `src/utilities/errors.js`, return `{ error: { code: "SERVICE_NOT_FOUND", message: "..." } }` in all error responses. This makes API integration programmable (consumers switch on `code`, not parse `message`). Effort: ~3 hr.
+- **impact:** API consumers can handle errors programmatically. Required for SDK generation and good DX.
+
+### DC-087: No API client SDK / type definitions
+- **status:** pending
+- **details:** There is no TypeScript definitions file (`.d.ts`) or client SDK. Anyone integrating against the API has to read the source code to understand request/response shapes. Fix: (1) Generate TypeScript types from the OpenAPI spec (once DC-062 updates it) using `openapi-typescript`. (2) Ship a `@dashcaddy/api-types` npm package or include a `types/index.d.ts` in the repo. (3) Optionally, a thin JS client wrapper. Effort: ~2 hr (after DC-062).
+- **impact:** Developer adoption. A typed SDK lowers the barrier to integration.
+
+### DC-088: No log rotation — error.log grows forever
+- **status:** pending
+- **details:** The logger has basic rotation (rename to `.1` when it hits a size limit), but only keeps ONE rotated file. In production, error.log can grow rapidly during incident bursts. There's no retention policy, no compression, no date-based rotation. Fix: (1) Add a max-size threshold (e.g., 10MB) and keep N rotated files (e.g., 5). (2) Compress rotated files with gzip. (3) Add date-based naming so logs are greppable by date. (4) Add a `GET /api/v1/system/logs` endpoint so operators can view recent logs without SSH. Effort: ~1.5 hr.
+- **impact:** Prevents disk fill during incident storms. Makes logs accessible without SSH access.
+
+### DC-089: No rate limit on public license activation endpoint
+- **status:** pending
+- **details:** The rate limiter `skip` list includes `req.path === '/api/v1/license/status'` and `req.path.startsWith('/api/v1/license/feature/')` — meaning license checks bypass rate limiting. While these are GET endpoints, the license *activation* endpoint (`POST /api/v1/license/activate`) should have its own dedicated rate limit to prevent brute-force license key guessing. Fix: add a dedicated `licenseLimiter` with tighter limits (e.g., 10 attempts per 15 min per IP) on POST /license/activate. Effort: ~30 min.
+- **impact:** Prevents license key brute-forcing. Pro keys follow a predictable format (DC-XXX-XXXXX-XXXXXX) making them guessable without rate limiting.
+
+### DC-090: Node.js version drift — Dockerfile says 20, host runs 22
+- **status:** pending
+- **details:** Dockerfile uses `FROM node:20-alpine` (floating). The development machine runs Node v22.22.3. The container uses whatever `node:20-alpine` resolves to at build time. This version drift can cause "works on my machine" bugs (especially around `fetch()`, `crypto`, and `structuredClone` which changed between 20 and 22). Fix: (1) Pin the exact version: `FROM node:20.10.0-alpine3.19`. (2) Add `.nvmrc` or `engines` field to package.json specifying the minimum version. (3) Optionally upgrade to Node 22 across the board. Effort: ~30 min.
+- **impact:** Reproducible builds. No surprise behavior from Node version drift.
+
+### DC-091: No dependency update automation (Dependabot/Renovate)
+- **status:** pending
+- **details:** Dependencies are updated manually. The 21 production dependencies and 4 dev dependencies can fall behind silently. There's no automated PR for security patches or major version bumps. Fix: add either GitHub Dependabot config (`.github/dependabot.yml`) or Renovate config (`renovate.json`). Schedule weekly checks. Group minor/patch updates into one PR. Keep major updates separate for review. Effort: ~30 min.
+- **impact:** Security patches arrive automatically. No more manual `npm audit` sessions.
+
+### DC-092: No health check for DashCaddy's own dependencies (disk space, memory)
+- **status:** pending
+- **details:** The Dockerfile has a HEALTHCHECK that hits `/health`, but that endpoint only checks if the Express server responds. It doesn't check: disk space (if `/app/data` is on a full disk), memory pressure (Node heap near limit), Docker socket connectivity (if Docker daemon is down), Caddy admin API reachability. Fix: extend the health endpoint to include dependency checks: `{ diskSpace: { free: ..., total: ... }, memory: { heapUsed: ..., heapTotal: ..., rss: ... }, docker: { reachable: true/false }, caddy: { reachable: true/false } }`. Return 503 if any critical dependency is down. Effort: ~1.5 hr.
+- **impact:** Catch systemic issues before they become outages. External monitoring can alert on `503`.
+
+### DC-093: Workflow engine has no retry/backoff for failed actions
+- **status:** pending
+- **details:** When the workflow engine's health-check action fails, it logs the failure and moves on — no retry. If a service is temporarily down and recovers in 30s, the workflow reports it as failed for the entire 15-min cycle. Fix: add configurable retry logic to workflow actions (e.g., retry 2 times with 30s backoff before reporting failure). Also add a `maxRetries` config to the health-check workflow. Effort: ~1.5 hr.
+- **impact:** Fewer false-positive alerts. More resilient monitoring.
+
+### DC-094: No audit trail for config changes (who changed what, when)
+- **status:** pending
+- **details:** The audit logger (`src/security/audit-logger.js`) captures POST/PUT/DELETE events, but config changes (services.json, health-config.json, config.json) are made via file writes, not API calls. There's no record of who changed a service URL, disabled a health check, or modified a workflow. Fix: (1) Route all config mutations through API endpoints that log to the audit trail. (2) Add a `GET /api/v1/system/audit-log` endpoint for viewing the trail. (3) Include a diff of what changed in each audit entry. Effort: ~2 hr.
+- **impact:** Accountability. When something breaks, you can trace who changed the config and when.
+
+---
+
+## P4 — Advanced Features
+
+### DC-095: No multi-user support — single-admin only
+- **status:** pending
+- **details:** DashCaddy has one admin user. For teams or homelab groups, there's no way to add a second admin or a read-only viewer. Fix: (1) Add a `users.json` with role-based access (admin, editor, viewer). (2) Add user management endpoints. (3) Add per-service permissions (editor can manage services but not billing). This is a significant feature, not a quick fix. Effort: ~6 hr.
+- **impact:** Multi-admin is a requirement for team/enterprise adoption.
+
+### DC-096: No API key management (create/revoke/scoped keys)
+- **status:** pending
+- **details:** API authentication uses session cookies or TOTP. There's no way to create scoped API keys for automation (e.g., a read-only key for monitoring, a key that can only manage one service). Fix: add `POST /api/v1/api-keys` (create with scopes), `GET /api/v1/api-keys` (list), `DELETE /api/v1/api-keys/:id` (revoke). Store hashed in credentials.json. Effort: ~2 hr.
+- **impact:** Enables automation and third-party integrations without sharing the admin password.
+
+### DC-097: No Prometheus / Grafana metrics export
+- **status:** pending
+- **details:** There's a basic `/metrics` endpoint, but it returns JSON, not Prometheus format. Fix: (1) Add `prom-client` dependency. (2) Instrument key metrics: HTTP request duration histogram, active WebSocket connections, health check pass/fail counter, container count gauge, API error rate. (3) Expose `GET /metrics` in Prometheus exposition format alongside the existing JSON endpoint. (4) Ship a Grafana dashboard JSON as a reference. Effort: ~2 hr.
+- **impact:** Industry-standard observability. Drop-in Grafana dashboard for operators.
+
+### DC-098: No changelog / release notes generation
+- **status:** pending
+- **details:** Releases are tracked via git commits and VERSION file, but there's no user-facing changelog. For a public product, customers need to know what changed between versions. Fix: (1) Add a `CHANGELOG.md` following Keep a Changelog format. (2) Auto-generate from conventional commits (if adopted) or git log. (3) Display "What's new" on the dashboard after updates. Effort: ~1.5 hr.
+- **impact:** Customer trust. Users won't update without knowing what changed.
+
+### DC-099: No automated database migration system
+- **status:** pending
+- **details:** Config migrations exist (`src/config/migrations.js`) but are ad-hoc. As the data schema evolves (new fields in services.json, config.json), there's no versioned migration system. Fix: (1) Add a `schemaVersion` field to config files. (2) Create a migration runner that applies migrations sequentially on startup. (3) Log each migration. (4) Support rollback on failure. Effort: ~2 hr.
+- **impact:** Safe upgrades. No more manual config patching after updates.
+
+### DC-100: No service discovery / auto-detect running containers
+- **status:** pending
+- **details:** Services are added manually by specifying URLs. DashCaddy doesn't auto-detect running Docker containers and suggest adding them as services. Fix: (1) Scan `docker ps` for containers with exposed ports. (2) Match against known app templates (Plex, Sonarr, etc.). (3) Show a "Detected services" panel with one-click add. (4) Periodically re-scan for new containers. Effort: ~3 hr.
+- **impact:** Zero-config onboarding. New users see their services auto-discovered.
+
+---
+
+---
+
+## P5 — Product Vision: Self-Hosting Platform
+
+> These tasks directly serve the vision from PRODUCT-VISION.md:
+> "Self-host anything in 30 seconds — no config files, no TLS headaches."
+
+### DC-101: Disk Space Manager with user-configurable budget + dashboard widget
+- **status:** in-progress (backend done, needs UI + deployment)
+- **details:** Backend module (`src/monitoring/disk-space-monitor.js`) and routes (`routes/disk-space.js`) are written and pass tests. Still needs: (1) Dashboard widget showing disk usage gauge with budget line, breakdown by category (images/volumes/logs/build-cache), and "Cleanup now" button. (2) Settings page section for disk budget input. (3) Deploy to DNS2 production. API endpoints: GET /api/v1/disk, GET /api/v1/disk/breakdown, POST /api/v1/disk/config, POST /api/v1/disk/cleanup. Effort: ~2 hr remaining.
+- **impact:** Users set a disk budget (e.g., "DashCaddy gets 20GB") and the system auto-manages cleanup. The #1 reason people abandon self-hosting is disk filling up silently. This solves it.
+
+### DC-102: One-click deploy should auto-generate Caddyfile entry + DNS record
+- **status:** pending
+- **details:** When a user deploys an app from the catalog, DashCaddy should automatically: (1) Create the Docker container, (2) Add a Caddyfile reverse_proxy block with TLS for `appname.tld`, (3) Create a DNS record pointing to the host, (4) Reload Caddy, (5) Add the service to the dashboard with health check. Currently steps 2-4 are manual. Fix: add a `deployApp(serviceId, options)` function that orchestrates the full chain. The Caddyfile generation can use the admin API (POST to :2019) so no file editing needed. DNS record creation uses the existing Technitium/Cloudflare DNS provider integration. Effort: ~4 hr.
+- **impact:** This is THE core value proposition. Without this, DashCaddy is just Portainer with extra steps. With this, it's a self-hosting platform.
+
+### DC-103: Container auto-discovery with auto-route generation
+- **status:** pending
+- **details:** When DashCaddy detects a new running Docker container (via docker events API), it should: (1) Check if it matches a known app template (Plex, Sonarr, etc.), (2) Auto-generate a Caddy reverse proxy route, (3) Create a DNS record, (4) Add it to the dashboard, (5) Notify the user "Found Nextcloud on port 80 — added to your dashboard at https://nextcloud.yourdomain.com". This is the "zero-config" experience. Effort: ~4 hr.
+- **impact:** Magic. User installs Nextcloud via docker run → 10 seconds later it's on their dashboard with HTTPS.
+
+### DC-104: App catalog with curated templates + one-click deploy
+- **status:** pending
+- **details:** The app templates exist (`src/docker/app-templates.js` has 50+ templates) but there's no polished catalog UI. Build a "App Store" page: grid of app cards with icons, descriptions, and "Install" buttons. Clicking install triggers DC-102's deploy chain. Include categories (Media, Productivity, Security, Development). Show "Popular" and "New" badges. Allow community templates via DC-080's plugin system. Effort: ~4 hr.
+- **impact:** This is the front door. The catalog IS the product for most users.
+
+### DC-105: Smart defaults wizard — "What do you want to self-host?"
+- **status:** pending
+- **details:** Instead of asking users to configure DNS servers, TLD, Caddy paths, and auth — ask them ONE question: "What domain do you want to use?" Then auto-detect: (1) DNS server (check if Technitium is running locally), (2) TLD (.home, .local, or their domain), (3) Caddy installation, (4) Docker setup. Configure everything automatically. If something is missing, install it. The wizard should handle 90% of setups in under 5 questions. Effort: ~3 hr.
+- **impact:** First-run experience determines whether users stay. A 15-step config wizard kills adoption. A 1-question wizard creates delight.
+
+### DC-106: Caddyfile-as-code — visual reverse proxy builder
+- **status:** pending
+- **details:** Instead of editing Caddyfile text, provide a visual builder: "I want requests to blog.yourdomain.com to go to container X on port 80, with authentication, rate limiting, and compression." Generate the Caddyfile block from the form. Show a live preview of the generated config. Apply via Caddy admin API. This eliminates the need to learn Caddyfile syntax entirely. Effort: ~3 hr.
+- **impact:** Caddyfile syntax is the #1 technical barrier. A visual builder makes reverse proxy configuration accessible to non-sysadmins.
+
+### DC-107: Disaster recovery — one-click backup + restore of entire setup
+- **status:** pending
+- **details:** Extend DC-078 to include container definitions, Caddyfile, DNS zones, and all app data. The backup should be a single encrypted tarball. "Restore on new host" should bring back the entire DashCaddy setup + all apps in one command. This is the "set it and forget it" insurance policy. Effort: ~3 hr.
+- **impact:** Fear of losing setup is why people stick with SaaS. One-click backup + restore removes that fear.
+
+### DC-108: Multi-host fleet management — deploy across multiple servers
+- **status:** pending
+- **details:** Currently DashCaddy manages one Docker host. For users with multiple servers (like Sami's DNS1/DNS2/DNS3 setup), DashCaddy should connect to remote Docker daemons (via TLS or SSH) and manage containers across all hosts from one dashboard. "Deploy Nextcloud on DNS2" or "Deploy Plex on SAMI-PC" from the same UI. Show per-host resource usage and health. Effort: ~6 hr.
+- **impact:** Power users have multiple servers. Managing them individually defeats the purpose of a unified platform.
+
+---
+
+## Summary by Priority
+
+| Priority | Count | Effort | Theme |
+|----------|-------|--------|-------|
+| P0 | 3 (DC-062–064) | ~7 hr | Public release blockers |
+| P1 | 5 (DC-065–069) | ~7 hr | Reliability & code quality |
+| P2 | 6 (DC-070–075) | ~5.5 hr | Polish & DX |
+| P2.5 | 5 (DC-081–085) | ~15 hr | Security hardening (deep audit) |
+| P3 | 5 (DC-076–080) | ~16 hr | Future growth |
+| P3.5 | 9 (DC-086–094) | ~14.5 hr | Operational maturity |
+| P4 | 6 (DC-095–100) | ~16.5 hr | Advanced features |
+| P5 | 8 (DC-101–108) | ~29 hr | Product vision: self-hosting platform |
+| **Total** | **47** | **~110.5 hr** | |
@@ -0,0 +1,107 @@
+# DashCaddy Product Vision
+
+## The Problem
+
+Self-hosting software is hard. To deploy a single app (Plex, Nextcloud, Vaultwarden, anything), you need to:
+
+1. **Understand Docker** — images, containers, volumes, ports, networks, compose files
+2. **Configure a reverse proxy** — Caddy/Nginx/Traefik config files with obscure syntax
+3. **Set up TLS/HTTPS** — certificate generation, ACME, DNS challenges, trust stores
+4. **Configure DNS** — A records, CNAMEs, split-horizon DNS, DoH
+5. **Secure it** — firewall rules, auth, rate limiting, CSRF, CORS
+6. **Monitor it** — health checks, log rotation, disk space, restart policies
+7. **Maintain it** — updates, backups, migrations, disaster recovery
+
+Each of these is a rabbit hole. A typical homelabber spends **hours per app** fighting configuration files, reading documentation, and debugging cryptic errors. This is why most people give up and just use SaaS.
+
+## The Solution
+
+**DashCaddy is a self-hosting platform.** It eliminates the complexity by fusing Docker, Caddy, and DNS management into one unified interface.
+
+### Core Value: "Self-host anything in 30 seconds."
+
+```
+User picks an app from the catalog
+    ↓
+DashCaddy deploys the Docker container
+    ↓
+DashCaddy generates the Caddy reverse proxy config automatically
+    ↓
+DashCaddy provisions TLS certificates
+    ↓
+DashCaddy configures DNS records
+    ↓
+DashCaddy sets up authentication (SSO gate)
+    ↓
+App is live at https://app.yourdomain.com — done.
+```
+
+No editing config files. No Docker networking headaches. No TLS cert errors. No DNS archaeology.
+
+## What Makes DashCaddy Different
+
+### vs. Plain Docker / docker-compose
+- Docker gives you containers. DashCaddy gives you **containers + networking + TLS + DNS + auth + monitoring**.
+- Docker doesn't know about your domain. DashCaddy manages the full stack from DNS record to container port.
+- Docker doesn't tell you when your disk is full. DashCaddy monitors, alerts, and auto-cleans.
+
+### vs. Portainer
+- Portainer is a **Docker UI**. DashCaddy is a **self-hosting platform**.
+- Portainer shows containers. DashCaddy shows services — with their URLs, health, certs, and auth.
+- Portainer doesn't manage Caddy, DNS, or TLS. DashCaddy fuses all three.
+- Portainer doesn't have a one-click app catalog with auto-configured reverse proxy + DNS + TLS.
+
+### vs. CasaOS / Umbrel
+- These are **app stores**. DashCaddy is a **platform**.
+- They bundle their own Docker management. DashCaddy works with your existing Docker setup.
+- They don't manage Caddy or advanced DNS. DashCaddy handles the full network stack.
+- DashCaddy's SSO gate, credential injection, and security center are enterprise-grade features.
+
+### vs. Yunohost / FreedomBox
+- These are **complete OS replacements**. DashCaddy is a **single Docker container**.
+- No OS install needed. Deploy DashCaddy on any Linux machine in 60 seconds.
+- DashCaddy works alongside your existing setup — it doesn't take over your machine.
+
+## The Three Pillars
+
+### 1. One-Click Deploy (The "Wow" moment)
+Pick an app → DashCaddy handles everything:
+- Docker container creation with optimal defaults
+- Caddy reverse proxy route with TLS
+- DNS record creation
+- SSO authentication gate
+- Health check configuration
+- Disk budget allocation
+
+### 2. Zero-Config Networking (The "It just works" layer)
+- Automatic TLS via Caddy's ACME + Let's Encrypt
+- Automatic DNS via Technitium/Cloudflare integration
+- Automatic reverse proxy with sane defaults
+- Automatic SSO with credential injection
+- Automatic subdomain routing (subdomain or subdirectory mode)
+
+### 3. Self-Healing Infrastructure (The "Set it and forget it" layer)
+- Health checks with retry/backoff and notification on state transitions
+- Auto-restart failed containers
+- Auto-cleanup when disk approaches budget
+- Config drift detection and correction
+- SSL certificate expiration monitoring
+- Container log rotation and size enforcement
+- Docker image cleanup — old images pruned automatically
+
+## Who Is It For?
+
+1. **Homelabbers** — tired of spending weekends on config files
+2. **Small businesses** — want self-hosted alternatives to SaaS without hiring a sysadmin
+3. **Privacy-conscious users** — want to own their data without the technical burden
+4. **Developers** — want a quick way to deploy side projects with TLS + auth
+
+## Revenue Model
+
+- **Free tier**: Up to 5 services, community support
+- **Pro license**: Unlimited services, email alerts, advanced health checks, priority updates
+- **Site license**: Multi-host, team accounts, API access
+
+## North Star Metric
+
+**Time-to-first-app-deploy** — how long from install to having a working self-hosted service with HTTPS. Target: under 60 seconds.
@@ -1,10 +1,14 @@
-node_modules/
 __tests__/
-jest.config.js
-.env
-.encryption-key
+.git/
 .gitignore
-.dockerignore
-*.log
+node_modules/
+coverage/
 *.md
-docker-compose.yml
+.eslintrc.js
+jest.config.js
+npm-debug.log*
+.env*
+.env.example
+.DS_Store
+*.log
+dc.png
@@ -1,4 +1,4 @@
-FROM node:20-alpine
+FROM node:20.11.1-alpine3.19

 WORKDIR /app

@@ -0,0 +1,490 @@
+/**
+ * Tests for the graceful shutdown coordinator (DC-067).
+ *
+ * Covers:
+ *  - Constructor rejects bad inputs
+ *  - shutdown() emits 'shutdown' event with the signal name
+ *  - shutdown() stops each manager in declaration order
+ *  - shutdown() is idempotent — second call logs and returns
+ *  - shutdown() force-exits after drainTimeoutMs if server.close never fires
+ *  - shutdown() clears the force-exit timer when server.close fires first
+ *  - shutdown() catches manager.stop() throws so one bad manager doesn't
+ *    prevent the others from being stopped
+ *  - installSignalHandlers() registers for SIGTERM and SIGINT by default
+ *
+ * process.exit is mocked so tests don't actually kill the test runner.
+ */
+'use strict';
+
+const EventEmitter = require('events');
+const {
+  createShutdownCoordinator,
+  installSignalHandlers,
+  DEFAULT_DRAIN_TIMEOUT_MS,
+  ShutdownCoordinator,
+} = require('../src/utilities/shutdown');
+
+describe('ShutdownCoordinator (DC-067)', () => {
+  let exitMock;
+  let exitCalls;
+
+  beforeEach(() => {
+    exitCalls = [];
+    // Use jest.spyOn so the mock is restored in afterEach (via clearMocks +
+    // restoreMocks: true in jest.config.js). Direct assignment to process.exit
+    // doesn't suppress Jest's process.exit watchlist which fails the test.
+    exitMock = jest.spyOn(process, 'exit').mockImplementation((code) => {
+      exitCalls.push(code);
+      // Returning undefined prevents the test runner from actually exiting.
+      return undefined;
+    });
+  });
+
+  afterEach(() => {
+    exitMock.mockRestore();
+    jest.clearAllTimers();
+  });
+
+  function makeFakeServer({ closeBehavior = 'sync' } = {}) {
+    // 'sync' close calls back immediately.
+    // 'never' close never calls back (used to test force-exit).
+    if (closeBehavior === 'never') {
+      return { close: jest.fn() };
+    }
+    return { close: jest.fn((cb) => { cb(); }) };
+  }
+
+  function makeFakeLog() {
+    return {
+      info: jest.fn(),
+      warn: jest.fn(),
+      error: jest.fn(),
+    };
+  }
+
+  describe('constructor', () => {
+    test('throws if server is missing', () => {
+      expect(() => createShutdownCoordinator({ log: makeFakeLog(), managers: [] }))
+        .toThrow('server is required');
+    });
+
+    test('throws if log is missing or invalid', () => {
+      expect(() => createShutdownCoordinator({ server: makeFakeServer(), managers: [] }))
+        .toThrow('log must have info');
+      expect(() => createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: { foo: 'bar' },
+        managers: [],
+      })).toThrow('log must have info');
+      expect(() => createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: { info: () => {}, warn: () => {} },  // missing error
+        managers: [],
+      })).toThrow('log must have info');
+      // A log with all three methods should NOT throw.
+      expect(() => createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: { info: () => {}, warn: () => {}, error: () => {} },
+        managers: [],
+      })).not.toThrow();
+    });
+
+    test('uses DEFAULT_DRAIN_TIMEOUT_MS when drainTimeoutMs is not finite positive', () => {
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        drainTimeoutMs: 0,
+        managers: [],
+      });
+      expect(c.drainTimeoutMs).toBe(DEFAULT_DRAIN_TIMEOUT_MS);
+
+      const c2 = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        drainTimeoutMs: NaN,
+        managers: [],
+      });
+      expect(c2.drainTimeoutMs).toBe(DEFAULT_DRAIN_TIMEOUT_MS);
+
+      const c3 = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        drainTimeoutMs: 5000,
+        managers: [],
+      });
+      expect(c3.drainTimeoutMs).toBe(5000);
+    });
+
+    test('defaults managers to [] when not an array', () => {
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+      });
+      expect(c.managers).toEqual([]);
+    });
+
+    test('is an EventEmitter', () => {
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        managers: [],
+      });
+      expect(c).toBeInstanceOf(EventEmitter);
+      expect(c).toBeInstanceOf(ShutdownCoordinator);
+    });
+  });
+
+  describe('shutdown()', () => {
+    test('emits shutdown event with signal name', () => {
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        managers: [],
+      });
+      const handler = jest.fn();
+      c.on('shutdown', handler);
+
+      c.shutdown('SIGTERM');
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(handler).toHaveBeenCalledWith('SIGTERM');
+    });
+
+    test('swallows exceptions thrown by shutdown event listeners', () => {
+      const log = makeFakeLog();
+      const server = makeFakeServer();
+      const c = createShutdownCoordinator({
+        server,
+        log,
+        managers: [],
+      });
+      c.on('shutdown', () => { throw new Error('listener boom'); });
+
+      // shutdown() must NOT propagate the exception — that would abort
+      // the entire shutdown sequence before server.close is even called.
+      expect(() => c.shutdown('SIGTERM')).not.toThrow();
+      expect(log.error).toHaveBeenCalledWith(
+        'shutdown',
+        "event listener for 'shutdown' threw",
+        expect.objectContaining({ error: 'listener boom' }),
+      );
+      // server.close should still have been called.
+      expect(server.close).toHaveBeenCalledTimes(1);
+    });
+
+    test('swallows exceptions thrown by closed event listeners', async () => {
+      const log = makeFakeLog();
+      const server = makeFakeServer();
+      const c = createShutdownCoordinator({
+        server,
+        log,
+        managers: [],
+      });
+      c.on('closed', () => { throw new Error('closed listener boom'); });
+
+      // process.exit is mocked; we just verify the throw doesn't bubble.
+      c.shutdown('SIGTERM');
+      await new Promise((resolve) => setImmediate(resolve));
+      // The closed listener threw but the exit still got recorded.
+      expect(exitCalls).toEqual([0]);
+    });
+
+    test('calls server.close() once', () => {
+      const server = makeFakeServer();
+      const c = createShutdownCoordinator({
+        server,
+        log: makeFakeLog(),
+        managers: [],
+      });
+
+      c.shutdown('SIGTERM');
+
+      expect(server.close).toHaveBeenCalledTimes(1);
+    });
+
+    test('stops each manager in declaration order AFTER server.close fires', async () => {
+      const order = [];
+      const managers = [
+        { name: 'first', stop: jest.fn(() => { order.push('first'); }) },
+        { name: 'second', stop: jest.fn(() => { order.push('second'); }) },
+        { name: 'third', stop: jest.fn(() => { order.push('third'); }) },
+      ];
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        managers,
+      });
+
+      c.shutdown('SIGTERM');
+      // Wait for the async chain (server.close → _stopManagersInOrder →
+      // process.exit) to settle. The mock exit is synchronous so this
+      // resolves once all microtasks drain.
+      await new Promise((resolve) => setImmediate(resolve));
+
+      expect(order).toEqual(['first', 'second', 'third']);
+    });
+
+    test('does NOT stop managers until server.close callback fires', () => {
+      const order = [];
+      // Use a server whose close callback fires only when we manually call it.
+      let deferredCloseCb;
+      const server = {
+        close: jest.fn((cb) => { deferredCloseCb = cb; }),
+      };
+      const managers = [
+        { name: 'first', stop: jest.fn(() => { order.push('first'); }) },
+      ];
+      const c = createShutdownCoordinator({
+        server,
+        log: makeFakeLog(),
+        managers,
+      });
+
+      c.shutdown('SIGTERM');
+
+      // server.close has been called but its callback hasn't fired yet.
+      expect(server.close).toHaveBeenCalledTimes(1);
+      // Manager has NOT been stopped yet — server is still draining.
+      expect(order).toEqual([]);
+
+      // Now fire the deferred callback to simulate drain completion.
+      deferredCloseCb();
+
+      // Manager stopped AFTER server.close fired.
+      expect(order).toEqual(['first']);
+    });
+
+    test('continues stopping remaining managers if one throws', async () => {
+      const order = [];
+      const managers = [
+        { name: 'first', stop: jest.fn(() => { order.push('first'); }) },
+        { name: 'broken', stop: jest.fn(() => { throw new Error('boom'); }) },
+        { name: 'third', stop: jest.fn(() => { order.push('third'); }) },
+      ];
+      const log = makeFakeLog();
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log,
+        managers,
+      });
+
+      c.shutdown('SIGTERM');
+      await new Promise((resolve) => setImmediate(resolve));
+
+      expect(order).toEqual(['first', 'third']);
+      expect(log.warn).toHaveBeenCalledWith(
+        'shutdown',
+        'manager stop failed: broken',
+        expect.objectContaining({ error: 'boom' }),
+      );
+    });
+
+    test('is idempotent — second shutdown() returns without re-running', () => {
+      const server = makeFakeServer();
+      const c = createShutdownCoordinator({
+        server,
+        log: makeFakeLog(),
+        managers: [{ name: 'm', stop: jest.fn() }],
+      });
+
+      c.shutdown('SIGTERM');
+      c.shutdown('SIGTERM');
+      c.shutdown('SIGINT');
+
+      expect(server.close).toHaveBeenCalledTimes(1);
+      expect(c.isShuttingDown()).toBe(true);
+    });
+
+    test('isShuttingDown() flips false→true on first shutdown call', () => {
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        managers: [],
+      });
+      expect(c.isShuttingDown()).toBe(false);
+      c.shutdown('SIGTERM');
+      expect(c.isShuttingDown()).toBe(true);
+    });
+
+    test('force-exits after drainTimeoutMs if server.close never fires', () => {
+      jest.useFakeTimers();
+      try {
+        const server = makeFakeServer({ closeBehavior: 'never' });
+        const log = makeFakeLog();
+        const c = createShutdownCoordinator({
+          server,
+          log,
+          drainTimeoutMs: 1000,
+          managers: [],
+        });
+
+        c.shutdown('SIGTERM');
+        expect(exitCalls).toEqual([]);
+
+        jest.advanceTimersByTime(999);
+        expect(exitCalls).toEqual([]);
+
+        jest.advanceTimersByTime(2);
+        expect(exitCalls).toEqual([0]);
+        expect(log.warn).toHaveBeenCalledWith(
+          'shutdown',
+          expect.stringContaining('drain timeout (1000ms) reached before HTTP server closed'),
+        );
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    test('force-exits after drainTimeoutMs if manager.stop() hangs after HTTP close', () => {
+      jest.useFakeTimers();
+      try {
+        const server = makeFakeServer();  // calls back immediately
+        const log = makeFakeLog();
+        // Manager that NEVER resolves — simulates a hung cleanup.
+        const hungManager = {
+          name: 'hung',
+          stop: jest.fn(() => new Promise(() => {})),  // never resolves
+        };
+        const c = createShutdownCoordinator({
+          server,
+          log,
+          drainTimeoutMs: 1000,
+          managers: [hungManager],
+        });
+
+        c.shutdown('SIGTERM');
+        // After the synchronous shutdown() call: server.close has fired
+        // (serverClosed=true), but hungManager.stop() has been called and
+        // its promise is pending. managersStopped is still false.
+        // process.exit should NOT have been called yet.
+        expect(exitCalls).toEqual([]);
+
+        jest.advanceTimersByTime(1001);
+        // Now the safety-net timer fires — force-exit because manager hung.
+        expect(exitCalls).toEqual([0]);
+        expect(log.warn).toHaveBeenCalledWith(
+          'shutdown',
+          expect.stringContaining('after HTTP close (manager hung)'),
+        );
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    test('clears force-exit timer when manager drain completes promptly', () => {
+      jest.useFakeTimers();
+      try {
+        const server = makeFakeServer();  // calls back on the same tick
+        const log = makeFakeLog();
+        // Quick-stopping manager. The close callback awaits stop(),
+        // which resolves immediately, so managersStopped flips true
+        // and the safety-net timer is cleared before it can fire.
+        const fastManager = {
+          name: 'fast',
+          stop: jest.fn(() => Promise.resolve()),
+        };
+        const c = createShutdownCoordinator({
+          server,
+          log,
+          drainTimeoutMs: 1000,
+          managers: [fastManager],
+        });
+
+        c.shutdown('SIGTERM');
+
+        // Flush microtasks so the close callback's await stop() resolves,
+        // managersStopped flips true, the timer is cleared, and
+        // process.exit(0) is recorded exactly once.
+        return Promise.resolve().then(() => Promise.resolve()).then(() => {
+          expect(exitCalls).toEqual([0]);
+
+          // Advance well past the drain timeout — no extra exit should fire.
+          jest.advanceTimersByTime(5000);
+          expect(exitCalls).toEqual([0]);
+        });
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+  });
+
+  describe('installSignalHandlers()', () => {
+    // Track listeners added during each test so we can remove them in
+    // afterEach. process.on() listeners leak across tests otherwise.
+    let addedListeners;
+    let originalProcessOn;
+
+    beforeEach(() => {
+      addedListeners = [];
+      originalProcessOn = process.on;
+      // Wrap process.on to record every (signal, listener) pair we add.
+      // Must capture originalProcessOn at wrap time so we can call it.
+      const realOn = originalProcessOn;
+      process.on = function patchedOn(signal, listener) {
+        addedListeners.push({ signal, listener });
+        return realOn.call(process, signal, listener);
+      };
+    });
+
+    afterEach(() => {
+      process.on = originalProcessOn;
+      for (const { signal, listener } of addedListeners) {
+        originalProcessOn.call(process, signal, listener);  // ensure clean slate
+        process.removeListener(signal, listener);
+      }
+      addedListeners = [];
+    });
+
+    test('registers listeners on the given signals', () => {
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        managers: [],
+      });
+      const shutdownSpy = jest.spyOn(c, 'shutdown');
+
+      installSignalHandlers(c);
+
+      // Emit fake signals through process.emit to verify the listener was
+      // registered (process.on listens to the process EventEmitter).
+      process.emit('SIGTERM');
+      process.emit('SIGINT');
+
+      expect(shutdownSpy).toHaveBeenCalledWith('SIGTERM');
+      expect(shutdownSpy).toHaveBeenCalledWith('SIGINT');
+    });
+
+    test('accepts custom signal list', () => {
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        managers: [],
+      });
+      const shutdownSpy = jest.spyOn(c, 'shutdown');
+
+      installSignalHandlers(c, ['SIGHUP']);
+
+      process.emit('SIGHUP');
+      expect(shutdownSpy).toHaveBeenCalledWith('SIGHUP');
+    });
+
+    test('is idempotent — calling installSignalHandlers twice does not double-register', () => {
+      const c = createShutdownCoordinator({
+        server: makeFakeServer(),
+        log: makeFakeLog(),
+        managers: [],
+      });
+      const shutdownSpy = jest.spyOn(c, 'shutdown');
+
+      installSignalHandlers(c);
+      installSignalHandlers(c);  // second call
+      installSignalHandlers(c);  // third call
+
+      // The installedSignals tracker should have one entry per signal.
+      expect(c._installedSignals).toEqual(['SIGTERM', 'SIGINT']);
+
+      process.emit('SIGTERM');
+      expect(shutdownSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+});
@@ -3,6 +3,9 @@
  "version": "1.15.0",
  "description": "DashCaddy API server - Dashboard backend for Docker, Caddy & DNS management",
  "main": "server.js",
+  "engines": {
+    "node": ">=20.0.0"
+  },
  "scripts": {
    "start": "node server.js",
    "test": "jest",
@@ -0,0 +1,64 @@
+const express = require('express');
+const { success, error: errorResponse } = require('../src/utils/responses');
+
+/**
+ * Disk space management routes
+ *
+ * GET  /disk                 — current usage snapshot (budget, breakdown, status)
+ * GET  /disk/breakdown       — detailed breakdown incl. per-container log sizes
+ * GET  /disk/config          — get disk budget settings
+ * POST /disk/config          — update disk budget settings
+ * POST /disk/cleanup         — trigger manual cleanup (standard|aggressive|logs-only)
+ */
+module.exports = function({ diskSpaceMonitor, asyncHandler, log }) {
+  const router = express.Router();
+
+  // Current disk usage snapshot
+  router.get('/', asyncHandler(async (req, res) => {
+    const snapshot = await diskSpaceMonitor.getSnapshot();
+    success(res, snapshot);
+  }, 'disk-get'));
+
+  // Detailed breakdown (includes per-container log sizes)
+  router.get('/breakdown', asyncHandler(async (req, res) => {
+    const breakdown = await diskSpaceMonitor.getDetailedBreakdown();
+    success(res, breakdown);
+  }, 'disk-breakdown'));
+
+  // Get disk budget config
+  router.get('/config', asyncHandler(async (req, res) => {
+    success(res, diskSpaceMonitor.getConfig());
+  }, 'disk-config-get'));
+
+  // Update disk budget config
+  router.post('/config', asyncHandler(async (req, res) => {
+    const { diskBudgetGB, warningThresholdPct, criticalThresholdPct, autoCleanup, enabled, cleanupAggressivePct } = req.body;
+
+    const updates = {};
+    if (typeof diskBudgetGB === 'number' && diskBudgetGB > 0) updates.diskBudgetGB = Math.min(diskBudgetGB, 1000);
+    if (typeof warningThresholdPct === 'number') updates.warningThresholdPct = Math.min(Math.max(warningThresholdPct, 50), 99);
+    if (typeof criticalThresholdPct === 'number') updates.criticalThresholdPct = Math.min(Math.max(criticalThresholdPct, 60), 99);
+    if (typeof cleanupAggressivePct === 'number') updates.cleanupAggressivePct = Math.min(Math.max(cleanupAggressivePct, 70), 99);
+    if (typeof autoCleanup === 'boolean') updates.autoCleanup = autoCleanup;
+    if (typeof enabled === 'boolean') updates.enabled = enabled;
+
+    const config = diskSpaceMonitor.configure(updates);
+    log.info('disk', 'Disk budget updated', updates);
+
+    success(res, { message: 'Disk budget updated', config });
+  }, 'disk-config-set'));
+
+  // Manual cleanup trigger
+  router.post('/cleanup', asyncHandler(async (req, res) => {
+    const level = req.body?.level || 'standard';
+    if (!['standard', 'aggressive', 'logs-only'].includes(level)) {
+      return errorResponse(res, 'Invalid cleanup level. Use: standard, aggressive, or logs-only', 400);
+    }
+
+    log.info('disk', 'Manual cleanup triggered', { level, by: req.auth?.user || 'api' });
+    const result = await diskSpaceMonitor.performCleanup(level);
+    success(res, result);
+  }, 'disk-cleanup'));
+
+  return router;
+};
@@ -1,7 +1,20 @@
 const express = require('express');
+const rateLimit = require('express-rate-limit');
 const { success, error: errorResponse } = require('../src/utils/responses');
 const { ValidationError } = require('../src/utilities/errors');

+// Dedicated rate limiter for license activation — prevents brute-force key guessing.
+// Pro keys follow a predictable format (DC-XXX-XXXXX-XXXXXX), so without rate
+// limiting an attacker could enumerate valid keys.
+const licenseActivateLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 10,                   // 10 attempts per window per IP
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { success: false, error: 'Too many license activation attempts. Please try again later.' },
+  skip: () => process.env.NODE_ENV === 'test',
+});
+
 /**
 * License routes factory
 * @param {Object} deps - Explicit dependencies
@@ -13,7 +26,7 @@ module.exports = function({ licenseManager, asyncHandler }) {
  const router = express.Router();

  // Activate a license code
-  router.post('/activate', asyncHandler(async (req, res) => {
+  router.post('/activate', licenseActivateLimiter, asyncHandler(async (req, res) => {
    const { code } = req.body;
    if (!code) {
      throw new ValidationError('License code is required');
@@ -252,43 +252,52 @@ process.on('uncaughtException', (error) => {
      log.info('server', 'All feature modules initialized');
    });

-    // Graceful shutdown
-    const shutdown = (signal) => {
-      log.info('shutdown', `${signal} received, draining connections...`);
-      
-      const resourceMonitor = require('./src/managers/resource-monitor');
-      const backupManager = require('./src/utilities/backup-manager');
-      const healthChecker = require('./src/monitoring/health-checker');
-      const updateManager = require('./src/managers/update-manager');
-      const selfUpdater = require('./src/docker/self-updater');
-      
-      resourceMonitor.stop();
-      backupManager.stop();
-      healthChecker.stop();
-      updateManager.stop();
-      selfUpdater.stop();
-      
-      try {
-        const dockerMaintenance = require('./src/docker/docker-maintenance');
-        dockerMaintenance.stop();
-      } catch { /* optional */ }
-      
-      try {
-        const logDigest = require('./src/security/log-digest');
-        logDigest.stop();
-      } catch { /* optional */ }
+    // Graceful shutdown (DC-067) — drains in-flight HTTP connections, stops
+    // each manager in deterministic order, emits a 'shutdown' event for any
+    // additional listeners, and force-exits after a 10s drain timeout.
+    // Idempotent: a second SIGTERM during shutdown is a no-op.
+    const {
+      createShutdownCoordinator,
+      installSignalHandlers,
+      DEFAULT_DRAIN_TIMEOUT_MS,
+    } = require('./src/utilities/shutdown');

-      server.close(() => {
-        log.info('shutdown', 'HTTP server closed');
-        process.exit(0);
+    const optionalManagers = [];
+    try {
+      optionalManagers.push({
+        name: 'docker-maintenance',
+        stop: () => require('./src/docker/docker-maintenance').stop(),
      });
-      
-      // Force exit after 5s if connections don't drain
-      setTimeout(() => process.exit(0), 5000).unref();
-    };
+    } catch { /* optional module */ }
+    try {
+      optionalManagers.push({
+        name: 'log-digest',
+        stop: () => require('./src/security/log-digest').stop(),
+      });
+    } catch { /* optional module */ }

-    process.on('SIGTERM', () => shutdown('SIGTERM'));
-    process.on('SIGINT', () => shutdown('SIGINT'));
+    const coordinator = createShutdownCoordinator({
+      server,
+      log,
+      drainTimeoutMs: DEFAULT_DRAIN_TIMEOUT_MS,
+      managers: [
+        { name: 'resource-monitor', stop: () => require('./src/managers/resource-monitor').stop() },
+        { name: 'backup-manager', stop: () => require('./src/utilities/backup-manager').stop() },
+        { name: 'health-checker', stop: () => require('./src/monitoring/health-checker').stop() },
+        { name: 'update-manager', stop: () => require('./src/managers/update-manager').stop() },
+        { name: 'self-updater', stop: () => require('./src/docker/self-updater').stop() },
+        ...optionalManagers,
+      ],
+    });
+
+    // Expose the shutdown signal as an event so additional listeners can
+    // subscribe without touching this file. The coordinator is an
+    // EventEmitter and emits 'shutdown' on SIGTERM/SIGINT.
+    coordinator.on('shutdown', (signal) => {
+      log.info('shutdown', 'shutdown event observed', { signal });
+    });
+
+    installSignalHandlers(coordinator);

  } catch (error) {
    console.error('[FATAL] Server startup failed:', error);
@@ -90,9 +90,11 @@ const DependencyManager = require('./managers/dependency-manager');
 const autoRestartRoutes = require('../routes/auto-restart');
 const configDriftRoutes = require('../routes/config-drift');
 const sslMonitorRoutes = require('../routes/ssl-monitor');
+const diskSpaceRoutes = require('../routes/disk-space');
 const { AutoRestartManager } = require('./managers/auto-restart-manager');
 const { ConfigDriftDetector } = require('./managers/config-drift-detector');
 const SSLMonitor = require('./monitoring/ssl-monitor');
+const { DiskSpaceMonitor } = require('./monitoring/disk-space-monitor');
 const DNSPropagationChecker = require('./dns/dns-propagation');

 // Constants
@@ -455,6 +457,12 @@ async function createApp() {
  sslMonitor.start(3600000); // 1 hour
  log.info('app', 'SSL monitor initialized');

+  // Initialize disk space monitor (disk budget + auto-cleanup)
+  const diskSpaceMonitor = new DiskSpaceMonitor({ log, config: ctx.siteConfig });
+  ctx.diskSpaceMonitor = diskSpaceMonitor;
+  diskSpaceMonitor.start(600000); // 10 min
+  log.info('app', 'Disk space monitor initialized', { budgetGB: diskSpaceMonitor.getConfig().diskBudgetGB });
+
  // Initialize DNS propagation checker
  const dnsPropagationChecker = new DNSPropagationChecker(ctx);
  ctx.dnsPropagationChecker = dnsPropagationChecker;
@@ -709,6 +717,11 @@ async function createApp() {
    asyncHandler: ctx.asyncHandler,
    logError: ctx.logError,
  }));
+  apiRouter.use('/disk', diskSpaceRoutes({
+    diskSpaceMonitor: ctx.diskSpaceMonitor,
+    asyncHandler: ctx.asyncHandler,
+    log: ctx.log,
+  }));

  // Inline API routes (mounted under /api/v1 below)
  // Note: /health lives at root only — see root-level health check below.
@@ -10,6 +10,7 @@

 const { execFile } = require('child_process');
 const { promisify } = require('util');
+const crypto = require('crypto');
 const dns = require('dns');
 const os = require('os');
 const path = require('path');
@@ -117,7 +118,7 @@ class RFC2136Provider extends BaseDNSProvider {
   */
  async _runNsupdate(commands) {
    const script = commands.join('\n') + '\n';
-    const tmpFile = path.join(os.tmpdir(), `nsupdate-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.cmd`);
+    const tmpFile = path.join(os.tmpdir(), `nsupdate-${crypto.randomBytes(4).toString('hex')}.cmd`);

    try {
      await fs.promises.writeFile(tmpFile, script, { mode: 0o600 });
@@ -0,0 +1,392 @@
+/**
+ * Disk Space Monitor
+ *
+ * Tracks Docker + system disk usage against a user-configured budget.
+ * When usage exceeds thresholds, triggers automatic cleanup and notifications.
+ *
+ * Key concepts:
+ *   - diskBudgetGB:  How much disk the user is willing to give DashCaddy (default 10)
+ *   - The monitor calculates Docker's footprint (images, volumes, containers, build cache)
+ *   - Breakdown shows where space goes so users can make informed decisions
+ *   - Auto-cleanup triggers at 80% (warning), 90% (aggressive), 95% (critical)
+ */
+
+const EventEmitter = require('events');
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_BUDGET_GB = 10;
+const DEFAULT_CONFIG = {
+  enabled: true,
+  diskBudgetGB: DEFAULT_BUDGET_GB,
+  warningThresholdPct: 80,
+  criticalThresholdPct: 90,
+  autoCleanup: true,
+  cleanupAggressivePct: 95,
+};
+
+class DiskSpaceMonitor extends EventEmitter {
+  constructor({ log, config }) {
+    super();
+    this.log = log;
+    this.config = config;
+    this.lastSnapshot = null;
+    this.lastCleanup = null;
+    this.intervalHandle = null;
+    this.diskConfig = { ...DEFAULT_CONFIG };
+    this._loadConfig();
+  }
+
+  /**
+   * Load disk budget config from the site config file
+   * Stored under `diskSpace` key in config.json
+   */
+  _loadConfig() {
+    try {
+      const raw = this.config?.diskSpace;
+      if (raw) {
+        this.diskConfig = {
+          ...DEFAULT_CONFIG,
+          ...raw,
+        };
+      }
+    } catch {
+      // Use defaults
+    }
+  }
+
+  /**
+   * Update disk space settings
+   */
+  configure(updates) {
+    const prev = { ...this.diskConfig };
+    this.diskConfig = { ...this.diskConfig, ...updates };
+    this._persistConfig();
+    this.emit('config-changed', { prev, current: this.diskConfig });
+    return this.diskConfig;
+  }
+
+  _persistConfig() {
+    // The config is persisted by the caller (settings route) which merges
+    // into config.json. We just expose the current state.
+    if (this.config) {
+      this.config.diskSpace = this.diskConfig;
+    }
+  }
+
+  /**
+   * Get a disk usage snapshot using `df` and `docker system df -v`
+   */
+  async getSnapshot() {
+    const [diskInfo, dockerInfo] = await Promise.all([
+      this._getDiskInfo(),
+      this._getDockerInfo(),
+    ]);
+
+    const snapshot = {
+      timestamp: new Date().toISOString(),
+      system: diskInfo,
+      docker: dockerInfo,
+      budget: {
+        configuredGB: this.diskConfig.diskBudgetGB,
+        dockerUsageGB: dockerInfo.totalGB,
+        remainingBudgetGB: Math.max(0, this.diskConfig.diskBudgetGB - dockerInfo.totalGB),
+        budgetUsedPct: Math.min(100, Math.round((dockerInfo.totalGB / this.diskConfig.diskBudgetGB) * 100)),
+        status: this._getBudgetStatus(dockerInfo.totalGB),
+      },
+      config: { ...this.diskConfig },
+      lastCleanup: this.lastCleanup,
+    };
+
+    this.lastSnapshot = snapshot;
+
+    // Check thresholds and emit events
+    this._checkThresholds(snapshot);
+
+    return snapshot;
+  }
+
+  _getBudgetStatus(dockerUsageGB) {
+    const pct = (dockerUsageGB / this.diskConfig.diskBudgetGB) * 100;
+    if (pct >= this.diskConfig.cleanupAggressivePct) return 'critical';
+    if (pct >= this.diskConfig.criticalThresholdPct) return 'aggressive';
+    if (pct >= this.diskConfig.warningThresholdPct) return 'warning';
+    return 'healthy';
+  }
+
+  _checkThresholds(snapshot) {
+    const { status, budgetUsedPct } = snapshot.budget;
+    if (status === 'critical' || status === 'aggressive') {
+      this.emit('budget-exceeded', snapshot);
+      if (this.diskConfig.autoCleanup) {
+        this.performCleanup(status === 'critical' ? 'aggressive' : 'standard').catch(() => {});
+      }
+    } else if (status === 'warning') {
+      this.emit('budget-warning', snapshot);
+    }
+  }
+
+  async _getDiskInfo() {
+    try {
+      const { stdout } = await execFileAsync('df', ['-B1', '/']);
+      const lines = stdout.trim().split('\n');
+      const parts = lines[1].split(/\s+/);
+      return {
+        totalBytes: parseInt(parts[1], 10),
+        usedBytes: parseInt(parts[2], 10),
+        availableBytes: parseInt(parts[3], 10),
+        usedPct: parseInt(parts[4], 10),
+        mount: parts[5],
+        totalGB: Math.round(parseInt(parts[1], 10) / 1073741824 * 10) / 10,
+        usedGB: Math.round(parseInt(parts[2], 10) / 1073741824 * 10) / 10,
+        availableGB: Math.round(parseInt(parts[3], 10) / 1073741824 * 10) / 10,
+      };
+    } catch {
+      return { totalBytes: 0, usedBytes: 0, availableBytes: 0, usedPct: 0, totalGB: 0, usedGB: 0, availableGB: 0 };
+    }
+  }
+
+  async _getDockerInfo() {
+    try {
+      const { stdout } = await execFileAsync('docker', ['system', 'df', '--format', '{{json .}}']);
+      const lines = stdout.trim().split('\n').filter(Boolean);
+
+      let images = { count: 0, totalGB: 0, reclaimableGB: 0 };
+      let containers = { count: 0, totalGB: 0, reclaimableGB: 0 };
+      let volumes = { count: 0, totalGB: 0, reclaimableGB: 0 };
+      let buildCache = { count: 0, totalGB: 0, reclaimableGB: 0 };
+
+      for (const line of lines) {
+        try {
+          const d = JSON.parse(line);
+          const type = d.Type?.toLowerCase() || '';
+          const sizeGB = this._parseSizeToGB(d.Size);
+          const reclaimGB = this._parseSizeToGB(d.Reclaimable);
+
+          if (type === 'images') images = { count: parseInt(d.TotalCount, 10) || 0, totalGB: sizeGB, reclaimableGB: reclaimGB };
+          else if (type === 'containers') containers = { count: parseInt(d.TotalCount, 10) || 0, totalGB: sizeGB, reclaimableGB: reclaimGB };
+          else if (type === 'local volumes') volumes = { count: parseInt(d.TotalCount, 10) || 0, totalGB: sizeGB, reclaimableGB: reclaimGB };
+          else if (type === 'build cache') buildCache = { count: parseInt(d.TotalCount, 10) || 0, totalGB: sizeGB, reclaimableGB: reclaimGB };
+        } catch { /* skip unparseable lines */ }
+      }
+
+      const totalGB = Math.round((images.totalGB + containers.totalGB + volumes.totalGB + buildCache.totalGB) * 100) / 100;
+      const reclaimableGB = Math.round((images.reclaimableGB + containers.reclaimableGB + volumes.reclaimableGB + buildCache.reclaimableGB) * 100) / 100;
+
+      return {
+        images,
+        containers,
+        volumes,
+        buildCache,
+        totalGB,
+        reclaimableGB,
+      };
+    } catch {
+      return { images: {}, containers: {}, volumes: {}, buildCache: {}, totalGB: 0, reclaimableGB: 0 };
+    }
+  }
+
+  /**
+   * Parse Docker's human-readable size strings (e.g., "2.519GB", "8.108MB", "0B")
+   */
+  _parseSizeToGB(str) {
+    if (!str || str === '0B') return 0;
+    const match = str.match(/^([\d.]+)(B|KB|MB|GB|TB)$/i);
+    if (!match) return 0;
+    const value = parseFloat(match[1]);
+    const unit = match[2].toUpperCase();
+    const multipliers = { B: 1e-9, KB: 1e-6, MB: 1e-3, GB: 1, TB: 1e3 };
+    return Math.round(value * (multipliers[unit] || 0) * 1000) / 1000;
+  }
+
+  /**
+   * Get per-container log file sizes (the hidden disk hog)
+   */
+  async _getContainerLogs() {
+    try {
+      const { stdout } = await execFileAsync('sh', ['-c', 'for f in /var/lib/docker/containers/*/*-json.log; do [ -f "$f" ] && stat -c "%s %n" "$f"; done 2>/dev/null | sort -rn | head -10']);
+      const entries = [];
+      for (const line of stdout.trim().split('\n').filter(Boolean)) {
+        const [sizeStr, ...fileParts] = line.split(' ');
+        const sizeBytes = parseInt(sizeStr, 10);
+        entries.push({
+          sizeBytes,
+          sizeMB: Math.round(sizeBytes / 1048576 * 10) / 10,
+          file: fileParts.join(' '),
+        });
+      }
+      return entries;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Perform cleanup
+   * @param {string} level - 'standard' | 'aggressive' | 'logs-only'
+   * @returns {Object} cleanup result with bytes reclaimed
+   */
+  async performCleanup(level = 'standard') {
+    const startTime = Date.now();
+    const result = {
+      level,
+      startedAt: new Date(startTime).toISOString(),
+      actions: [],
+      bytesReclaimed: 0,
+    };
+
+    try {
+      // Always: truncate oversized container logs
+      const logsBefore = await this._getContainerLogs();
+      let logBytesFreed = 0;
+      for (const log of logsBefore) {
+        if (log.sizeBytes > 100 * 1048576) { // > 100MB
+          try {
+            await execFileAsync('truncate', ['-s', '0', log.file]);
+            logBytesFreed += log.sizeBytes;
+            result.actions.push({ action: 'truncate-log', file: log.file, freedBytes: log.sizeBytes });
+          } catch { /* skip */ }
+        }
+      }
+      result.bytesReclaimed += logBytesFreed;
+
+      // Always: vacuum journald to 200MB
+      try {
+        const { stdout } = await execFileAsync('journalctl', ['--vacuum-size=200M']);
+        const freedMatch = stdout.match(/freed ([\d.]+[KMGT]?B)/i);
+        if (freedMatch) {
+          const freedBytes = this._humanToBytes(freedMatch[1]);
+          result.bytesReclaimed += freedBytes;
+          result.actions.push({ action: 'vacuum-journal', freedBytes, freedHuman: freedMatch[1] });
+        }
+      } catch { /* skip */ }
+
+      if (level === 'standard' || level === 'aggressive') {
+        // Prune dangling images
+        try {
+          const { stdout } = await execFileAsync('docker', ['image', 'prune', '-f', '--filter', 'dangling=true']);
+          const reclaimed = this._extractDockerReclaimed(stdout);
+          result.bytesReclaimed += reclaimed;
+          result.actions.push({ action: 'prune-dangling-images', freedBytes: reclaimed });
+        } catch { /* skip */ }
+
+        // Prune unused volumes
+        try {
+          const { stdout } = await execFileAsync('docker', ['volume', 'prune', '-f']);
+          const reclaimed = this._extractDockerReclaimed(stdout);
+          result.bytesReclaimed += reclaimed;
+          result.actions.push({ action: 'prune-unused-volumes', freedBytes: reclaimed });
+        } catch { /* skip */ }
+
+        // Prune build cache (keep last 500MB)
+        try {
+          const { stdout } = await execFileAsync('docker', ['builder', 'prune', '-f', '--keep-storage', '500m']);
+          const reclaimed = this._extractDockerReclaimed(stdout);
+          result.bytesReclaimed += reclaimed;
+          result.actions.push({ action: 'prune-build-cache', freedBytes: reclaimed });
+        } catch { /* skip */ }
+      }
+
+      if (level === 'aggressive') {
+        // Remove ALL images not used by running containers
+        try {
+          const { stdout } = await execFileAsync('docker', ['image', 'prune', '-a', '-f']);
+          const reclaimed = this._extractDockerReclaimed(stdout);
+          result.bytesReclaimed += reclaimed;
+          result.actions.push({ action: 'prune-all-unused-images', freedBytes: reclaimed });
+        } catch { /* skip */ }
+
+        // Prune stopped containers older than 24h
+        try {
+          const { stdout } = await execFileAsync('docker', ['container', 'prune', '-f', '--filter', 'until=24h']);
+          const reclaimed = this._extractDockerReclaimed(stdout);
+          result.bytesReclaimed += reclaimed;
+          result.actions.push({ action: 'prune-old-containers', freedBytes: reclaimed });
+        } catch { /* skip */ }
+      }
+
+      result.completedAt = new Date().toISOString();
+      result.durationMs = Date.now() - startTime;
+      result.bytesReclaimedGB = Math.round(result.bytesReclaimed / 1073741824 * 100) / 100;
+
+      this.lastCleanup = result;
+      this.emit('cleanup-complete', result);
+
+      if (this.log) {
+        this.log.info('disk', 'Disk cleanup completed', {
+          level,
+          bytesReclaimed: result.bytesReclaimed,
+          GBReclaimed: result.bytesReclaimedGB,
+          durationMs: result.durationMs,
+          actions: result.actions.length,
+        });
+      }
+
+      return result;
+    } catch (err) {
+      result.error = err.message;
+      result.completedAt = new Date().toISOString();
+      if (this.log) {
+        this.log.error('disk', 'Disk cleanup failed', { error: err.message, level });
+      }
+      return result;
+    }
+  }
+
+  _humanToBytes(str) {
+    const match = str.match(/^([\d.]+)(B|KB|MB|GB|TB)$/i);
+    if (!match) return 0;
+    const value = parseFloat(match[1]);
+    const unit = match[2].toUpperCase();
+    const multipliers = { B: 1, KB: 1024, MB: 1048576, GB: 1073741824, TB: 1099511627776 };
+    return Math.round(value * (multipliers[unit] || 0));
+  }
+
+  _extractDockerReclaimed(stdout) {
+    const match = stdout.match(/reclaimed\s+([\d.]+[KMGT]?B)/i) || stdout.match(/Total reclaimed space:\s*([\d.]+[KMGT]?B)/i);
+    if (match) return this._humanToBytes(match[1]);
+    return 0;
+  }
+
+  /**
+   * Start periodic monitoring
+   * @param {number} intervalMs - check interval (default 10 minutes)
+   */
+  start(intervalMs = 600000) {
+    if (this.intervalHandle) return;
+    this.log?.info?.('disk', 'Disk space monitor started', { intervalMs });
+    // Initial check
+    this.getSnapshot().catch(() => {});
+    this.intervalHandle = setInterval(() => {
+      this.getSnapshot().catch(() => {});
+    }, intervalMs);
+  }
+
+  stop() {
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle);
+      this.intervalHandle = null;
+    }
+  }
+
+  getConfig() {
+    return { ...this.diskConfig };
+  }
+
+  async getDetailedBreakdown() {
+    const [snapshot, containerLogs] = await Promise.all([
+      this.getSnapshot(),
+      this._getContainerLogs(),
+    ]);
+    return {
+      ...snapshot,
+      containerLogs,
+    };
+  }
+}
+
+module.exports = { DiskSpaceMonitor, DEFAULT_DISK_CONFIG: DEFAULT_CONFIG };
@@ -6,6 +6,7 @@

 const https = require('https');
 const http = require('http');
+const crypto = require('crypto');
 const EventEmitter = require('events');
 const fs = require('fs');
 const path = require('path');
@@ -349,7 +350,7 @@ class HealthChecker extends EventEmitter {

    // Create new incident
    const incident = {
-      id: `incident-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+      id: `incident-${crypto.randomUUID()}`,
      serviceId,
      type,
      message,
@@ -11,6 +11,7 @@ const fs = require('fs');
 const fsp = require('fs').promises;
 const path = require('path');
 const { DOCKER } = require('../utilities/constants');
+const { log } = require('../utils/logging');

 const docker = new Docker();

@@ -63,7 +64,7 @@ class LogDigest extends EventEmitter {
    // Collect logs every hour
    this.collectInterval = setInterval(() => {
      this._collectHourlyLogs().catch(e =>
-        console.error('[LogDigest] Hourly collection failed:', e.message)
+        log.error('logdigest', e, { phase: 'hourlyCollect' })
      );
    }, DOCKER.DIGEST.COLLECT_INTERVAL);

@@ -71,7 +72,7 @@ class LogDigest extends EventEmitter {
    this._scheduleDailyDigest();

    // Run initial collection after 2 minutes
-    setTimeout(() => {
+    this._initialTimeout = setTimeout(() => {
      if (this.running) {
        this._collectHourlyLogs().catch(() => {});
      }
@@ -89,6 +90,10 @@ class LogDigest extends EventEmitter {
      clearTimeout(this.digestTimeout);
      this.digestTimeout = null;
    }
+    if (this._initialTimeout) {
+      clearTimeout(this._initialTimeout);
+      this._initialTimeout = null;
+    }
  }

  /**
@@ -195,7 +200,7 @@ class LogDigest extends EventEmitter {
        hourSummary.services[appId] = serviceSummary;
      }
    } catch (e) {
-      console.error('[LogDigest] Container enumeration failed:', e.message);
+      log.error('logdigest', e, { phase: 'enumerateContainers' });
    }

    // Add to ring buffer
@@ -258,7 +263,7 @@ class LogDigest extends EventEmitter {
    const delay = next.getTime() - now.getTime();
    this.digestTimeout = setTimeout(() => {
      this.generateDailyDigest().catch(e =>
-        console.error('[LogDigest] Daily digest generation failed:', e.message)
+        log.error('logdigest', e, { phase: 'dailyDigest' })
      );
      // Reschedule for tomorrow
      if (this.running) this._scheduleDailyDigest();
@@ -3,12 +3,161 @@
 * Validates config.json structure to catch typos and invalid values early.
 */

-const VALID_TIMEZONES_SAMPLE = [
-  'UTC', 'America/New_York', 'America/Chicago', 'America/Denver', 'America/Los_Angeles',
-  'Europe/London', 'Europe/Paris', 'Europe/Berlin', 'Asia/Tokyo', 'Asia/Shanghai',
-  'Asia/Singapore', 'Australia/Sydney', 'Pacific/Auckland'
+const VALID_THEMES = ['dark', 'light', 'blue'];
+const VALID_ROUTING_MODES = ['subdomain', 'subdirectory'];
+const VALID_DNS_PROVIDERS = ['technitium', 'cloudflare', 'rfc2136', 'manual'];
+
+const KNOWN_KEYS = [
+  'tld', 'caName', 'dns', 'dnsServers', 'dashboardHost', 'timezone', 'theme',
+  'updatedAt', 'timestamp', 'logo', 'logoPosition', 'favicon', 'weather',
+  'setupComplete', 'setupCompleted', 'setupMode', 'onboardingCompleted',
+  'configurationType', 'defaults', 'customLogo', 'customFavicon',
+  'dashboardTitle', 'tailscale', 'license', 'skipped',
+  'routingMode', 'domain', 'email', 'defaultIP', 'pylon',
+  'customLogoDark', 'customLogoLight'
 ];

+/**
+ * @param {string[]} arr
+ * @param {string} val
+ * @returns {boolean}
+ */
+function isInArray(arr, val) {
+  return arr.includes(val);
+}
+
+/**
+ * @param {{errors:string[], warnings:string[]}} ctx
+ * @param {object} config
+ */
+function validateTld(ctx, config) {
+  if (config.tld === undefined) return;
+  if (typeof config.tld !== 'string') {
+    ctx.errors.push('tld must be a string');
+    return;
+  }
+  const tld = config.tld.startsWith('.') ? config.tld : '.' + config.tld;
+  if (!/^\.[a-z0-9][a-z0-9-]*$/.test(tld)) {
+    ctx.errors.push(`tld "${config.tld}" contains invalid characters (use lowercase alphanumeric)`);
+  }
+  if (tld.length > 20) {
+    ctx.warnings.push(`tld "${config.tld}" is unusually long`);
+  }
+}
+
+/**
+ * @param {{errors:string[], warnings:string[]}} ctx
+ * @param {object} config
+ */
+function validateDns(ctx, config) {
+  if (config.dns === undefined) return;
+  if (typeof config.dns !== 'object' || config.dns === null) {
+    ctx.errors.push('dns must be an object');
+    return;
+  }
+  if (config.dns.ip !== undefined && typeof config.dns.ip !== 'string') {
+    ctx.errors.push('dns.ip must be a string');
+  }
+  if (config.dns.ip && !/^[\d.]+$/.test(config.dns.ip) && !/^[a-zA-Z0-9.-]+$/.test(config.dns.ip)) {
+    ctx.errors.push(`dns.ip "${config.dns.ip}" is not a valid IP address or hostname`);
+  }
+  if (config.dns.port !== undefined) {
+    const port = parseInt(config.dns.port, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      ctx.errors.push(`dns.port "${config.dns.port}" is not a valid port number (1-65535)`);
+    }
+  }
+  if (config.dns.servers !== undefined) {
+    if (typeof config.dns.servers !== 'object' || config.dns.servers === null) {
+      ctx.errors.push('dns.servers must be an object');
+    }
+  }
+  if (config.dns.provider !== undefined) {
+    if (typeof config.dns.provider !== 'string') {
+      ctx.errors.push('dns.provider must be a string');
+    } else if (!isInArray(VALID_DNS_PROVIDERS, config.dns.provider)) {
+      ctx.warnings.push(`dns.provider "${config.dns.provider}" is not one of: ${VALID_DNS_PROVIDERS.join(', ')}. It may still work if a custom adapter is installed.`);
+    }
+  }
+}
+
+/**
+ * @param {{errors:string[], warnings:string[]}} ctx
+ * @param {object} config
+ */
+function validateDashboardHost(ctx, config) {
+  if (config.dashboardHost === undefined) return;
+  if (typeof config.dashboardHost !== 'string') {
+    ctx.errors.push('dashboardHost must be a string');
+  } else if (config.dashboardHost && !/^[a-zA-Z0-9][a-zA-Z0-9.-]*$/.test(config.dashboardHost)) {
+    ctx.errors.push(`dashboardHost "${config.dashboardHost}" contains invalid characters`);
+  }
+}
+
+/**
+ * @param {{errors:string[], warnings:string[]}} ctx
+ * @param {object} config
+ */
+function validateTimezone(ctx, config) {
+  if (config.timezone === undefined) return;
+  if (typeof config.timezone !== 'string') {
+    ctx.errors.push('timezone must be a string');
+  } else if (config.timezone) {
+    try {
+      Intl.DateTimeFormat(undefined, { timeZone: config.timezone });
+    } catch {
+      ctx.errors.push(`timezone "${config.timezone}" is not a recognized IANA timezone`);
+    }
+  }
+}
+
+/**
+ * @param {{errors:string[], warnings:string[]}} ctx
+ * @param {object} config
+ */
+function validateTheme(ctx, config) {
+  if (config.theme === undefined) return;
+  if (!isInArray(VALID_THEMES, config.theme)) {
+    ctx.warnings.push(`theme "${config.theme}" is not one of: ${VALID_THEMES.join(', ')}`);
+  }
+}
+
+/**
+ * @param {{errors:string[], warnings:string[]}} ctx
+ * @param {object} config
+ */
+function validateRoutingMode(ctx, config) {
+  if (config.routingMode === undefined) return;
+  if (!isInArray(VALID_ROUTING_MODES, config.routingMode)) {
+    ctx.errors.push(`routingMode "${config.routingMode}" is not one of: ${VALID_ROUTING_MODES.join(', ')}`);
+  }
+}
+
+/**
+ * @param {{errors:string[], warnings:string[]}} ctx
+ * @param {object} config
+ */
+function validateDomain(ctx, config) {
+  if (config.domain === undefined) return;
+  if (typeof config.domain !== 'string') {
+    ctx.errors.push('domain must be a string');
+  } else if (config.domain && !/^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/i.test(config.domain)) {
+    ctx.warnings.push(`domain "${config.domain}" may not be a valid domain name`);
+  }
+}
+
+/**
+ * @param {{warnings:string[]}} ctx
+ * @param {object} config
+ */
+function validateKnownKeys(ctx, config) {
+  for (const key of Object.keys(config)) {
+    if (!isInArray(KNOWN_KEYS, key)) {
+      ctx.warnings.push(`Unknown config key "${key}" — possible typo?`);
+    }
+  }
+}
+
 /**
 * Validate a config object and return errors/warnings.
 * @param {object} config - The config object to validate
@@ -17,123 +166,20 @@ const VALID_TIMEZONES_SAMPLE = [
 function validateConfig(config) {
  const errors = [];
  const warnings = [];
+  const ctx = { errors, warnings };

  if (!config || typeof config !== 'object') {
    return { valid: false, errors: ['Config must be a non-null object'], warnings };
  }

-  // TLD validation
-  if (config.tld !== undefined) {
-    if (typeof config.tld !== 'string') {
-      errors.push('tld must be a string');
-    } else {
-      const tld = config.tld.startsWith('.') ? config.tld : '.' + config.tld;
-      if (!/^\.[a-z0-9][a-z0-9-]*$/.test(tld)) {
-        errors.push(`tld "${config.tld}" contains invalid characters (use lowercase alphanumeric)`);
-      }
-      if (tld.length > 20) {
-        warnings.push(`tld "${config.tld}" is unusually long`);
-      }
-    }
-  }
-
-  // DNS config validation
-  if (config.dns !== undefined) {
-    if (typeof config.dns !== 'object' || config.dns === null) {
-      errors.push('dns must be an object');
-    } else {
-      if (config.dns.ip !== undefined && typeof config.dns.ip !== 'string') {
-        errors.push('dns.ip must be a string');
-      }
-      if (config.dns.ip && !/^[\d.]+$/.test(config.dns.ip) && !/^[a-zA-Z0-9.-]+$/.test(config.dns.ip)) {
-        errors.push(`dns.ip "${config.dns.ip}" is not a valid IP address or hostname`);
-      }
-      if (config.dns.port !== undefined) {
-        const port = parseInt(config.dns.port, 10);
-        if (isNaN(port) || port < 1 || port > 65535) {
-          errors.push(`dns.port "${config.dns.port}" is not a valid port number (1-65535)`);
-        }
-      }
-      if (config.dns.servers !== undefined) {
-        if (typeof config.dns.servers !== 'object' || config.dns.servers === null) {
-          errors.push('dns.servers must be an object');
-        }
-      }
-      // DNS provider validation
-      if (config.dns.provider !== undefined) {
-        const validProviders = ['technitium', 'cloudflare', 'rfc2136', 'manual'];
-        if (typeof config.dns.provider !== 'string') {
-          errors.push('dns.provider must be a string');
-        } else if (!validProviders.includes(config.dns.provider)) {
-          warnings.push(`dns.provider "${config.dns.provider}" is not one of: ${validProviders.join(', ')}. It may still work if a custom adapter is installed.`);
-        }
-      }
-    }
-  }
-
-  // Dashboard host validation
-  if (config.dashboardHost !== undefined) {
-    if (typeof config.dashboardHost !== 'string') {
-      errors.push('dashboardHost must be a string');
-    } else if (config.dashboardHost && !/^[a-zA-Z0-9][a-zA-Z0-9.-]*$/.test(config.dashboardHost)) {
-      errors.push(`dashboardHost "${config.dashboardHost}" contains invalid characters`);
-    }
-  }
-
-  // Timezone validation
-  if (config.timezone !== undefined) {
-    if (typeof config.timezone !== 'string') {
-      errors.push('timezone must be a string');
-    } else if (config.timezone) {
-      // Basic format check — full validation would require Intl API
-      try {
-        Intl.DateTimeFormat(undefined, { timeZone: config.timezone });
-      } catch {
-        errors.push(`timezone "${config.timezone}" is not a recognized IANA timezone`);
-      }
-    }
-  }
-
-  // Theme validation
-  if (config.theme !== undefined) {
-    const validThemes = ['dark', 'light', 'blue'];
-    if (!validThemes.includes(config.theme)) {
-      warnings.push(`theme "${config.theme}" is not one of: ${validThemes.join(', ')}`);
-    }
-  }
-
-  // Routing mode validation
-  if (config.routingMode !== undefined) {
-    const validModes = ['subdomain', 'subdirectory'];
-    if (!validModes.includes(config.routingMode)) {
-      errors.push(`routingMode "${config.routingMode}" is not one of: ${validModes.join(', ')}`);
-    }
-  }
-
-  // Domain validation
-  if (config.domain !== undefined) {
-    if (typeof config.domain !== 'string') {
-      errors.push('domain must be a string');
-    } else if (config.domain && !/^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/i.test(config.domain)) {
-      warnings.push(`domain "${config.domain}" may not be a valid domain name`);
-    }
-  }
-
-  // Warn on unknown top-level keys
-  const knownKeys = [
-    'tld', 'caName', 'dns', 'dnsServers', 'dashboardHost', 'timezone', 'theme',
-    'updatedAt', 'timestamp', 'logo', 'logoPosition', 'favicon', 'weather',
-    'setupComplete', 'setupCompleted', 'setupMode', 'onboardingCompleted',
-    'configurationType', 'defaults', 'customLogo', 'customFavicon',
-    'dashboardTitle', 'tailscale', 'license', 'skipped',
-    'routingMode', 'domain', 'email', 'defaultIP', 'pylon',
-    'customLogoDark', 'customLogoLight'
-  ];
-  for (const key of Object.keys(config)) {
-    if (!knownKeys.includes(key)) {
-      warnings.push(`Unknown config key "${key}" — possible typo?`);
-    }
-  }
+  validateTld(ctx, config);
+  validateDns(ctx, config);
+  validateDashboardHost(ctx, config);
+  validateTimezone(ctx, config);
+  validateTheme(ctx, config);
+  validateRoutingMode(ctx, config);
+  validateDomain(ctx, config);
+  validateKnownKeys(ctx, config);

  return { valid: errors.length === 0, errors, warnings };
 }
@@ -113,6 +113,41 @@ module.exports = function configureMiddleware(app, {
    next();
  });

+  // ── Tailscale authentication helpers ──
+
+  const PROBE_PATHS_TAILSCALE = new Set([
+    '/health', '/health/live', '/health/ready', '/healthz', '/readyz',
+  ]);
+
+  function isTailScaleProbePath(reqPath) {
+    return PROBE_PATHS_TAILSCALE.has(reqPath) || reqPath.startsWith('/probe/');
+  }
+
+  function extractTailscaleIPs(req) {
+    const clientIP = req.ip || req.socket?.remoteAddress || '';
+    const forwardedFor = req.headers['x-forwarded-for'];
+    const realIP = req.headers['x-real-ip'];
+    const ipsToCheck = [clientIP, forwardedFor, realIP].filter(Boolean);
+    const fromTailscale = ipsToCheck.some(ip =>
+      isTailscaleIP(ip.toString().split(',')[0].trim()));
+    const clientTailscaleIP = ipsToCheck
+      .map(ip => ip.toString().split(',')[0].trim())
+      .find(ip => isTailscaleIP(ip));
+    return { clientIP, ipsToCheck, fromTailscale, clientTailscaleIP };
+  }
+
+  async function isIPInTailnet(clientTailscaleIP) {
+    const status = await getTailscaleStatus();
+    if (!status) return true; // no status = can't verify = allow
+
+    const knownIPs = new Set();
+    for (const ip of (status.Self?.TailscaleIPs || [])) knownIPs.add(ip);
+    for (const peer of Object.values(status.Peer || {})) {
+      for (const ip of (peer.TailscaleIPs || [])) knownIPs.add(ip);
+    }
+    return knownIPs.has(clientTailscaleIP);
+  }
+
  // ── Tailscale authentication middleware (optional) ──
  const tailscaleAuthMiddleware = async (req, res, next) => {
    if (!tailscaleConfig.enabled || !tailscaleConfig.requireAuth) {
@@ -121,25 +156,11 @@ module.exports = function configureMiddleware(app, {

    // Probe endpoints bypass Tailscale auth — k8s/Docker healthchecks
    // don't carry a Tailscale identity header.
-    if (req.path === '/health'
-      || req.path === '/health/live'
-      || req.path === '/health/ready'
-      || req.path === '/healthz'
-      || req.path === '/readyz'
-      || req.path.startsWith('/probe/')) {
+    if (isTailScaleProbePath(req.path) || req.path.startsWith('/api/v1/tailscale/')) {
      return next();
    }

-    if (req.path.startsWith('/api/v1/tailscale/')) {
-      return next();
-    }
-
-    const clientIP = req.ip || req.socket?.remoteAddress || '';
-    const forwardedFor = req.headers['x-forwarded-for'];
-    const realIP = req.headers['x-real-ip'];
-
-    const ipsToCheck = [clientIP, forwardedFor, realIP].filter(Boolean);
-    const fromTailscale = ipsToCheck.some(ip => isTailscaleIP(ip.toString().split(',')[0].trim()));
+    const { clientIP, fromTailscale, clientTailscaleIP } = extractTailscaleIPs(req);

    if (!fromTailscale) {
      return errorResponse(res, 403, '[DC-120] Access denied. This dashboard requires Tailscale connection.', {
@@ -148,27 +169,14 @@ module.exports = function configureMiddleware(app, {
      });
    }

-    if (tailscaleConfig.allowedTailnet) {
+    if (tailscaleConfig.allowedTailnet && clientTailscaleIP) {
      try {
-        const status = await getTailscaleStatus();
-        if (status) {
-          const clientTailscaleIP = ipsToCheck
-            .map(ip => ip.toString().split(',')[0].trim())
-            .find(ip => isTailscaleIP(ip));
-
-          if (clientTailscaleIP) {
-            const knownIPs = new Set();
-            for (const ip of (status.Self?.TailscaleIPs || [])) knownIPs.add(ip);
-            for (const peer of Object.values(status.Peer || {})) {
-              for (const ip of (peer.TailscaleIPs || [])) knownIPs.add(ip);
-            }
-            if (!knownIPs.has(clientTailscaleIP)) {
-              return errorResponse(res, 403, '[DC-121] Access denied. Device not in allowed tailnet.', {
-                requiresTailscale: true,
-                clientIP
-              });
-            }
-          }
+        const inTailnet = await isIPInTailnet(clientTailscaleIP);
+        if (!inTailnet) {
+          return errorResponse(res, 403, '[DC-121] Access denied. Device not in allowed tailnet.', {
+            requiresTailscale: true,
+            clientIP
+          });
        }
      } catch (e) {
        log.warn('tailscale', 'Tailnet verification failed, allowing request', { error: e.message });
@@ -0,0 +1,195 @@
+/**
+ * Graceful shutdown coordinator — DashCaddy
+ *
+ * Extracts the SIGTERM/SIGINT handler from server.js into a testable,
+ * reusable module that:
+ *   1. Calls server.close() to drain in-flight HTTP connections
+ *   2. Stops each manager in a deterministic order
+ *   3. Emits a 'shutdown' event so additional listeners can do cleanup
+ *   4. Force-exits after a configurable drain timeout if connections don't drain
+ *   5. Is idempotent — a second SIGTERM during shutdown does not re-run handlers
+ *
+ * Spec: DC-067 (production-grade backlog). Docker sends SIGTERM on stop;
+ * without this coordinator, in-flight API calls drop.
+ *
+ * Exports:
+ *   - createShutdownCoordinator({ server, log, drainTimeoutMs, managers })
+ *       Returns an EventEmitter with: { shutdown, isShuttingDown, on, emit, ... }
+ *   - installSignalHandlers(coordinator, signals = ['SIGTERM', 'SIGINT'])
+ *       Registers the OS-level handlers. Idempotent.
+ */
+'use strict';
+
+const EventEmitter = require('events');
+
+const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
+
+class ShutdownCoordinator extends EventEmitter {
+  constructor({ server, log, drainTimeoutMs, managers }) {
+    super();
+    if (!server) throw new Error('createShutdownCoordinator: server is required');
+    if (!log || typeof log.info !== 'function' || typeof log.warn !== 'function'
+        || typeof log.error !== 'function') {
+      throw new Error('createShutdownCoordinator: log must have info(), warn(), and error() methods');
+    }
+    this.server = server;
+    this.log = log;
+    this.drainTimeoutMs = Number.isFinite(drainTimeoutMs) && drainTimeoutMs > 0
+      ? drainTimeoutMs
+      : DEFAULT_DRAIN_TIMEOUT_MS;
+    this.managers = Array.isArray(managers) ? managers : [];
+    this._shuttingDown = false;
+    this._forceTimer = null;
+  }
+
+  isShuttingDown() {
+    return this._shuttingDown;
+  }
+
+  async _stopManager(m) {
+    try {
+      await m.stop();
+      this.log.info('shutdown', `manager stopped: ${m.name}`);
+    } catch (err) {
+      this.log.warn('shutdown', `manager stop failed: ${m.name}`, { error: err.message });
+    }
+  }
+
+  /**
+   * Stop each manager sequentially in declaration order. Each manager's
+   * stop() is awaited so that a downstream manager is not stopped until
+   * its upstream dependency has finished draining.
+   *
+   * IMPORTANT: this runs AFTER server.close() returns (see shutdown()).
+   * We must wait for in-flight HTTP requests to complete before tearing
+   * down the services that serve them — otherwise those requests fail
+   * mid-drain with "service not found" / "monitor not running" errors.
+   */
+  async _stopManagersInOrder() {
+    for (const m of this.managers) {
+      await this._stopManager(m);
+    }
+  }
+
+  /**
+   * Emit an event but swallow listener exceptions so one bad listener
+   * can't abort the shutdown sequence. Logs each failure with the
+   * listener's name (set via `listener.name`) if available.
+   */
+  _safeEmit(event, ...args) {
+    const listeners = this.listeners(event);
+    for (const listener of listeners) {
+      try {
+        listener.apply(this, args);
+      } catch (err) {
+        const name = listener.name || '<anonymous>';
+        this.log.error('shutdown', `event listener for '${event}' threw`,
+          { listener: name, error: err.message });
+      }
+    }
+  }
+
+  shutdown(signal) {
+    if (this._shuttingDown) {
+      this.log.info('shutdown', `${signal || 'shutdown'} received — already shutting down, ignoring`);
+      return;
+    }
+    this._shuttingDown = true;
+    this.log.info('shutdown', `${signal || 'shutdown'} received, draining (timeout=${this.drainTimeoutMs}ms)...`);
+
+    // Emit 'shutdown' event first so any listeners can observe the signal
+    // before the drain begins. NOTE: listeners should NOT tear down their
+    // state here — that happens in the 'closed' event after server.close.
+    // _safeEmit swallows listener exceptions so a buggy listener can't
+    // abort the entire shutdown sequence.
+    this._safeEmit('shutdown', signal);
+
+    // Close the HTTP server FIRST. Stops accepting new connections, waits
+    // for in-flight requests to complete naturally. Only AFTER close fires
+    // do we tear down managers — otherwise in-flight requests could fail
+    // when the services they call have already been stopped.
+    let serverClosed = false;
+    let managersStopped = false;
+    try {
+      this.server.close(async () => {
+        serverClosed = true;
+        this.log.info('shutdown', 'HTTP server closed cleanly');
+        // Now that in-flight requests are done, stop managers in order.
+        // We do NOT clear the force-exit timer yet — if a manager's stop()
+        // hangs, the timer is the safety net that prevents the process
+        // from living forever in a half-shut-down state.
+        try {
+          await this._stopManagersInOrder();
+        } catch (err) {
+          // _stopManager already logs per-manager failures, but a top-level
+          // throw (e.g. from the for-loop itself) is still possible.
+          this.log.error('shutdown', 'manager shutdown loop threw', { error: err.message });
+        }
+        managersStopped = true;
+        // Manager drain complete — NOW we can clear the safety timer.
+        if (this._forceTimer) {
+          clearTimeout(this._forceTimer);
+          this._forceTimer = null;
+        }
+        this._safeEmit('closed', signal);
+        process.exit(0);
+      });
+    } catch (err) {
+      this.log.error('shutdown', 'server.close threw', { error: err.message });
+    }
+
+    // Force-exit safety net. Fires when EITHER:
+    //   (a) server.close never fires (HTTP server stuck draining), or
+    //   (b) server.close fired but managers hung during stop()
+    // We only suppress when managersStopped === true (full drain complete).
+    // serverClosed alone is NOT enough — managers could still be running.
+    this._forceTimer = setTimeout(() => {
+      if (managersStopped) return;  // full shutdown complete
+      if (!serverClosed) {
+        this.log.warn('shutdown', `drain timeout (${this.drainTimeoutMs}ms) reached before HTTP server closed, force-exiting`);
+      } else {
+        this.log.warn('shutdown', `drain timeout (${this.drainTimeoutMs}ms) reached after HTTP close (manager hung), force-exiting`);
+      }
+      process.exit(0);
+    }, this.drainTimeoutMs);
+    if (this._forceTimer && typeof this._forceTimer.unref === 'function') {
+      this._forceTimer.unref();
+    }
+  }
+}
+
+function createShutdownCoordinator(opts) {
+  return new ShutdownCoordinator(opts);
+}
+
+/**
+ * Install OS-level signal handlers. Idempotent: second call for the same
+ * signal does NOT register a duplicate listener. Tracks registered signals
+ * on the coordinator itself so a future caller can introspect.
+ *
+ * @param {ShutdownCoordinator} coordinator
+ * @param {string[]} signals - signals to handle (default: SIGTERM, SIGINT)
+ */
+function installSignalHandlers(coordinator, signals) {
+  if (!coordinator || typeof coordinator.shutdown !== 'function') {
+    throw new Error('installSignalHandlers: coordinator required');
+  }
+  if (!Array.isArray(coordinator._installedSignals)) {
+    coordinator._installedSignals = [];
+  }
+  const sigs = Array.isArray(signals) && signals.length > 0
+    ? signals
+    : ['SIGTERM', 'SIGINT'];
+  for (const sig of sigs) {
+    if (coordinator._installedSignals.includes(sig)) continue;
+    process.on(sig, () => coordinator.shutdown(sig));
+    coordinator._installedSignals.push(sig);
+  }
+}
+
+module.exports = {
+  createShutdownCoordinator,
+  installSignalHandlers,
+  DEFAULT_DRAIN_TIMEOUT_MS,
+  ShutdownCoordinator,  // exported for tests
+};
@@ -9,10 +9,11 @@
 *
 * Priority:
 *   1. internet → https://www.google.com
- *   2. isExternal + externalUrl → use as-is
- *   3. service.url → prepend https:// if no protocol
- *   4. dnsServers config → http://{ip}:{port}
- *   5. fallback → buildServiceUrl(id)
+ *   2. healthCheckUrl → use as-is (bypass SSO/Caddy for direct container health checks)
+ *   3. isExternal + externalUrl → use as-is
+ *   4. service.url → prepend https:// if no protocol
+ *   5. dnsServers config → http://{ip}:{port}
+ *   6. fallback → buildServiceUrl(id)
 *
 * @param {string} id - service identifier
 * @param {Object|null} service - service object from services.json (may be null for top-card services)
@@ -22,6 +23,7 @@
 */
 function resolveServiceUrl(id, service, siteConfig, buildServiceUrl) {
  if (id === 'internet') return 'https://www.google.com';
+  if (service?.healthCheckUrl) return service.healthCheckUrl;
  if (service?.isExternal && service.externalUrl) return service.externalUrl;
  if (service?.url) return service.url.startsWith('http') ? service.url : `https://${service.url}`;
  const dnsServer = siteConfig?.dnsServers?.[id];
@@ -835,6 +835,22 @@ start_caddy() {
  fi
 }

+# DC-037: Make API source reachable from both the install path
+# (${SITES_DIR}/dashcaddy-api, where this installer writes files) and the
+# /opt/dashcaddy/dashcaddy-api path that the auto-updater and several runtime
+# helpers default to. Without this, a first auto-update lands on a fresh host
+# that wrote its API files to ${SITES_DIR}/dashcaddy-api but tried to read
+# from /opt/dashcaddy/dashcaddy-api and crashes with
+# `cp: cannot create directory '/etc/dashcaddy/sites/dashcaddy-api/routes':
+# No such file or directory` because the trailing parent path is missing.
+# `ln -sfn` is idempotent (safe on re-runs; does not fail if the link already
+# points to the same target) and replaces any stale link.
+install_api_symlink() {
+  mkdir -p /opt/dashcaddy
+  ln -sfn "${API_DIR}" /opt/dashcaddy/dashcaddy-api
+  ok "API symlink: /opt/dashcaddy/dashcaddy-api -> ${API_DIR}"
+}
+
 # ============================================================================
 # Firewall
 # ============================================================================
@@ -1091,6 +1107,7 @@ main() {
  # ---- Step 7: Start Caddy ----
  step "Starting web server"
  start_caddy
+  install_api_symlink

  print_success "$(elapsed "$start_time")"
 }
@@ -0,0 +1,65 @@
+#!/bin/bash
+# DashCaddy Docker Space Management
+# Runs via cron to keep Docker disk usage under control
+# Prevents the overlay2 + dangling volumes + stale images that fill the disk
+
+set -euo pipefail
+
+MAX_DISK_PCT=85  # Alert if disk usage exceeds this
+LOG_PREFIX="[dc-disk]"
+
+# 1. Remove dangling (untagged) images
+echo "$LOG_PREFIX Pruning dangling images..."
+docker image prune -f --filter "dangling=true" 2>/dev/null || true
+
+# 2. Remove unused volumes (volumes not attached to any container)
+echo "$LOG_PREFIX Pruning unused volumes..."
+docker volume prune -f 2>/dev/null || true
+
+# 3. Remove old build cache
+echo "$LOG_PREFIX Pruning build cache..."
+docker builder prune -f --keep-storage 500m 2>/dev/null || true
+
+# 4. Remove stopped containers older than 7 days
+echo "$LOG_PREFIX Pruning old stopped containers..."
+docker container prune -f --filter "until=168h" 2>/dev/null || true
+
+# 5. Remove images not used by any container (keep only running images)
+# Only remove images older than 7 days to avoid breaking recent updates
+echo "$LOG_PREFIX Pruning unused images (>7 days old)..."
+docker image prune -a -f --filter "until=168h" --filter "dangling=false" 2>/dev/null || true
+
+# 6. Truncate container log files that are bigger than 100MB
+echo "$LOG_PREFIX Checking container logs..."
+for logfile in /var/lib/docker/containers/*/*-json.log; do
+  if [ -f "$logfile" ]; then
+    size=$(stat -c%s "$logfile" 2>/dev/null || echo 0)
+    if [ "$size" -gt 104857600 ]; then  # 100MB
+      echo "$LOG_PREFIX Truncating $(basename $logfile) ($(( size / 1048576 ))MB)"
+      truncate -s 0 "$logfile"
+    fi
+  fi
+done
+
+# 7. Vacuum journald logs to 200MB
+echo "$LOG_PREFIX Vacuuming journal logs..."
+journalctl --vacuum-size=200M 2>/dev/null || true
+
+# 8. Clear pip/npm caches that grow over time
+echo "$LOG_PREFIX Clearing stale caches..."
+rm -rf /root/.cache/pip/cache/html 2>/dev/null || true
+rm -rf /root/.cache/npm/_cacache 2>/dev/null || true
+
+# 9. Report disk usage
+USAGE=$(df / | tail -1 | awk '{print $5}' | tr -d '%')
+FREE_GB=$(df -h / | tail -1 | awk '{print $4}')
+echo "$LOG_PREFIX Disk usage: ${USAGE}% (${FREE_GB} free)"
+
+if [ "$USAGE" -gt "$MAX_DISK_PCT" ]; then
+  echo "$LOG_PREFIX WARNING: Disk usage above ${MAX_DISK_PCT}%!"
+  # More aggressive: remove ALL images not used by running containers
+  echo "$LOG_PREFIX Aggressive prune: removing all unused images..."
+  docker image prune -a -f 2>/dev/null || true
+fi
+
+echo "$LOG_PREFIX Done."
Author	SHA1	Message	Date
Hermes	1528fd1a35	DC-067: [WIP] jest failing at grade time	2026-08-12 07:24:29 -07:00
hermes	432e9635bc	DC-067: fix force-exit + listener exception handling per Codex D-grade feedback - Force-exit timer now distinguishes serverClosed from managersStopped. Was: if (closed) return → suppressed timer when manager hung after server.close fired (the original bug). Now: if (managersStopped) return → timer fires only when full drain (HTTP close + all managers stopped) completes before the deadline. - Added _safeEmit() helper that wraps this.emit() so a buggy listener throwing during 'shutdown' or 'closed' doesn't abort the shutdown sequence. Each failed listener is logged via the structured logger. - Added 4 new tests covering: hung manager after HTTP close, throwing shutdown listener, throwing closed listener, and the fast-drain happy path that clears the timer cleanly.	2026-08-12 03:59:11 -07:00
hermes	5b74536472	DC-067: harden shutdown per Codex C-grade feedback - Logger validation now requires info/warn/error (was info-only) - Force-exit timer now survives manager stop drain so a hung manager cannot trap the process in half-shutdown - installSignalHandlers is now actually idempotent — tracks installed signals on coordinator and skips duplicates	2026-08-12 03:52:34 -07:00
hermes	bb01a77ae7	DC-067: fix shutdown sequencing — stop managers AFTER server.close drains Codex grade D flagged two real defects: 1. Managers were stopped before HTTP server finished draining, so in-flight requests could fail when their backing services were already down. 2. _stopManager() promises weren't awaited, contradicting the documented 'declaration order' claim for async stop methods. Fix: server.close callback now awaits _stopManagersInOrder() before exiting. The 'shutdown' event fires first (so listeners can observe the signal); the 'closed' event fires after all managers are stopped.	2026-08-12 03:46:42 -07:00
hermes	88ff260e5e	DC-067: graceful shutdown coordinator (EventEmitter, 10s drain, idempotent)	2026-08-12 03:36:49 -07:00
Hermes	ff81d99021	DC-101: Disk Space Monitor + Product Vision CI / Test & Lint (push) Canceled after 0s Details CI / Security audit (push) Canceled after 0s Details Backend: - src/monitoring/disk-space-monitor.js: monitors Docker disk usage against user-configured budget, auto-cleans at thresholds, breaks down by category - routes/disk-space.js: GET /disk, GET /disk/breakdown, POST /disk/config, POST /disk/cleanup endpoints - src/app.js: wire DiskSpaceMonitor into startup, 10-min check interval - All 1539 tests pass Product Vision (PRODUCT-VISION.md): - DashCaddy is a self-hosting platform, not just a dashboard - Core value: 'Self-host anything in 30 seconds' - Three pillars: One-click deploy, zero-config networking, self-healing infra - vs Portainer/CasaOS/Yunohost positioning New backlog tasks (P5 tier, DC-101–108): - Disk budget, one-click deploy with auto Caddyfile+DNS, container auto-discovery, app catalog, smart wizard, visual Caddy builder, disaster recovery, multi-host fleet management 47 total backlog tasks, ~110 hr of work, cron running every 2h.	2026-08-12 02:41:40 -07:00
Hermes	5c02bfba1d	DC-084/085/089/090: Quick wins batch CI / Test & Lint (push) Canceled after 0s Details CI / Security audit (push) Canceled after 0s Details DC-084: Add .dockerignore (excludes __tests__/, .git/, node_modules/, coverage/) DC-085: Replace Math.random() with crypto.randomUUID()/crypto.randomBytes() for IDs DC-089: Add dedicated rate limiter on POST /license/activate (10 attempts/15min) DC-090: Pin Node.js to 20.11.1-alpine3.19 + add engines field to package.json All 1539 tests pass. ESLint: 0 errors.	2026-08-12 02:24:28 -07:00
Hermes	bb20f02cbf	Expand production backlog: 19 → 39 tasks (DC-081–DC-100) CI / Test & Lint (push) Canceled after 0s Details CI / Security audit (push) Canceled after 0s Details Deep audit additions: P2.5 Security: route validation gap (151/160 unvalidated), cmd injection surface in ca.js, 30 untested source files, no .dockerignore, Math.random IDs P3.5 Ops: error codes, SDK/types, log rotation, license rate limit, Node version pin, Dependabot, dependency health checks, workflow retry, audit trail P4 Advanced: multi-user RBAC, API keys, Prometheus/Grafana, changelog, migration system, service auto-discovery	2026-08-12 02:13:55 -07:00
Hermes	dc788e5dd3	DC-061: healthCheckUrl override + v2 production-grade backlog CI / Test & Lint (push) Canceled after 0s Details CI / Security audit (push) Canceled after 0s Details - url-resolver.js: add healthCheckUrl priority (bypasses SSO for health checks) - DC-PRODUCTION-GRADE-BACKLOG.md: v2 backlog with 19 tasks (DC-062–DC-080) based on full codebase audit: 1539 tests, 86.55% coverage, 0 ESLint errors v2 backlog replaces completed v1 (P0-1 through P2-7 all done). New priorities: P0: OpenAPI spec update, branch coverage gap, Dockerfile resource limits P1: Console sweep remainder, billing E2E test, graceful shutdown, lint sweep, health notification spam P2: CI/CD pipeline, Sentry, source maps, request logging, multi-stage Docker, health endpoint P3: WebSocket, i18n, config backup/restore, mobile, plugin system	2026-08-12 02:05:08 -07:00
Hermes	04f90d1505	DC-061: Add healthCheckUrl override to URL resolver CI / Test & Lint (push) Canceled after 0s Details CI / Security audit (push) Canceled after 0s Details Services behind SSO auth gates (like Seerr) would fail health checks because the health checker hit the Caddy auth-gated URL and got redirected to login instead of reaching the service. The healthCheckUrl field in services.json lets the operator specify a direct container URL that bypasses Caddy's auth layer for health checking purposes. Priority order in resolveServiceUrl(): 1. internet → fixed google.com 2. healthCheckUrl → direct container URL (NEW) 3. isExternal + externalUrl 4. service.url 5. dnsServers config 6. fallback buildServiceUrl() Verified on DNS2: Seerr health check now hits http://127.0.0.1:5055 directly instead of https://requests.sami through the SSO gate.	2026-08-12 01:52:37 -07:00
Krystie	bd13104362	DC-037: install.sh creates /opt/dashcaddy/dashcaddy-api -> /etc/dashcaddy/sites/dashcaddy-api symlink CI / Test & Lint (push) Has been cancelled Details CI / Security audit (push) Has been cancelled Details	2026-08-11 05:27:54 -07:00
Hermes	dcf252e515	P2-5 through P2-7: mark done — all backlog items complete CI / Test & Lint (push) Has been cancelled Details CI / Security audit (push) Has been cancelled Details	2026-08-10 21:19:43 -07:00
Hermes	a7512b4a56	[grade=A] P2-7: refactor tailscaleAuthMiddleware (complexity 24→7, nesting 6→3) Extracted 3 helpers from the monolithic tailscaleAuthMiddleware: - isTailScaleProbePath(): probe-path bypass check (was 6 \|\| chains) - extractTailscaleIPs(): IP collection + Tailscale classification - isIPInTailnet(): async tailnet membership verification Middleware is now a flat 15-line function that reads top-to-bottom. Probe paths extracted to a Set for O(1) lookup. Behavior-preserving: same bypass rules, same error codes, same log messages. ESLint complexity 24→7, max-depth 6→3. 1539/1539 tests pass.	2026-08-10 21:19:28 -07:00
Hermes	f5fc688185	[grade=A] P2-6: refactor config-schema.js validateConfig (complexity 44→8 sub-validators) Extracted 8 field-level validators from the monolithic validateConfig function: validateTld, validateDns, validateDashboardHost, validateTimezone, validateTheme, validateRoutingMode, validateDomain, validateKnownKeys. ESLint complexity dropped from 44 (Error) to <10 per function. Removed unused VALID_TIMEZONES_SAMPLE constant. Extracted VALID_THEMES, VALID_ROUTING_MODES, VALID_DNS_PROVIDERS, KNOWN_KEYS as module-level constants. Behavior-preserving: same validation rules, same error/warning messages, same return shape. 1539/1539 tests pass. ESLint: 0 problems (was 2).	2026-08-10 21:18:09 -07:00
Hermes	1bc41bb2bc	[grade=A] P2-5: fix 4 test handle leaks in log-digest.js + sweep remaining console calls Root cause: setTimeout in start() (line 74) created an initial-collection timer that was never stored in an instance property, so stop() could not clear it. Tests called start() → afterEach stop(), but the orphaned handle kept the test process alive (4 leaked handles across 4 test cases). Fix: store as this._initialTimeout, clear in stop() alongside digestTimeout. Also replaced 3 remaining console.error calls in log-digest.js with structured log.error tagged 'logdigest' (was missed in P1-8 sweep). 1539/1539 tests pass. 0 open handles (--detectOpenHandles clean).	2026-08-10 21:16:22 -07:00