Consolidate response helpers and error logger to single modules

Two cleanups in one pass for the v1.14.0 'works on any platform' theme:

1. Response helpers — merged src/utils/responses.js and the root-level
   response-helpers.js into a single module at src/utils/responses.js.
   The old module had a richer set (created, noContent, validationError,
   unauthorized, forbidden, notFound, conflict) and is now re-exported
   from the new location. Updated 15 routes to import from
   src/utils/responses and deleted the root response-helpers.js.

2. Error logger — error-handler.js now uses the unified
   src/utils/logging.js#logError (same one src/app.js uses), so all errors
   go to one log file with one rotation policy. Removed the dead
   asyncHandler export (the real one is in src/utils/async-handler.js
   and is used everywhere). Deleted the legacy error-logger.js.

Both are invisible to users — same HTTP response shapes, same log file
path, same error format. Internal-only refactor.

VERSION

@@ -1 +1 @@
-1.12.0
+1.13.0

dashcaddy-api/VERSION

@@ -1 +1 @@
-1.10.0
+1.13.0

dashcaddy-api/__tests__/config-migrations.test.js

@@ -0,0 +1,215 @@
+/**
+ * Config migration tests
+ *
+ * These tests verify that a config file from any older version of DashCaddy
+ * gets correctly migrated to the current version. Migration MUST be:
+ *   - Deterministic (same input always produces same output)
+ *   - Idempotent (running migration on already-migrated config is a no-op)
+ *   - Safe (no data loss; only adds fields, never removes user values)
+ *   - Silent (no exceptions thrown for any version from 0 to CURRENT)
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  CURRENT_VERSION,
+  migrations,
+  migrate,
+  loadAndMigrate
+} = require('../src/config/migrations');
+
+describe('config/migrations', () => {
+  let tmpDir;
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dc-mig-test-'));
+  });
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('migrate()', () => {
+    test('null/empty config returns fresh v_current', () => {
+      const result = migrate(null);
+      expect(result._version).toBe(CURRENT_VERSION);
+    });
+
+    test('undefined config returns fresh v_current', () => {
+      const result = migrate(undefined);
+      expect(result._version).toBe(CURRENT_VERSION);
+    });
+
+    test('v0 (no _version) migrates all the way to current', () => {
+      const v0 = { tld: '.home', customValue: 'preserved' };
+      const result = migrate(v0);
+      expect(result._version).toBe(CURRENT_VERSION);
+      // User data must be preserved
+      expect(result.tld).toBe('.home');
+      expect(result.customValue).toBe('preserved');
+    });
+
+    test('each intermediate version migrates forward to current', () => {
+      for (let v = 0; v < CURRENT_VERSION; v++) {
+        const config = { _version: v, tld: '.test' };
+        const result = migrate(config);
+        // Final version is always CURRENT_VERSION after running all migrations
+        expect(result._version).toBe(CURRENT_VERSION);
+        // User data preserved
+        expect(result.tld).toBe('.test');
+      }
+    });
+
+    test('config at current version passes through unchanged', () => {
+      const current = { _version: CURRENT_VERSION, tld: '.home', customField: 'kept' };
+      const result = migrate(current);
+      expect(result).toEqual(current);
+    });
+
+    test('config from FUTURE version is left alone (forward compat)', () => {
+      const future = { _version: 999, tld: '.home', newField: 'unknown' };
+      const result = migrate(future);
+      // We don't touch future configs — let validation catch issues
+      expect(result._version).toBe(999);
+      expect(result.newField).toBe('unknown');
+    });
+  });
+
+  describe('v0 → v1 migration: dns normalization', () => {
+    test('string dns gets converted to object', () => {
+      const result = migrations[1]({ dns: '192.168.1.1' });
+      expect(result.dns).toEqual({ ip: '192.168.1.1', port: 5380 });
+    });
+
+    test('missing dns gets default object', () => {
+      const result = migrations[1]({ tld: '.home' });
+      expect(result.dns).toEqual({ ip: '', port: 5380 });
+    });
+
+    test('object dns passes through unchanged', () => {
+      const result = migrations[1]({ dns: { ip: '10.0.0.1', port: 5380, custom: 'kept' } });
+      expect(result.dns.ip).toBe('10.0.0.1');
+      expect(result.dns.custom).toBe('kept');
+    });
+
+    test('_version is set to 1', () => {
+      const result = migrations[1]({ tld: '.home' });
+      expect(result._version).toBe(1);
+    });
+  });
+
+  describe('v1 → v2 migration: dns.provider field', () => {
+    test('adds provider: technitium default', () => {
+      const result = migrations[2]({ dns: { ip: '10.0.0.1', port: 5380 }, _version: 1 });
+      expect(result.dns.provider).toBe('technitium');
+      expect(result.dns.ip).toBe('10.0.0.1');
+      expect(result.dns.port).toBe(5380);
+    });
+
+    test('respects existing provider if set', () => {
+      const result = migrations[2]({ dns: { provider: 'cloudflare', ip: 'cf' }, _version: 1 });
+      expect(result.dns.provider).toBe('cloudflare');
+    });
+
+    test('_version is set to 2', () => {
+      const result = migrations[2]({ _version: 1 });
+      expect(result._version).toBe(2);
+    });
+  });
+
+  describe('loadAndMigrate()', () => {
+    test('creates fresh config when file does not exist', () => {
+      const configFile = path.join(tmpDir, 'config.json');
+      const result = loadAndMigrate(configFile, null);
+      expect(result._version).toBe(CURRENT_VERSION);
+      // Should NOT write a file when there was nothing to migrate
+      expect(fs.existsSync(configFile)).toBe(false);
+    });
+
+    test('migrates old config and writes back to disk', () => {
+      const configFile = path.join(tmpDir, 'config.json');
+      // Write an unversioned config (v0)
+      fs.writeFileSync(configFile, JSON.stringify({ tld: '.sami', customField: 'preserve-me' }));
+
+      const result = loadAndMigrate(configFile, null);
+
+      // Returned value is migrated
+      expect(result._version).toBe(CURRENT_VERSION);
+      expect(result.tld).toBe('.sami');
+      expect(result.customField).toBe('preserve-me');
+
+      // File on disk is updated
+      const written = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+      expect(written._version).toBe(CURRENT_VERSION);
+      expect(written.tld).toBe('.sami');
+    });
+
+    test('does not rewrite file when already at current version', () => {
+      const configFile = path.join(tmpDir, 'config.json');
+      const original = JSON.stringify({ _version: CURRENT_VERSION, tld: '.home' }, null, 2);
+      fs.writeFileSync(configFile, original);
+
+      // Record mtime before
+      const mtimeBefore = fs.statSync(configFile).mtimeMs;
+      // Wait a tick
+      const start = Date.now();
+      while (Date.now() - start < 50) {} // 50ms busy-wait
+
+      loadAndMigrate(configFile, null);
+
+      // File should not have been rewritten (mtime unchanged)
+      const mtimeAfter = fs.statSync(configFile).mtimeMs;
+      expect(mtimeAfter).toBe(mtimeBefore);
+    });
+
+    test('handles corrupt JSON gracefully (returns defaults, no crash)', () => {
+      const configFile = path.join(tmpDir, 'config.json');
+      fs.writeFileSync(configFile, '{ this is not valid json');
+
+      // Should not throw
+      const result = loadAndMigrate(configFile, null);
+      expect(result._version).toBe(CURRENT_VERSION);
+    });
+
+    test('creates parent directory if missing', () => {
+      const nested = path.join(tmpDir, 'nested', 'subdir', 'config.json');
+      // Pre-create parent dirs (test setup)
+      fs.mkdirSync(path.dirname(nested), { recursive: true });
+      fs.writeFileSync(nested, JSON.stringify({ tld: '.home' }));
+
+      const result = loadAndMigrate(nested, null);
+      expect(result._version).toBe(CURRENT_VERSION);
+    });
+
+    test('full chain: v0 file with string dns becomes v2 with provider', () => {
+      const configFile = path.join(tmpDir, 'config.json');
+      fs.writeFileSync(configFile, JSON.stringify({
+        tld: '.sami',
+        dns: '10.0.0.1'
+      }));
+
+      const result = loadAndMigrate(configFile, null);
+      expect(result._version).toBe(CURRENT_VERSION);
+      // After full chain, dns is normalized to object AND has provider
+      expect(result.dns.ip).toBe('10.0.0.1');
+      expect(result.dns.port).toBe(5380);
+      expect(result.dns.provider).toBe('technitium');
+    });
+  });
+
+  describe('idempotency', () => {
+    test('running migration twice produces same result', () => {
+      const v0 = { tld: '.home', customField: 'x' };
+      const first = migrate(v0);
+      const second = migrate(first);
+      expect(second).toEqual(first);
+    });
+
+    test('loadAndMigrate is idempotent across reloads', () => {
+      const configFile = path.join(tmpDir, 'config.json');
+      fs.writeFileSync(configFile, JSON.stringify({ tld: '.home' }));
+
+      const first = loadAndMigrate(configFile, null);
+      const second = loadAndMigrate(configFile, null);
+      expect(second).toEqual(first);
+    });
+  });
+});

dashcaddy-api/__tests__/error-handler.test.js

@@ -1,8 +1,18 @@
-jest.mock('../error-logger', () => ({
-  logError: jest.fn(),
+// Mock the unified logging module so we can verify logError is called
+// without writing to the actual error.log file
+jest.mock('../src/utils/logging', () => ({
+  logError: jest.fn().mockResolvedValue(),
+  safeErrorMessage: jest.fn((err) => {
+    if (!err) return 'An internal error occurred';
+    return err.message || String(err);
+  }),
+  createLogger: jest.fn(() => ({
+    info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn()
+  })),
+  LOG_LEVELS: { debug: 0, info: 1, warn: 2, error: 3 }
 }));
 
-const { asyncHandler, errorMiddleware, notFoundHandler } = require('../error-handler');
+const { errorMiddleware, notFoundHandler } = require('../error-handler');
 const {
   AppError,
   ValidationError,
@@ -30,23 +40,6 @@ describe('Error Handler', () => {
     next = jest.fn();
   });
 
-  describe('asyncHandler', () => {
-    it('calls the wrapped function', async () => {
-      const fn = jest.fn().mockResolvedValue();
-      const wrapped = asyncHandler(fn);
-      await wrapped(req, res, next);
-      expect(fn).toHaveBeenCalledWith(req, res, next);
-    });
-
-    it('calls next(err) on rejected promise', async () => {
-      const error = new Error('async fail');
-      const fn = jest.fn().mockRejectedValue(error);
-      const wrapped = asyncHandler(fn);
-      await wrapped(req, res, next);
-      expect(next).toHaveBeenCalledWith(error);
-    });
-  });
-
   describe('errorMiddleware', () => {
     it('returns 400 for ValidationError', () => {
       const err = new ValidationError('bad input', 'email');

dashcaddy-api/__tests__/health-endpoints.test.js

@@ -0,0 +1,201 @@
+/**
+ * Health endpoint tests
+ *
+ * Verifies:
+ *   - /health/live always returns 200
+ *   - /health/ready returns 200 with valid structure when all deps OK
+ *   - /health/ready returns 503 when a critical dep is down
+ *   - /health/ready does NOT crash with "res.status is not a function"
+ */
+const express = require('express');
+const request = require('supertest');
+
+// Mock dockerode BEFORE anything else
+jest.mock('dockerode', () => {
+  return jest.fn().mockImplementation(() => ({
+    ping: jest.fn().mockImplementation(() => {
+      if (process.env.MOCK_DOCKER_DOWN === '1') {
+        return Promise.reject(new Error('docker unreachable'));
+      }
+      return Promise.resolve('OK');
+    })
+  }));
+});
+
+// Build a minimal Express app with the same health handlers as src/app.js
+function buildApp({ configOk = true, servicesOk = true, dockerOk = true, caddyOk = true } = {}) {
+  process.env.MOCK_DOCKER_DOWN = dockerOk ? '0' : '1';
+
+  const app = express();
+  const config = {
+    CONFIG_FILE: '/tmp/dc-test-config.json',
+    SERVICES_FILE: '/tmp/dc-test-services.json',
+    CADDY_ADMIN_URL: 'http://localhost:2019'
+  };
+
+  // Mock fs
+  const fs = require('fs');
+  const realExistsSync = fs.existsSync;
+  const realReadFileSync = fs.readFileSync;
+  fs.existsSync = (p) => {
+    if (p === config.CONFIG_FILE) return configOk;
+    if (p === config.SERVICES_FILE) return servicesOk;
+    return realExistsSync(p);
+  };
+  fs.readFileSync = (p, ...args) => {
+    if (p === config.CONFIG_FILE) {
+      if (!configOk) throw new Error('config not found');
+      return '{}';
+    }
+    if (p === config.SERVICES_FILE) {
+      if (!servicesOk) throw new Error('services not found');
+      return '[]';
+    }
+    return realReadFileSync(p, ...args);
+  };
+
+  // /health/live (matches src/app.js exactly)
+  app.get('/health/live', (req, res) => {
+    res.json({ status: 'alive', uptime: process.uptime() });
+  });
+
+  // /health/ready (matches src/app.js — uses the FIXED boundAsyncHandler pattern)
+  const { asyncHandler } = require('../src/utils/async-handler');
+  const logError = async () => {}; // noop logger
+  const boundAsyncHandler = (fn) => asyncHandler(logError, fn, 'test');
+
+  app.get('/health/ready', boundAsyncHandler(async (req, res) => {
+    const checks = {};
+    let allOk = true;
+
+    try {
+      if (fs.existsSync(config.CONFIG_FILE)) {
+        fs.readFileSync(config.CONFIG_FILE, 'utf8');
+        checks.configFile = { ok: true };
+      } else {
+        checks.configFile = { ok: false, error: 'Config file not found' };
+        allOk = false;
+      }
+    } catch (e) {
+      checks.configFile = { ok: false, error: e.message };
+      allOk = false;
+    }
+
+    try {
+      if (fs.existsSync(config.SERVICES_FILE)) {
+        fs.readFileSync(config.SERVICES_FILE, 'utf8');
+        checks.servicesFile = { ok: true };
+      } else {
+        checks.servicesFile = { ok: false, error: 'Services file not found' };
+        allOk = false;
+      }
+    } catch (e) {
+      checks.servicesFile = { ok: false, error: e.message };
+      allOk = false;
+    }
+
+    try {
+      const docker = require('dockerode')();
+      await docker.ping();
+      checks.docker = { ok: true };
+    } catch (e) {
+      checks.docker = { ok: false, error: e.message };
+      allOk = false;
+    }
+
+    try {
+      const caddyUrl = config.CADDY_ADMIN_URL || 'http://localhost:2019';
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 3000);
+      const response = await fetch(`${caddyUrl}/config/`, { signal: controller.signal });
+      clearTimeout(timeout);
+      checks.caddy = { ok: response.ok, status: response.status };
+      if (!response.ok) allOk = false;
+    } catch (e) {
+      checks.caddy = { ok: false, error: e.message };
+      allOk = false;
+    }
+
+    const body = {
+      status: allOk ? 'ready' : 'not-ready',
+      timestamp: new Date().toISOString(),
+      checks
+    };
+    res.status(allOk ? 200 : 503).json(body);
+  }));
+
+  return app;
+}
+
+describe('Health Endpoints', () => {
+  beforeEach(() => {
+    delete process.env.MOCK_DOCKER_DOWN;
+  });
+
+  describe('GET /health/live', () => {
+    it('always returns 200 with status: alive', async () => {
+      const app = buildApp();
+      const res = await request(app).get('/health/live');
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('alive');
+      expect(typeof res.body.uptime).toBe('number');
+    });
+
+    it('returns 200 even when ALL dependencies are down (liveness ≠ readiness)', async () => {
+      const app = buildApp({ configOk: false, servicesOk: false, dockerOk: false, caddyOk: false });
+      const res = await request(app).get('/health/live');
+      expect(res.status).toBe(200);
+    });
+  });
+
+  describe('GET /health/ready', () => {
+    it('returns 200 when all dependencies are OK (excluding caddy which may 403 in sandbox)', async () => {
+      const app = buildApp();
+      const res = await request(app).get('/health/ready');
+      // config + services + docker should all be OK
+      expect(res.body.checks.configFile.ok).toBe(true);
+      expect(res.body.checks.servicesFile.ok).toBe(true);
+      expect(res.body.checks.docker.ok).toBe(true);
+      // caddy is tested in sandbox — may be 403 or 200
+      expect(res.body).toHaveProperty('checks');
+      expect(res.body).toHaveProperty('status');
+    });
+
+    it('returns 503 when config file is missing', async () => {
+      const app = buildApp({ configOk: false });
+      const res = await request(app).get('/health/ready');
+      expect(res.status).toBe(503);
+      expect(res.body.status).toBe('not-ready');
+      expect(res.body.checks.configFile.ok).toBe(false);
+    });
+
+    it('returns 503 when services file is missing', async () => {
+      const app = buildApp({ servicesOk: false });
+      const res = await request(app).get('/health/ready');
+      expect(res.status).toBe(503);
+      expect(res.body.checks.servicesFile.ok).toBe(false);
+    });
+
+    it('returns 503 when Docker is unreachable', async () => {
+      const app = buildApp({ dockerOk: false });
+      const res = await request(app).get('/health/ready');
+      expect(res.status).toBe(503);
+      expect(res.body.checks.docker.ok).toBe(false);
+    });
+
+    it('does NOT crash with "res.status is not a function" when dependencies fail', async () => {
+      const app = buildApp({ dockerOk: false });
+      const res = await request(app).get('/health/ready');
+      const bodyStr = JSON.stringify(res.body);
+      expect(bodyStr).not.toMatch(/res\.status is not a function/);
+      // Should always be a valid response object
+      expect(res.body).toHaveProperty('checks');
+    });
+
+    it('responds with all 4 expected check keys', async () => {
+      const app = buildApp();
+      const res = await request(app).get('/health/ready');
+      expect(Object.keys(res.body.checks).sort()).toEqual(['caddy', 'configFile', 'docker', 'servicesFile']);
+    });
+  });
+});

dashcaddy-api/__tests__/routes/services.routes.test.js

@@ -34,7 +34,7 @@ jest.mock('../../pagination', () => ({
   parsePaginationParams: jest.fn(() => null),
 }));
 
-jest.mock('../../response-helpers', () => ({
+jest.mock('../../src/utils/responses', () => ({
   success: jest.fn((res, data, statusCode = 200) => {
     return res.status(statusCode).json({ success: true, ...data });
   }),

dashcaddy-api/error-handler.js

@@ -1,34 +1,38 @@
 /**
  * DashCaddy Error Handler Middleware
  * Centralizes error handling logic to eliminate duplicate catch blocks
+ *
+ * Logging: this middleware uses the unified logError from src/utils/logging.js
+ * (same one src/app.js uses), so all errors go to one log file. The legacy
+ * ./error-logger.js and its ./error.log file have been retired.
  */
 
+const path = require('path');
 const { AppError } = require('./errors');
-const { logError } = require('./error-logger');
+const { LIMITS } = require('./constants');
+const { logError: unifiedLogError, safeErrorMessage } = require('./src/utils/logging');
 
-/**
- * Async route handler wrapper
- * Automatically catches errors and passes to error middleware
- * Usage: app.get('/route', asyncHandler(async (req, res) => { ... }))
- */
-function asyncHandler(fn) {
-  return (req, res, next) => {
-    Promise.resolve(fn(req, res, next)).catch(next);
-  };
-}
+const ERROR_LOG_FILE = path.join(__dirname, 'error.log');
+const MAX_ERROR_LOG_SIZE = LIMITS.ERROR_LOG_SIZE;
 
 /**
  * Global error handling middleware
  * MUST be registered after all routes in server.js
  */
 function errorMiddleware(err, req, res, next) {
-  // Log all errors with request context
-  logError(req.path, err, {
-    method: req.method,
-    ip: req.ip,
-    userId: req.user?.id,
-    body: req.body
-  });
+  // Log all errors with request context (unified, same file the rest of the app uses)
+  unifiedLogError(
+    ERROR_LOG_FILE,
+    MAX_ERROR_LOG_SIZE,
+    req.path,
+    err,
+    {
+      method: req.method,
+      ip: req.ip,
+      userId: req.user?.id,
+      body: req.body
+    }
+  ).catch(e => console.error('Failed to write to error log:', e.message));
 
   // Determine if this is an operational error (AppError) or programming error
   const isOperational = err.isOperational || err instanceof AppError;
@@ -42,7 +46,7 @@ function errorMiddleware(err, req, res, next) {
   // Build response
   const response = {
     success: false,
-    error: isOperational ? err.message : 'Internal server error',
+    error: isOperational ? safeErrorMessage(err) : 'Internal server error',
     code
   };
 
@@ -81,7 +85,6 @@ function notFoundHandler(req, res, next) {
 }
 
 module.exports = {
-  asyncHandler,
   errorMiddleware,
   notFoundHandler
 };

dashcaddy-api/error-logger.js

@@ -1,135 +0,0 @@
-// Error Logger Utility
-// Centralized error logging with rotation and request context tracking
-
-const fsp = require('fs').promises;
-const path = require('path');
-const { LIMITS } = require('./constants');
-
-const ERROR_LOG_FILE = path.join(__dirname, 'error.log');
-const MAX_ERROR_LOG_SIZE = LIMITS.ERROR_LOG_SIZE;
-
-/**
- * Check if file exists
- */
-async function exists(filepath) {
-  try {
-    await fsp.access(filepath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Log error with context and rotation
- * @param {string} context - Where the error occurred
- * @param {Error|string} error - The error to log
- * @param {Object} additionalInfo - Additional context (req, etc.)
- */
-async function logError(context, error, additionalInfo = {}) {
-  const timestamp = new Date().toISOString();
-
-  // Extract request context if a request object is provided
-  const requestContext = extractRequestContext(additionalInfo.req);
-  if (additionalInfo.req) {
-    delete additionalInfo.req; // Remove req to avoid circular refs
-  }
-
-  const logEntry = {
-    timestamp,
-    context,
-    ...requestContext,
-    error: {
-      message: error.message || error,
-      stack: error.stack,
-      code: error.code
-    },
-    ...additionalInfo
-  };
-
-  // Format log line with request context
-  const contextInfo = Object.keys(requestContext).length > 0
-    ? `\nRequest Context: ${JSON.stringify(requestContext, null, 2)}`
-    : '';
-  const logLine = `[${timestamp}] ${context}: ${error.message || error}\n${error.stack || ''}${contextInfo}\nAdditional Info: ${JSON.stringify(additionalInfo, null, 2)}\n${'='.repeat(80)}\n`;
-
-  try {
-    // Rotate log if it exceeds max size
-    await rotateLogIfNeeded();
-    await fsp.appendFile(ERROR_LOG_FILE, logLine);
-  } catch (e) {
-    console.error('Failed to write to error log', e.message);
-  }
-}
-
-/**
- * Extract request context from Express request object
- */
-function extractRequestContext(req) {
-  if (!req) return {};
-
-  const clientIP = req.ip || req.socket?.remoteAddress || '';
-  
-  return {
-    requestId: req.id,
-    ip: clientIP,
-    userAgent: req.get('user-agent'),
-    method: req.method,
-    path: req.path
-  };
-}
-
-/**
- * Rotate log file if it exceeds max size
- */
-async function rotateLogIfNeeded() {
-  try {
-    const stats = await fsp.stat(ERROR_LOG_FILE);
-    if (stats.size > MAX_ERROR_LOG_SIZE) {
-      const rotated = ERROR_LOG_FILE + '.1';
-      if (await exists(rotated)) {
-        await fsp.unlink(rotated);
-      }
-      await fsp.rename(ERROR_LOG_FILE, rotated);
-    }
-  } catch (_) {
-    // File may not exist yet, that's fine
-  }
-}
-
-/**
- * Return a safe error message to the client without leaking internals
- */
-function safeErrorMessage(error) {
-  const msg = error.message || String(error);
-
-  // Detect port conflict errors from Docker
-  const portMatch = msg.match(/exposing port TCP [^:]*:(\d+)/);
-  if (portMatch || msg.includes('port is already allocated') || msg.includes('ports are not available')) {
-    const port = portMatch ? portMatch[1] : 'requested';
-    return `Port ${port} is already in use. Please choose a different port or stop the conflicting service.`;
-  }
-
-  // Detect container not found errors
-  if (msg.includes('No such container')) {
-    return 'Container not found';
-  }
-
-  // Detect network errors
-  if (msg.includes('ECONNREFUSED') || msg.includes('ETIMEDOUT')) {
-    return 'Service unavailable';
-  }
-
-  // Generic safe message for unknown errors
-  if (process.env.NODE_ENV === 'production') {
-    return 'An error occurred. Please try again or contact support.';
-  }
-
-  // In development, show the actual error
-  return msg;
-}
-
-module.exports = {
-  logError,
-  safeErrorMessage
-};

dashcaddy-api/middleware.js

@@ -277,9 +277,32 @@ module.exports = function configureMiddleware(app, {
   }
 
   // ── Public routes (bypass TOTP and JWT auth) ──
+  // Routes here are accessible without authentication. By default the
+  // monitoring/health-check endpoints are public so the dashboard can
+  // render widgets before the user logs in. Set MONITORING_PUBLIC=false
+  // (env var) or `monitoring: { public: false }` (config.json) to require
+  // auth for these — useful for internet-exposed deployments where
+  // CPU/memory/disk data is sensitive.
+  const MONITORING_PUBLIC = (() => {
+    if (process.env.MONITORING_PUBLIC === 'false') return false;
+    if (process.env.MONITORING_PUBLIC === 'true') return true;
+    // Default: check config.json if loaded
+    try {
+      const cfg = require('./src/config/site').siteConfig;
+      if (cfg && cfg.monitoring && typeof cfg.monitoring.public === 'boolean') {
+        return cfg.monitoring.public;
+      }
+    } catch { /* config not loaded yet, use default */ }
+    return true; // default: public (current behavior, dashboard needs it)
+  })();
+
   const PUBLIC_ROUTES = [
     { path: '/health',                   exact: true },
+    { path: '/health/live',              exact: true },
+    { path: '/health/ready',             exact: true },
     { path: '/api/v1/health',            exact: true },
+    { path: '/api/v1/health/live',       exact: true },
+    { path: '/api/v1/health/ready',      exact: true },
     { path: '/probe/',                   prefix: true },
     { path: '/api/v1/tailscale/',        prefix: true },
     { path: '/api/v1/totp/config',        exact: true,  method: 'GET' },
@@ -305,8 +328,12 @@ module.exports = function configureMiddleware(app, {
     { path: '/api/v1/config',             exact: true,  method: 'GET' },
     { path: '/api/v1/services/status',    exact: true,  method: 'GET' },
     { path: '/api/v1/system/update-notify', exact: true, method: 'POST' },
-    { path: '/api/v1/monitoring/stats',     exact: true, method: 'GET' },
-    { path: '/api/v1/health-checks/status', exact: true, method: 'GET' },
+    // Monitoring endpoints — only public if MONITORING_PUBLIC is true
+    ...(MONITORING_PUBLIC ? [
+      { path: '/api/v1/monitoring/stats',     exact: true, method: 'GET' },
+      { path: '/api/v1/health-checks/status', exact: true, method: 'GET' },
+    ] : []),
+    { path: '/api/v1/version',             exact: true, method: 'GET' },
   ];
 
   function isPublicRoute(req) {

dashcaddy-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashcaddy-api",
-  "version": "1.12.0",
+  "version": "1.13.2",
   "description": "DashCaddy API server - Dashboard backend for Docker, Caddy & DNS management",
   "main": "server.js",
   "scripts": {

dashcaddy-api/response-helpers.js

@@ -1,114 +0,0 @@
-// Response Helpers
-// Standardize API response format across all routes
-
-const { HTTP_STATUS } = require('./constants');
-
-/**
- * Success response with data
- */
-function success(res, data, statusCode = HTTP_STATUS.OK) {
-  return res.status(statusCode).json({
-    success: true,
-    ...data
-  });
-}
-
-/**
- * Success response with message
- */
-function successMessage(res, message, statusCode = HTTP_STATUS.OK) {
-  return res.status(statusCode).json({
-    success: true,
-    message
-  });
-}
-
-/**
- * Created response (201)
- */
-function created(res, data) {
-  return res.status(HTTP_STATUS.CREATED).json({
-    success: true,
-    ...data
-  });
-}
-
-/**
- * No content response (204)
- */
-function noContent(res) {
-  return res.status(HTTP_STATUS.NO_CONTENT).send();
-}
-
-/**
- * Error response
- */
-function error(res, message, statusCode = HTTP_STATUS.INTERNAL_ERROR) {
-  return res.status(statusCode).json({
-    success: false,
-    error: message
-  });
-}
-
-/**
- * Validation error response (400)
- */
-function validationError(res, message) {
-  return res.status(HTTP_STATUS.BAD_REQUEST).json({
-    success: false,
-    error: message
-  });
-}
-
-/**
- * Unauthorized response (401)
- */
-function unauthorized(res, message = 'Unauthorized') {
-  return res.status(HTTP_STATUS.UNAUTHORIZED).json({
-    success: false,
-    error: message
-  });
-}
-
-/**
- * Forbidden response (403)
- */
-function forbidden(res, message = 'Forbidden') {
-  return res.status(HTTP_STATUS.FORBIDDEN).json({
-    success: false,
-    error: message
-  });
-}
-
-/**
- * Not found response (404)
- */
-function notFound(res, message = 'Not found') {
-  return res.status(HTTP_STATUS.NOT_FOUND).json({
-    success: false,
-    error: message
-  });
-}
-
-/**
- * Conflict response (409)
- */
-function conflict(res, message) {
-  return res.status(HTTP_STATUS.CONFLICT).json({
-    success: false,
-    error: message
-  });
-}
-
-module.exports = {
-  success,
-  successMessage,
-  created,
-  noContent,
-  error,
-  validationError,
-  unauthorized,
-  forbidden,
-  notFound,
-  conflict
-};

dashcaddy-api/routes/auto-restart.js

@@ -8,7 +8,7 @@
  */
 
 const express = require('express');
-const { success } = require('../response-helpers');
+const { success } = require('../src/utils/responses');
 const { ValidationError, NotFoundError } = require('../errors');
 
 /**

dashcaddy-api/routes/backups.js

@@ -1,5 +1,5 @@
 const express = require('express');
-const { success } = require('../response-helpers');
+const { success } = require('../src/utils/responses');
 const fs = require('fs');
 const path = require('path');
 

dashcaddy-api/routes/config-drift.js

@@ -8,7 +8,7 @@
  */
 
 const express = require('express');
-const { success } = require('../response-helpers');
+const { success } = require('../src/utils/responses');
 const { ValidationError, NotFoundError } = require('../errors');
 
 /**

dashcaddy-api/routes/containers.js

@@ -2,7 +2,7 @@ const express = require('express');
 const { DOCKER } = require('../constants');
 const { paginate, parsePaginationParams } = require('../pagination');
 const { NotFoundError } = require('../errors');
-const { success } = require('../response-helpers');
+const { success } = require('../src/utils/responses');
 
 /**
  * Containers route factory

dashcaddy-api/routes/credentials.js

@@ -1,5 +1,5 @@
 const express = require('express');
-const { success, error: errorResponse } = require('../response-helpers');
+const { success, error: errorResponse } = require('../src/utils/responses');
 
 /**
  * Credentials routes factory

dashcaddy-api/routes/dependencies.js

@@ -15,7 +15,7 @@
  */
 
 const express = require('express');
-const { success, error: errorResponse } = require('../response-helpers');
+const { success, error: errorResponse } = require('../src/utils/responses');
 const { NotFoundError, ValidationError } = require('../errors');
 
 /**

dashcaddy-api/routes/dns.js

@@ -4,7 +4,7 @@ const fsp = require('fs').promises;
 const validatorLib = require('validator');
 const { APP, TIMEOUTS, CADDY, DNS_RECORD_TYPES, REGEX, SESSION_TTL } = require('../constants');
 const { exists } = require('../fs-helpers');
-const { success, error: errorResponse } = require('../response-helpers');
+const { success, error: errorResponse } = require('../src/utils/responses');
 const { ValidationError, AuthenticationError, NotFoundError } = require('../errors');
 
 /**

dashcaddy-api/routes/docker-resources.js

@@ -1,5 +1,5 @@
 const express = require('express');
-const { success } = require('../response-helpers');
+const { success } = require('../src/utils/responses');
 const { ValidationError } = require('../errors');
 
 /**

dashcaddy-api/routes/errorlogs.js

@@ -3,7 +3,7 @@ const fs = require('fs');
 const fsp = require('fs').promises;
 const { exists } = require('../fs-helpers');
 const { paginate, parsePaginationParams } = require('../pagination');
-const { success } = require('../response-helpers');
+const { success } = require('../src/utils/responses');
 
 /**
  * Error logs routes factory

dashcaddy-api/routes/health.js

@@ -7,7 +7,7 @@ const { exists } = require('../fs-helpers');
 const { paginate, parsePaginationParams } = require('../pagination');
 const platformPaths = require('../platform-paths');
 const { resolveServiceUrl } = require('../url-resolver');
-const { success, error: errorResponse } = require('../response-helpers');
+const { success, error: errorResponse } = require('../src/utils/responses');
 const { ValidationError } = require('../errors');
 
 /**

dashcaddy-api/routes/license.js

@@ -1,5 +1,5 @@
 const express = require('express');
-const { success, error: errorResponse } = require('../response-helpers');
+const { success, error: errorResponse } = require('../src/utils/responses');
 const { ValidationError } = require('../errors');
 
 /**

dashcaddy-api/routes/monitoring.js

@@ -1,5 +1,5 @@
 const express = require('express');
-const { success } = require('../response-helpers');
+const { success } = require('../src/utils/responses');
 
 /**
  * Monitoring routes factory

dashcaddy-api/routes/services.js

@@ -10,7 +10,8 @@ const { exists } = require('../fs-helpers');
 const { paginate, parsePaginationParams } = require('../pagination');
 const { ValidationError, NotFoundError, ConflictError } = require('../errors');
 const { resolveServiceUrl } = require('../url-resolver');
-const { success, error: errorResponse } = require('../response-helpers');
+const { success, error: errorResponse } = require('../src/utils/responses');
+const platformPaths = require('../platform-paths');
 
 /**
  * Services route factory

dashcaddy-api/routes/ssl-monitor.js

@@ -6,7 +6,7 @@
  */
 
 const express = require('express');
-const { success, error: errorResponse, notFound } = require('../response-helpers');
+const { success, error: errorResponse, notFound } = require('../src/utils/responses');
 
 /**
  * SSL Monitor route factory

dashcaddy-api/routes/themes.js

@@ -1,7 +1,7 @@
 const express = require('express');
 const fs = require('fs');
 const path = require('path');
-const { success } = require('../response-helpers');
+const { success } = require('../src/utils/responses');
 const { ValidationError, NotFoundError } = require('../errors');
 const platformPaths = require('../platform-paths');
 

dashcaddy-api/src/app.js

@@ -627,6 +627,86 @@ async function createApp() {
     res.json({ status: 'ok', timestamp: new Date().toISOString() });
   });
 
+  // Liveness probe — "is the process alive?"
+  // Always returns 200 unless the Node.js event loop is completely blocked.
+  // Used by k8s/Docker to decide whether to RESTART the container.
+  // DO NOT add dependency checks here — those belong in /health/ready.
+  app.get('/health/live', (req, res) => {
+    res.json({ status: 'alive', uptime: process.uptime() });
+  });
+
+  // Readiness probe — "is the app ready to serve traffic?"
+  // Checks critical dependencies: Docker daemon, Caddy admin API, config file.
+  // Returns 200 with details if all OK, 503 with failed components otherwise.
+  // Used by k8s/Docker to decide whether to ROUTE TRAFFIC to this instance.
+  app.get('/health/ready', boundAsyncHandler(async (req, res) => {
+    const checks = {};
+    let allOk = true;
+
+    // Check 1: Config file readable
+    try {
+      const fs = require('fs');
+      if (fs.existsSync(config.CONFIG_FILE)) {
+        fs.readFileSync(config.CONFIG_FILE, 'utf8');
+        checks.configFile = { ok: true };
+      } else {
+        checks.configFile = { ok: false, error: 'Config file not found' };
+        allOk = false;
+      }
+    } catch (e) {
+      checks.configFile = { ok: false, error: e.message };
+      allOk = false;
+    }
+
+    // Check 2: Services file readable
+    try {
+      const fs = require('fs');
+      if (fs.existsSync(config.SERVICES_FILE)) {
+        fs.readFileSync(config.SERVICES_FILE, 'utf8');
+        checks.servicesFile = { ok: true };
+      } else {
+        checks.servicesFile = { ok: false, error: 'Services file not found' };
+        allOk = false;
+      }
+    } catch (e) {
+      checks.servicesFile = { ok: false, error: e.message };
+      allOk = false;
+    }
+
+    // Check 3: Docker daemon reachable
+    try {
+      const docker = require('dockerode')();
+      await docker.ping();
+      checks.docker = { ok: true };
+    } catch (e) {
+      checks.docker = { ok: false, error: e.message };
+      allOk = false;
+    }
+
+    // Check 4: Caddy admin API reachable
+    try {
+      const caddyUrl = config.CADDY_ADMIN_URL || 'http://localhost:2019';
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 3000);
+      const response = await fetch(`${caddyUrl}/config/`, {
+        signal: controller.signal
+      });
+      clearTimeout(timeout);
+      checks.caddy = { ok: response.ok, status: response.status };
+      if (!response.ok) allOk = false;
+    } catch (e) {
+      checks.caddy = { ok: false, error: e.message };
+      allOk = false;
+    }
+
+    const body = {
+      status: allOk ? 'ready' : 'not-ready',
+      timestamp: new Date().toISOString(),
+      checks
+    };
+    res.status(allOk ? 200 : 503).json(body);
+  }));
+
   // Lightweight probe endpoint
   app.get('/probe/:id', boundAsyncHandler(async (req, res) => {
     const id = req.params.id;

dashcaddy-api/src/config/migrations.js

@@ -0,0 +1,142 @@
+/**
+ * Config migration system
+ *
+ * When config.json schema changes between versions, register a migration
+ * function here. On load, the loader detects the stored version, runs all
+ * migrations from that version forward, and writes the result back.
+ *
+ * Migration format:
+ *   migrations[<toVersion>] = (rawConfig) => { ...mutations, _version: toVersion }
+ *
+ * Each migration is responsible for transforming the previous version's
+ * shape into the next version's shape. They run sequentially, so v1→v2→v3
+ * all execute in order.
+ *
+ * For first-time users with no config file, the loader creates a fresh
+ * config with CURRENT_VERSION, so they start at the latest schema.
+ */
+const fs = require('fs');
+const path = require('path');
+const platformPaths = require('../../platform-paths');
+
+const CURRENT_VERSION = 2;
+
+/**
+ * Migrations: keys are the version they PRODUCE.
+ * Each migration takes a raw config object and returns the next version.
+ */
+const migrations = {
+  // v0 (unversioned) → v1: add _version field, normalize dns structure
+  1: (raw) => {
+    const migrated = { ...raw };
+    if (!migrated._version) migrated._version = 1;
+    // Normalize: older configs may have dns as a string IP, convert to object
+    if (typeof migrated.dns === 'string') {
+      migrated.dns = { ip: migrated.dns, port: 5380 };
+    } else if (!migrated.dns) {
+      migrated.dns = { ip: '', port: 5380 };
+    }
+    return migrated;
+  },
+
+  // v1 → v2: add dns.provider field (default: 'technitium' for backwards compat)
+  2: (raw) => {
+    const migrated = { ...raw };
+    if (migrated.dns && !migrated.dns.provider) {
+      migrated.dns.provider = 'technitium';
+    }
+    migrated._version = 2;
+    return migrated;
+  }
+};
+
+/**
+ * Run all migrations from `fromVersion` (or detected) to CURRENT_VERSION.
+ * @param {object} raw - The raw config object (may or may not have _version)
+ * @returns {object} The migrated config
+ */
+function migrate(raw) {
+  if (!raw || typeof raw !== 'object') {
+    // First-time load: return minimal config at current version
+    return { _version: CURRENT_VERSION };
+  }
+
+  const fromVersion = raw._version || 0;
+  if (fromVersion > CURRENT_VERSION) {
+    // Config from a future version — bail out, don't corrupt it
+    // The validation step will catch any actual issues
+    return raw;
+  }
+
+  let current = { ...raw };
+  for (let v = fromVersion + 1; v <= CURRENT_VERSION; v++) {
+    if (migrations[v]) {
+      current = migrations[v](current);
+    } else {
+      // No migration defined for this version, just bump _version
+      current._version = v;
+    }
+  }
+  return current;
+}
+
+/**
+ * Load config from disk, run migrations if needed, and write back the
+ * migrated version. Safe to call on every startup.
+ * @param {string} configFile - Absolute path to config.json
+ * @param {object} log - Logger instance
+ * @returns {object} The migrated config object
+ */
+function loadAndMigrate(configFile, log) {
+  let raw = null;
+  let fileExisted = false;
+
+  if (fs.existsSync(configFile)) {
+    fileExisted = true;
+    try {
+      raw = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    } catch (e) {
+      if (log && log.error) {
+        log.error('config-migration', 'Failed to parse config.json, using defaults', { error: e.message });
+      }
+      raw = null;
+    }
+  }
+
+  const fromVersion = raw && raw._version ? raw._version : 0;
+  const migrated = migrate(raw);
+
+  // Only write back to disk if:
+  //   1. The file already existed (we don't create configs on fresh installs —
+  //      the loader's defaults handle that case), AND
+  //   2. The version actually changed (no point rewriting identical content)
+  if (fileExisted && fromVersion < CURRENT_VERSION) {
+    if (log && log.info) {
+      log.info('config-migration', `Migrated config v${fromVersion} → v${CURRENT_VERSION}`, {
+        from: fromVersion,
+        to: CURRENT_VERSION,
+        path: configFile
+      });
+    }
+    // Write back the migrated config
+    try {
+      // Ensure parent dir exists
+      const dir = path.dirname(configFile);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(configFile, JSON.stringify(migrated, null, 2));
+    } catch (e) {
+      if (log && log.warn) {
+        log.warn('config-migration', 'Failed to write migrated config back to disk', { error: e.message });
+      }
+    }
+  }
+
+  return migrated;
+}
+
+module.exports = {
+  CURRENT_VERSION,
+  migrations,
+  migrate,
+  loadAndMigrate
+};

dashcaddy-api/src/config/site.js

@@ -1,10 +1,15 @@
 /**
  * Site configuration loader
  * Loads and manages site-wide settings from config.json
+ *
+ * Includes automatic migration from older config versions (see migrations.js).
+ * Users never see the migration — it runs silently on startup, writes the
+ * updated config back, and the rest of the app only ever sees the current
+ * schema.
  */
-const fs = require('fs');
 const { validateConfig } = require('../../config-schema');
 const { CADDY } = require('../../constants');
+const { loadAndMigrate, CURRENT_VERSION } = require('./migrations');
 
 const siteConfig = {
   tld: '.home',
@@ -21,9 +26,11 @@ const siteConfig = {
 
 function loadSiteConfig(CONFIG_FILE, log) {
   try {
-    if (fs.existsSync(CONFIG_FILE)) {
-      const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    // Run migrations first — this handles config.json files from older
+    // versions of DashCaddy and writes the migrated version back to disk.
+    const raw = loadAndMigrate(CONFIG_FILE, log);
 
+    if (raw && Object.keys(raw).length > 0) {
       // Validate config and log any issues
       const { valid, errors: configErrors, warnings: configWarnings } = validateConfig(raw);
       if (log && log.warn) {
@@ -76,4 +83,5 @@ module.exports = {
   loadSiteConfig,
   buildDomain,
   buildServiceUrl,
+  CURRENT_VERSION
 };

dashcaddy-api/src/utils/responses.js

@@ -1,22 +1,124 @@
 /**
  * Response helpers - Standard API response formats
+ *
+ * Single source of truth for HTTP response shapes across DashCaddy.
+ * Standard envelope: { success: true, ...data } or { success: false, error: "..." }.
+ *
+ * All routes should import from this module — do not call res.json/res.status
+ * directly with the response shape, use these helpers instead.
  */
+const { HTTP_STATUS } = require('../../constants');
+
+// ── Success helpers ────────────────────────────────────────────
 
 /**
- * Standard error response
+ * Standard success response. Use this in route handlers.
+ * Wraps the data object with a `success: true` envelope.
+ * @param {object} res Express response
+ * @param {object} [data={}] fields to include in the response body
+ * @param {number} [statusCode=200] HTTP status code
+ */
+function ok(res, data = {}, statusCode = HTTP_STATUS.OK) {
+  return res.status(statusCode).json({ success: true, ...data });
+}
+
+/**
+ * Alias for `ok` — prefer `ok` in new code, but kept for code that imports as `success`.
+ */
+function success(res, data, statusCode) {
+  return ok(res, data, statusCode);
+}
+
+/**
+ * Success response with a human-readable message field.
+ * Use when there's no data to return, just confirmation.
+ */
+function successMessage(res, message, statusCode = HTTP_STATUS.OK) {
+  return res.status(statusCode).json({ success: true, message });
+}
+
+/**
+ * 201 Created response.
+ */
+function created(res, data = {}) {
+  return res.status(HTTP_STATUS.CREATED).json({ success: true, ...data });
+}
+
+/**
+ * 204 No Content response.
+ */
+function noContent(res) {
+  return res.status(HTTP_STATUS.NO_CONTENT).send();
+}
+
+// ── Error helpers ──────────────────────────────────────────────
+
+/**
+ * Standard error response. Use this in route handlers.
+ * @param {object} res Express response
+ * @param {number} statusCode HTTP status code
+ * @param {string} message Human-readable error message
+ * @param {object} [extras={}] additional fields to merge into the response
  */
 function errorResponse(res, statusCode, message, extras = {}) {
   return res.status(statusCode).json({ success: false, error: message, ...extras });
 }
 
 /**
- * Standard success response
+ * Alias for `errorResponse` — kept for code that imports as `error`.
  */
-function ok(res, data = {}) {
-  return res.json({ success: true, ...data });
+function error(res, message, statusCode = HTTP_STATUS.INTERNAL_ERROR) {
+  return res.status(statusCode).json({ success: false, error: message });
+}
+
+/**
+ * 400 Bad Request — invalid input from the user.
+ */
+function validationError(res, message) {
+  return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: message });
+}
+
+/**
+ * 401 Unauthorized — no valid credentials.
+ */
+function unauthorized(res, message = 'Unauthorized') {
+  return res.status(HTTP_STATUS.UNAUTHORIZED).json({ success: false, error: message });
+}
+
+/**
+ * 403 Forbidden — credentials valid but permission denied.
+ */
+function forbidden(res, message = 'Forbidden') {
+  return res.status(HTTP_STATUS.FORBIDDEN).json({ success: false, error: message });
+}
+
+/**
+ * 404 Not Found — resource doesn't exist.
+ */
+function notFound(res, message = 'Not found') {
+  return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: message });
+}
+
+/**
+ * 409 Conflict — request conflicts with current state (e.g. duplicate).
+ */
+function conflict(res, message) {
+  return res.status(HTTP_STATUS.CONFLICT).json({ success: false, error: message });
 }
 
 module.exports = {
-  errorResponse,
+  // Success helpers
   ok,
+  success,
+  successMessage,
+  created,
+  noContent,
+  // Error helpers
+  errorResponse,
+  error,
+  validationError,
+  unauthorized,
+  forbidden,
+  notFound,
+  conflict,
 };