Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(ops): config drift detection, per-resource repair and doctor sweep

Juan Denisf296e1dd61db
diff --git a/backend/app/api/doctor.py b/backend/app/api/doctor.py
new file mode 100644
index 00000000..a9ab7f4f
--- /dev/null
+++ b/backend/app/api/doctor.py
@@ -0,0 +1,104 @@
+"""REST surface for the doctor sweep + configuration drift.
+
+Mounted at /api/v1/doctor (registered in app/__init__.py). Admin-only.
+
+Contract (the CLI codes against this too):
+ GET /drift -> {'report': <last drift report>|null}
+ POST /drift/check -> 202 {'job_id'}
+ POST /drift/<type>/<id>/repair -> repair result; body must carry
+ {'confirm': true} (400 otherwise)
+ GET / -> {'report': <last doctor report>|null}
+ POST /run -> runs synchronously, {'report': ...}
+ POST /repair -> {'results': [...]} for body
+ {'items': [{kind, type?, id?, name?}]}
+"""
+from flask import Blueprint, jsonify, request
+
+from ..middleware.rbac import admin_required
+from ..services.doctor_service import DoctorService
+from ..services.drift_service import DRIFT_JOB_KIND, DriftService
+
+doctor_bp = Blueprint('doctor', __name__)
+
+
+# --------------------------------------------------------------------------- #
+# Drift
+# --------------------------------------------------------------------------- #
+
+@doctor_bp.route('/drift', methods=['GET'])
+@admin_required
+def get_drift_report():
+ """Last stored drift report (null when no sweep has run yet)."""
+ try:
+ return jsonify({'report': DriftService.get_last_report()})
+ except Exception as exc: # noqa: BLE001 — surface as a clean JSON error
+ return jsonify({'error': str(exc)}), 500
+
+
+@doctor_bp.route('/drift/check', methods=['POST'])
+@admin_required
+def run_drift_check():
+ """Enqueue a one-off drift sweep job."""
+ try:
+ from app.jobs.service import JobService
+ job = JobService.enqueue(DRIFT_JOB_KIND, payload={}, max_attempts=1)
+ return jsonify({'job_id': job.id}), 202
+ except Exception as exc: # noqa: BLE001
+ return jsonify({'error': str(exc)}), 500
+
+
+@doctor_bp.route('/drift/<check_type>/<resource_id>/repair', methods=['POST'])
+@admin_required
+def repair_drift(check_type, resource_id):
+ """Repair one drifted resource. Explicit confirmation required."""
+ data = request.get_json(silent=True) or {}
+ if data.get('confirm') is not True:
+ return jsonify({'error': 'Confirmation required: pass {"confirm": true}.'}), 400
+ try:
+ rid = int(resource_id) if resource_id.isdigit() else resource_id
+ result = DriftService.repair(check_type, rid)
+ status = 200 if result.get('success') else 400
+ return jsonify(result), status
+ except Exception as exc: # noqa: BLE001
+ return jsonify({'error': str(exc)}), 500
+
+
+# --------------------------------------------------------------------------- #
+# Doctor
+# --------------------------------------------------------------------------- #
+
+@doctor_bp.route('', methods=['GET'])
+@doctor_bp.route('/', methods=['GET'])
+@admin_required
+def get_doctor_report():
+ """Last stored doctor report (null when the doctor has never run)."""
+ try:
+ return jsonify({'report': DoctorService.get_last_report()})
+ except Exception as exc: # noqa: BLE001
+ return jsonify({'error': str(exc)}), 500
+
+
+@doctor_bp.route('/run', methods=['POST'])
+@admin_required
+def run_doctor():
+ """Run the sweep synchronously (the doctor is interactive; every internal
+ probe is time-capped) and return the fresh report."""
+ try:
+ report = DoctorService.run()
+ return jsonify({'report': report})
+ except Exception as exc: # noqa: BLE001
+ return jsonify({'error': str(exc)}), 500
+
+
+@doctor_bp.route('/repair', methods=['POST'])
+@admin_required
+def repair_items():
+ """Batch-repair the explicit items the operator selected."""
+ data = request.get_json(silent=True) or {}
+ items = data.get('items')
+ if not isinstance(items, list) or not items:
+ return jsonify({'error': "Body must carry a non-empty 'items' list."}), 400
+ try:
+ return jsonify({'results': DoctorService.repair(items)})
+ except Exception as exc: # noqa: BLE001
+ return jsonify({'error': str(exc)}), 500
diff --git a/backend/app/notifications/catalog.py b/backend/app/notifications/catalog.py
index c502a29f..c0827721 100644
--- a/backend/app/notifications/catalog.py
+++ b/backend/app/notifications/catalog.py
@@ -100,6 +100,14 @@ _CATALOG = {
'severity': 'warning',
'category': 'system',
},
+ # Daily drift sweep found managed config files that no longer match what
+ # the panel would write (see app/services/drift_service.py).
+ 'drift.detected': {
+ 'title': 'Configuration drift detected ({count})',
+ 'template': 'generic',
+ 'severity': 'warning',
+ 'category': 'system',
+ },
# Multi-alert monitoring digest (used by the legacy send_all path).
'monitoring.alert': {
'title': 'ServerKit alert',
diff --git a/backend/app/services/compose_env_service.py b/backend/app/services/compose_env_service.py
index 58f5f94c..7385e547 100644
--- a/backend/app/services/compose_env_service.py
+++ b/backend/app/services/compose_env_service.py
@@ -121,6 +121,71 @@ class ComposeEnvService:
"""
return str(value).replace('$', '$$')
+ @classmethod
+ def render_override(cls, project_path, compose_file=None):
+ """Compute the override that *should* exist for a project dir, without
+ touching disk. Extracted from :meth:`refresh_for_project` so drift
+ detection can render the expected file content in-memory.
+
+ Returns ``{'applies': bool, 'path': str|None, 'content': str|None}``:
+ ``applies=False`` when this dir isn't a managed compose app (leave it
+ alone); ``content=None`` (with ``applies=True``) when no override should
+ exist. May raise — :meth:`refresh_for_project` wraps it.
+ """
+ if not project_path or not os.path.isdir(project_path):
+ return {'applies': False, 'path': None, 'content': None}
+
+ app = cls._app_for_project(project_path)
+ if app is None:
+ # Not a managed app dir (e.g. a proxy stack) — leave it alone.
+ return {'applies': False, 'path': None, 'content': None}
+
+ base = cls.find_base_compose(project_path, compose_file)
+ if not base:
+ return {'applies': False, 'path': None, 'content': None}
+ override_path = cls.override_path(project_path)
+ base_path = base if os.path.isabs(base) else os.path.join(project_path, base)
+ service_names = cls._service_names(base_path)
+ if not service_names:
+ return {'applies': True, 'path': override_path, 'content': None}
+
+ from app.services.env_service import EnvService
+ # Per-service effective env: a variable lands on every service unless
+ # it targets a specific one (EnvironmentVariable/SharedVariable
+ # .target_service). Local env vars override shared variable groups.
+ per_service = EnvService.get_effective_env_for_services(app.id, service_names)
+
+ services_block = {}
+ for name in service_names:
+ svc_env = (per_service or {}).get(name) or {}
+ if not svc_env:
+ continue # nothing targeted at this service
+ services_block[name] = {
+ 'environment': {k: cls._escape(v) for k, v in svc_env.items() if k}
+ }
+
+ # Per-app resource limits (task #23): cap the app's primary
+ # (first-declared) compose service. mem_limit/cpus apply with plain
+ # (non-swarm) docker compose.
+ limits = cls._limits_block(app)
+ if limits:
+ services_block.setdefault(service_names[0], {}).update(limits)
+
+ if not services_block:
+ # Nothing to inject → no override should exist.
+ return {'applies': True, 'path': override_path, 'content': None}
+ override = {'services': services_block}
+
+ header = (
+ '# Managed by ServerKit — do not edit.\n'
+ '# Injects the app\'s effective environment (shared variable groups\n'
+ '# under the app\'s own local env vars) into every compose service,\n'
+ '# plus any per-app resource limits on the primary service.\n'
+ '# Regenerated on every deploy; delete it and it will be recreated.\n'
+ )
+ content = header + yaml.safe_dump(override, default_flow_style=False, sort_keys=True)
+ return {'applies': True, 'path': override_path, 'content': content}
+
@classmethod
def refresh_for_project(cls, project_path, compose_file=None):
"""Regenerate (or remove) the env override for a project dir.
@@ -129,63 +194,16 @@ class ComposeEnvService:
Best-effort and fully guarded — never raises.
"""
try:
- if not project_path or not os.path.isdir(project_path):
+ spec = cls.render_override(project_path, compose_file)
+ if not spec['applies']:
return None
-
- app = cls._app_for_project(project_path)
- if app is None:
- # Not a managed app dir (e.g. a proxy stack) — leave it alone.
- return None
-
- base = cls.find_base_compose(project_path, compose_file)
- if not base:
- return None
- base_path = base if os.path.isabs(base) else os.path.join(project_path, base)
- service_names = cls._service_names(base_path)
- if not service_names:
- cls._remove_override(project_path)
- return None
-
- from app.services.env_service import EnvService
- # Per-service effective env: a variable lands on every service unless
- # it targets a specific one (EnvironmentVariable/SharedVariable
- # .target_service). Local env vars override shared variable groups.
- per_service = EnvService.get_effective_env_for_services(app.id, service_names)
-
- services_block = {}
- for name in service_names:
- svc_env = (per_service or {}).get(name) or {}
- if not svc_env:
- continue # nothing targeted at this service
- services_block[name] = {
- 'environment': {k: cls._escape(v) for k, v in svc_env.items() if k}
- }
-
- # Per-app resource limits (task #23): cap the app's primary
- # (first-declared) compose service. mem_limit/cpus apply with plain
- # (non-swarm) docker compose.
- limits = cls._limits_block(app)
- if limits:
- services_block.setdefault(service_names[0], {}).update(limits)
-
- if not services_block:
+ if spec['content'] is None:
# Nothing to inject → make sure no stale override lingers.
cls._remove_override(project_path)
return None
- override = {'services': services_block}
-
- override_path = cls.override_path(project_path)
- header = (
- '# Managed by ServerKit — do not edit.\n'
- '# Injects the app\'s effective environment (shared variable groups\n'
- '# under the app\'s own local env vars) into every compose service,\n'
- '# plus any per-app resource limits on the primary service.\n'
- '# Regenerated on every deploy; delete it and it will be recreated.\n'
- )
- with open(override_path, 'w', encoding='utf-8') as f:
- f.write(header)
- yaml.safe_dump(override, f, default_flow_style=False, sort_keys=True)
- return override_path
+ with open(spec['path'], 'w', encoding='utf-8') as f:
+ f.write(spec['content'])
+ return spec['path']
except Exception as e: # pragma: no cover - defensive
logger.warning('compose env overlay refresh failed for %s: %s', project_path, e)
return None
diff --git a/backend/app/services/doctor_service.py b/backend/app/services/doctor_service.py
new file mode 100644
index 00000000..983b9ccc
--- /dev/null
+++ b/backend/app/services/doctor_service.py
@@ -0,0 +1,265 @@
+"""One-shot "doctor" health sweep + explicit batch repair.
+
+Aggregates the drift report (drift_service) with a handful of cheap host
+health probes into a single ``{'checks': [...], 'ran_at': ...}`` report the
+Monitoring → Doctor tab renders. Everything is best-effort and bounded — the
+doctor is interactive (the API runs it synchronously), so no probe may hang.
+
+Nothing here repairs anything automatically: :meth:`DoctorService.repair`
+runs only for the explicit items the operator selected.
+"""
+import json
+import logging
+import sys
+from datetime import datetime, timedelta
+
+logger = logging.getLogger(__name__)
+
+DOCTOR_JOB_KIND = 'doctor.run'
+LAST_REPORT_KEY = 'doctor_last_report'
+
+# Core host services the doctor probes and is allowed to restart on demand.
+CORE_SERVICES = ('nginx', 'docker')
+
+CERT_WARN_DAYS = 14
+DISK_WARN_FREE_PCT = 10.0
+DISK_FAIL_FREE_PCT = 5.0
+
+# Cap for the synchronous probes that shell out (systemctl is-active).
+PROBE_TIMEOUT_SECONDS = 10
+
+
+def _check(key, title, status, detail, repairable=False, repair_ref=None):
+ return {
+ 'key': key,
+ 'title': title,
+ 'status': status, # 'ok' | 'warn' | 'fail'
+ 'detail': detail,
+ 'repairable': bool(repairable),
+ 'repair_ref': repair_ref,
+ }
+
+
+class DoctorService:
+ """Run the health sweep, store the last report, batch-repair on demand."""
+
+ # ------------------------------------------------------------------ #
+ # Sub-checks (each best-effort; a probe failure = a 'warn' entry, never
+ # an exception out of run()).
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def _drift_checks(cls):
+ from app.services.drift_service import DriftService
+ checks = []
+ try:
+ results = DriftService.check_all()
+ except Exception as e: # noqa: BLE001
+ return [_check('drift', 'Configuration drift', 'warn',
+ f'Drift sweep failed: {e}')]
+ for r in results:
+ key = f"drift.{r['type']}.{r['id']}" if r['id'] is not None else f"drift.{r['type']}"
+ title = f"Drift: {r['name']}"
+ if r['status'] == 'in_sync':
+ checks.append(_check(key, title, 'ok', 'Matches the expected configuration.'))
+ elif r['status'] in ('drifted', 'missing'):
+ detail = ('Managed file is missing on disk.' if r['status'] == 'missing'
+ else 'On-disk file differs from what ServerKit would write.')
+ entry = _check(
+ key, title, 'warn', detail, repairable=True,
+ repair_ref={'kind': 'drift', 'type': r['type'], 'id': r['id']},
+ )
+ entry['diff'] = r.get('diff')
+ checks.append(entry)
+ else: # error
+ checks.append(_check(key, title, 'warn',
+ r.get('detail') or 'Check could not run.'))
+ return checks
+
+ @classmethod
+ def _service_checks(cls):
+ checks = []
+ if not sys.platform.startswith('linux'):
+ for name in CORE_SERVICES:
+ checks.append(_check(f'service.{name}', f'{name} service', 'warn',
+ 'unsupported on this host'))
+ return checks
+ from app.utils.system import ServiceControl
+ for name in CORE_SERVICES:
+ try:
+ active = ServiceControl.is_active(name)
+ except Exception as e: # noqa: BLE001
+ checks.append(_check(f'service.{name}', f'{name} service', 'warn',
+ f'Status probe failed: {e}'))
+ continue
+ if active:
+ checks.append(_check(f'service.{name}', f'{name} service', 'ok', 'Running.'))
+ else:
+ checks.append(_check(
+ f'service.{name}', f'{name} service', 'fail', 'Not running.',
+ repairable=True, repair_ref={'kind': 'service', 'name': name},
+ ))
+ return checks
+
+ @classmethod
+ def _cert_check(cls):
+ """Nearest tracked certificate expiry (Domain.ssl_expires_at)."""
+ try:
+ from app.models.domain import Domain
+ rows = (Domain.query
+ .filter(Domain.ssl_expires_at.isnot(None))
+ .order_by(Domain.ssl_expires_at.asc())
+ .all())
+ except Exception as e: # noqa: BLE001
+ return _check('certs.expiry', 'Certificate expiry', 'warn',
+ f'Could not read certificate data: {e}')
+ if not rows:
+ return _check('certs.expiry', 'Certificate expiry', 'ok',
+ 'No certificates tracked.')
+ now = datetime.utcnow()
+ soon = [d for d in rows if d.ssl_expires_at <= now + timedelta(days=CERT_WARN_DAYS)]
+ expired = [d for d in soon if d.ssl_expires_at <= now]
+ if expired:
+ names = ', '.join(d.name for d in expired[:5])
+ return _check('certs.expiry', 'Certificate expiry', 'fail',
+ f'Expired certificate(s): {names}')
+ if soon:
+ nearest = soon[0]
+ days = max(0, (nearest.ssl_expires_at - now).days)
+ return _check('certs.expiry', 'Certificate expiry', 'warn',
+ f'{len(soon)} certificate(s) expire within {CERT_WARN_DAYS} days '
+ f'(nearest: {nearest.name} in {days}d).')
+ nearest = rows[0]
+ return _check('certs.expiry', 'Certificate expiry', 'ok',
+ f'Nearest expiry: {nearest.name} on '
+ f'{nearest.ssl_expires_at.date().isoformat()}.')
+
+ @classmethod
+ def _disk_check(cls):
+ try:
+ import psutil
+ usage = psutil.disk_usage('/')
+ free_pct = 100.0 - usage.percent
+ except Exception as e: # noqa: BLE001
+ return _check('disk.headroom', 'Disk headroom', 'warn',
+ f'Could not read disk usage: {e}')
+ detail = f'{free_pct:.1f}% free on /.'
+ if free_pct < DISK_FAIL_FREE_PCT:
+ return _check('disk.headroom', 'Disk headroom', 'fail', detail)
+ if free_pct < DISK_WARN_FREE_PCT:
+ return _check('disk.headroom', 'Disk headroom', 'warn', detail)
+ return _check('disk.headroom', 'Disk headroom', 'ok', detail)
+
+ @classmethod
+ def _db_check(cls):
+ try:
+ from sqlalchemy import text
+ from app import db
+ db.session.execute(text('SELECT 1'))
+ return _check('db.reachable', 'Database', 'ok', 'Reachable.')
+ except Exception as e: # noqa: BLE001
+ return _check('db.reachable', 'Database', 'fail', f'Query failed: {e}')
+
+ # ------------------------------------------------------------------ #
+ # Sweep
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def run(cls):
+ """Run the full sweep synchronously and store the report.
+
+ Returns ``{'checks': [...], 'ran_at': iso}``.
+ """
+ checks = []
+ checks += cls._drift_checks()
+ checks += cls._service_checks()
+ checks.append(cls._cert_check())
+ checks.append(cls._disk_check())
+ checks.append(cls._db_check())
+ report = {
+ 'checks': checks,
+ 'ran_at': datetime.utcnow().isoformat() + 'Z',
+ }
+ cls.store_report(report)
+ return report
+
+ @classmethod
+ def store_report(cls, report):
+ try:
+ from app.services.settings_service import SettingsService
+ SettingsService.set(LAST_REPORT_KEY, json.dumps(report))
+ except Exception as e: # noqa: BLE001 — storage is best-effort
+ logger.warning('could not store doctor report: %s', e)
+
+ @classmethod
+ def get_last_report(cls):
+ from app.services.settings_service import SettingsService
+ raw = SettingsService.get(LAST_REPORT_KEY)
+ if not raw:
+ return None
+ try:
+ return json.loads(raw)
+ except (TypeError, ValueError):
+ return None
+
+ # ------------------------------------------------------------------ #
+ # Batch repair (explicit only)
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def repair(cls, items):
+ """Repair an explicit list of items.
+
+ ``items``: ``[{'kind': 'drift', 'type': ..., 'id': ...} |
+ {'kind': 'service', 'name': ...}]``. Returns per-item results (same
+ order), each carrying the input item plus ``success``/detail fields.
+ """
+ results = []
+ for item in items or []:
+ kind = (item or {}).get('kind')
+ if kind == 'drift':
+ from app.services.drift_service import DriftService
+ res = DriftService.repair(item.get('type'), item.get('id'))
+ results.append({'item': item, **res})
+ elif kind == 'service':
+ results.append({'item': item, **cls._restart_service(item.get('name'))})
+ else:
+ results.append({'item': item, 'success': False,
+ 'error': f'Unknown repair kind: {kind}'})
+ return results
+
+ @classmethod
+ def _restart_service(cls, name):
+ if name not in CORE_SERVICES:
+ return {'success': False, 'error': f'Service not repairable: {name}'}
+ if not sys.platform.startswith('linux'):
+ return {'success': False, 'error': 'unsupported on this host'}
+ try:
+ from app.utils.system import ServiceControl
+ proc = ServiceControl.restart(name, timeout=60)
+ if proc.returncode == 0:
+ return {'success': True, 'restarted': name}
+ return {'success': False, 'error': (proc.stderr or '').strip()
+ or f'systemctl restart {name} failed'}
+ except Exception as e: # noqa: BLE001
+ return {'success': False, 'error': str(e)}
+
+ # ------------------------------------------------------------------ #
+ # Job plumbing
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def run_doctor_job(cls, job):
+ """Job handler for ``doctor.run`` (background variant of run())."""
+ report = cls.run()
+ counts = {}
+ for c in report['checks']:
+ counts[c['status']] = counts.get(c['status'], 0) + 1
+ return {'ran_at': report['ran_at'], 'counts': counts}
+
+ @classmethod
+ def register_jobs(cls):
+ """Register the doctor handler with the job registry.
+ Called once at app startup (see app/__init__.py)."""
+ from app.jobs import registry
+ registry.register(DOCTOR_JOB_KIND, cls.run_doctor_job, replace=True)
diff --git a/backend/app/services/drift_service.py b/backend/app/services/drift_service.py
new file mode 100644
index 00000000..b2c492c5
--- /dev/null
+++ b/backend/app/services/drift_service.py
@@ -0,0 +1,449 @@
+"""Configuration drift detection + explicit per-resource repair.
+
+ServerKit's service layer is imperative: it writes nginx vhosts and compose
+override files from DB state and assumes they stay put. This module closes the
+loop *gradually*: it re-renders what each managed file **should** contain
+(through the exact same renderers the panel uses when writing them), compares
+against what is actually on disk, and reports the difference. Nothing here
+auto-repairs — :meth:`DriftService.repair` runs only when explicitly invoked
+(API / doctor batch), per single resource.
+
+Check framework
+---------------
+``DRIFT_CHECKS`` maps a resource ``type`` to a small check dict:
+
+ {
+ 'type': 'nginx_vhost',
+ 'title': 'Nginx vhosts',
+ 'supported': fn() -> (bool, reason), # optional platform gate
+ 'list_resources': fn() -> [(id, name)],
+ 'render_expected': fn(resource_id) -> {path: content|None},
+ 'read_actual': fn(paths) -> {path: content|None}, # optional; default
+ # reads the files
+ 'repair': fn(resource_id) -> {'success', 'wrote', 'reloaded', ...},
+ }
+
+``render_expected`` values: a string is the exact content the file must have;
+``None`` means the file must NOT exist (e.g. a stale compose override that
+should have been removed). An empty dict means nothing applies to this
+resource → it reports ``in_sync``.
+
+Platform policy (documented choice): the built-in checks cover Linux server
+paths (``/etc/nginx/...``, app roots). On a non-Linux host each built-in check
+reports a single ``status='error'`` entry with detail ``'unsupported on this
+host'`` — we deliberately do NOT report ``in_sync`` there, because "we couldn't
+look" is not "it matches". The gate lives per-check (``supported``) so tests
+and future cross-platform checks run anywhere.
+
+Systemd units: the panel *does* template gunicorn units
+(``PythonService.create_gunicorn_service``), but their render inputs (worker
+count, run-as user, and a point-in-time snapshot of the app's ``.env``) are
+not persisted anywhere, so a faithful expected-render is impossible —
+re-rendering with today's defaults would flag false drift. The ServerKit
+panel/agent units themselves are installer-owned. No systemd drift check is
+registered for now.
+"""
+import difflib
+import json
+import logging
+import os
+import sys
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+DRIFT_JOB_KIND = 'drift.check'
+DRIFT_SCHEDULE_NAME = 'drift-check'
+LAST_REPORT_KEY = 'drift_last_report'
+DIFF_MAX_LINES = 200
+
+# type -> check dict (see module docstring for the shape).
+DRIFT_CHECKS = {}
+
+
+def register_check(check):
+ """Register (or replace) a drift check. Plugins may add their own."""
+ DRIFT_CHECKS[check['type']] = check
+ return check
+
+
+def _is_linux():
+ return sys.platform.startswith('linux')
+
+
+def _linux_only():
+ if _is_linux():
+ return True, None
+ return False, 'unsupported on this host'
+
+
+def _default_read_actual(paths):
+ """Read each path from disk; ``None`` for a file that doesn't exist."""
+ actual = {}
+ for path in paths:
+ try:
+ if os.path.exists(path):
+ with open(path, 'r', encoding='utf-8', errors='replace') as f:
+ actual[path] = f.read()
+ else:
+ actual[path] = None
+ except OSError as e:
+ raise RuntimeError(f'cannot read {path}: {e}')
+ return actual
+
+
+def _unified_diff(path, actual, expected):
+ """Unified diff actual → expected for one file, as a list of lines."""
+ a = (actual or '').splitlines()
+ b = (expected or '').splitlines()
+ return list(difflib.unified_diff(
+ a, b,
+ fromfile=f'{path} (actual)',
+ tofile=f'{path} (expected)',
+ lineterm='',
+ ))
+
+
+class DriftService:
+ """Detect + repair drift between DB-derived config and files on disk."""
+
+ # ------------------------------------------------------------------ #
+ # Detection
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def check_resource(cls, check, resource_id, name):
+ """Run one check against one resource. Returns a report entry."""
+ entry = {
+ 'type': check['type'],
+ 'id': resource_id,
+ 'name': name,
+ 'status': 'in_sync',
+ 'diff': None,
+ 'checked_at': datetime.utcnow().isoformat() + 'Z',
+ }
+ try:
+ expected = check['render_expected'](resource_id) or {}
+ if not expected:
+ # Nothing applies to this resource (e.g. app publishes no
+ # files) — by definition nothing can have drifted.
+ return entry
+ reader = check.get('read_actual') or _default_read_actual
+ actual = reader(list(expected.keys()))
+
+ diff_lines = []
+ statuses = set()
+ for path, want in expected.items():
+ have = actual.get(path)
+ if want is None:
+ # File must not exist.
+ if have is None:
+ statuses.add('in_sync')
+ else:
+ statuses.add('drifted')
+ diff_lines += _unified_diff(path, have, '')
+ elif have is None:
+ statuses.add('missing')
+ diff_lines += _unified_diff(path, '', want)
+ elif have == want:
+ statuses.add('in_sync')
+ else:
+ statuses.add('drifted')
+ diff_lines += _unified_diff(path, have, want)
+
+ if 'drifted' in statuses:
+ entry['status'] = 'drifted'
+ elif 'missing' in statuses:
+ entry['status'] = 'missing'
+ if diff_lines:
+ if len(diff_lines) > DIFF_MAX_LINES:
+ kept = diff_lines[:DIFF_MAX_LINES]
+ kept.append(
+ f'... (diff truncated at {DIFF_MAX_LINES} lines)')
+ diff_lines = kept
+ entry['diff'] = '\n'.join(diff_lines)
+ except Exception as e: # noqa: BLE001 — one bad resource must not kill the sweep
+ entry['status'] = 'error'
+ entry['detail'] = str(e)
+ return entry
+
+ @classmethod
+ def check_all(cls):
+ """Run every registered check against every resource.
+
+ Returns a list of entries ``{type, id, name, status, diff,
+ checked_at}`` with ``status`` in
+ ``in_sync | drifted | missing | error``.
+ """
+ results = []
+ for check in DRIFT_CHECKS.values():
+ supported = check.get('supported')
+ if supported:
+ ok, reason = supported()
+ if not ok:
+ results.append({
+ 'type': check['type'],
+ 'id': None,
+ 'name': check.get('title', check['type']),
+ 'status': 'error',
+ 'diff': None,
+ 'detail': reason or 'unsupported on this host',
+ 'checked_at': datetime.utcnow().isoformat() + 'Z',
+ })
+ continue
+ try:
+ resources = check['list_resources']()
+ except Exception as e: # noqa: BLE001
+ results.append({
+ 'type': check['type'],
+ 'id': None,
+ 'name': check.get('title', check['type']),
+ 'status': 'error',
+ 'diff': None,
+ 'detail': str(e),
+ 'checked_at': datetime.utcnow().isoformat() + 'Z',
+ })
+ continue
+ for resource_id, name in resources:
+ results.append(cls.check_resource(check, resource_id, name))
+ return results
+
+ # ------------------------------------------------------------------ #
+ # Last-report storage
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def build_report(cls):
+ results = cls.check_all()
+ return {
+ 'results': results,
+ 'drifted': sum(1 for r in results if r['status'] in ('drifted', 'missing')),
+ 'errors': sum(1 for r in results if r['status'] == 'error'),
+ 'generated_at': datetime.utcnow().isoformat() + 'Z',
+ }
+
+ @classmethod
+ def store_report(cls, report):
+ from app.services.settings_service import SettingsService
+ SettingsService.set(LAST_REPORT_KEY, json.dumps(report))
+
+ @classmethod
+ def get_last_report(cls):
+ from app.services.settings_service import SettingsService
+ raw = SettingsService.get(LAST_REPORT_KEY)
+ if not raw:
+ return None
+ try:
+ return json.loads(raw)
+ except (TypeError, ValueError):
+ return None
+
+ # ------------------------------------------------------------------ #
+ # Repair (explicit, per-resource — never automatic)
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def repair(cls, check_type, resource_id):
+ """Re-render + rewrite one resource through the panel's normal write
+ path (incl. nginx reload / compose up where applicable).
+
+ Returns ``{'success': bool, 'wrote': [paths], 'reloaded': bool}`` (plus
+ ``'error'`` on failure). Strictly on-demand.
+ """
+ check = DRIFT_CHECKS.get(check_type)
+ if not check:
+ return {'success': False, 'error': f'Unknown drift check type: {check_type}',
+ 'wrote': [], 'reloaded': False}
+ supported = check.get('supported')
+ if supported:
+ ok, reason = supported()
+ if not ok:
+ return {'success': False, 'error': reason or 'unsupported on this host',
+ 'wrote': [], 'reloaded': False}
+ repair_fn = check.get('repair')
+ if not repair_fn:
+ return {'success': False, 'error': f'{check_type} is not repairable',
+ 'wrote': [], 'reloaded': False}
+ try:
+ result = repair_fn(resource_id) or {}
+ except Exception as e: # noqa: BLE001 — surface as a clean error
+ return {'success': False, 'error': str(e), 'wrote': [], 'reloaded': False}
+ result.setdefault('success', False)
+ result.setdefault('wrote', [])
+ result.setdefault('reloaded', False)
+ return result
+
+ # ------------------------------------------------------------------ #
+ # Job plumbing
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def run_drift_check_job(cls, job):
+ """Job handler for ``drift.check``: sweep, store, notify on drift."""
+ report = cls.build_report()
+ cls.store_report(report)
+ if report['drifted'] > 0:
+ cls._notify_drift(report)
+ return {'drifted': report['drifted'], 'errors': report['errors'],
+ 'checked': len(report['results'])}
+
+ @classmethod
+ def _notify_drift(cls, report):
+ """Best-effort admin notification — never breaks the sweep."""
+ try:
+ from app.plugins_sdk import notify
+ names = [r['name'] for r in report['results']
+ if r['status'] in ('drifted', 'missing')]
+ summary = ', '.join(names[:5]) + ('…' if len(names) > 5 else '')
+ notify.send('drift.detected', to='admins', data={
+ 'count': report['drifted'],
+ 'resources': names,
+ 'message': (
+ f"{report['drifted']} managed configuration file(s) no longer match "
+ f"what ServerKit expects: {summary}. Review them on "
+ 'Monitoring → Doctor and repair the ones you did not change '
+ 'on purpose.'),
+ })
+ except Exception as e: # noqa: BLE001
+ logger.debug('drift notification failed: %s', e)
+
+ @classmethod
+ def register_jobs(cls):
+ """Register the drift sweep handler with the job registry.
+ Called once at app startup (see app/__init__.py)."""
+ from app.jobs import registry
+ registry.register(DRIFT_JOB_KIND, cls.run_drift_check_job, replace=True)
+
+
+# --------------------------------------------------------------------------- #
+# Built-in checks
+# --------------------------------------------------------------------------- #
+
+def _nginx_list_resources():
+ """Apps published via host nginx = apps that have Domain rows."""
+ from app.models.application import Application
+ from app.models.domain import Domain
+ rows = (Application.query
+ .join(Domain, Domain.application_id == Application.id)
+ .distinct()
+ .all())
+ return [(app.id, app.name) for app in rows]
+
+
+def _nginx_render_expected(app_id):
+ from app.models.application import Application
+ from app.services.nginx_service import NginxService
+ from app.services.site_domain_service import SiteDomainService
+
+ app = Application.query.get(app_id)
+ if app is None:
+ return {}
+ kwargs, warning = SiteDomainService.app_vhost_kwargs(app)
+ if kwargs is None:
+ if warning:
+ # App has domains but can't be published via host nginx — there is
+ # nothing the panel would have written, so nothing to compare.
+ logger.debug('drift: nginx vhost n/a for %s: %s', app.name, warning)
+ return {}
+ rendered = NginxService.render_site_config(**kwargs)
+ if not rendered.get('success'):
+ raise RuntimeError(rendered.get('error') or 'vhost render failed')
+ path = os.path.join(NginxService.SITES_AVAILABLE, app.name)
+ return {path: rendered['config']}
+
+
+def _nginx_repair(app_id):
+ from app.models.application import Application
+ from app.services.nginx_service import NginxService
+ from app.services.site_domain_service import SiteDomainService
+
+ app = Application.query.get(app_id)
+ if app is None:
+ return {'success': False, 'error': f'Application {app_id} not found'}
+ res = SiteDomainService.write_app_vhost(app)
+ if res.get('warning') and not (res.get('nginx') or {}).get('success'):
+ return {'success': False, 'error': res['warning']}
+ reload_res = NginxService.reload()
+ return {
+ 'success': True,
+ 'wrote': [os.path.join(NginxService.SITES_AVAILABLE, app.name)],
+ 'reloaded': bool(reload_res.get('success')),
+ 'warning': res.get('warning') or (None if reload_res.get('success')
+ else reload_res.get('error')),
+ }
+
+
+register_check({
+ 'type': 'nginx_vhost',
+ 'title': 'Nginx vhosts',
+ 'supported': _linux_only,
+ 'list_resources': _nginx_list_resources,
+ 'render_expected': _nginx_render_expected,
+ 'repair': _nginx_repair,
+})
+
+
+def _compose_list_resources():
+ """Managed apps that live in a project dir (candidate compose apps)."""
+ from app.models.application import Application
+ rows = Application.query.filter(Application.root_path.isnot(None)).all()
+ out = []
+ for app in rows:
+ try:
+ from app.services.compose_env_service import ComposeEnvService
+ if app.root_path and os.path.isdir(app.root_path) and \
+ ComposeEnvService.find_base_compose(app.root_path, app.compose_file):
+ out.append((app.id, app.name))
+ except Exception: # noqa: BLE001 — skip unreadable roots
+ continue
+ return out
+
+
+def _compose_render_expected(app_id):
+ from app.models.application import Application
+ from app.services.compose_env_service import ComposeEnvService
+
+ app = Application.query.get(app_id)
+ if app is None or not app.root_path:
+ return {}
+ spec = ComposeEnvService.render_override(app.root_path, app.compose_file)
+ if not spec['applies']:
+ return {}
+ # content None → the override must not exist (stale file = drift).
+ return {spec['path']: spec['content']}
+
+
+def _compose_repair(app_id):
+ from app.models.application import Application
+ from app.services.compose_env_service import ComposeEnvService
+ from app.services.docker_service import DockerService
+
+ app = Application.query.get(app_id)
+ if app is None:
+ return {'success': False, 'error': f'Application {app_id} not found'}
+ written = ComposeEnvService.refresh_for_project(app.root_path, app.compose_file)
+ # Apply the regenerated override the same way a deploy does.
+ up = DockerService.compose_up(app.root_path, detach=True,
+ compose_file=app.compose_file)
+ return {
+ 'success': True,
+ 'wrote': [written] if written else [],
+ 'reloaded': bool(up.get('success')),
+ 'warning': None if up.get('success') else up.get('error'),
+ }
+
+
+register_check({
+ 'type': 'compose_override',
+ 'title': 'Compose env overrides',
+ 'supported': _linux_only,
+ 'list_resources': _compose_list_resources,
+ 'render_expected': _compose_render_expected,
+ 'repair': _compose_repair,
+})
+
+# NOTE: no systemd unit check — see the module docstring. The panel-templated
+# gunicorn units (PythonService.create_gunicorn_service) render from inputs
+# that aren't persisted (workers/user/.env snapshot), so an expected render
+# can't be reproduced faithfully; everything else under /etc/systemd/system is
+# installer-owned.
diff --git a/backend/app/services/nginx_service.py b/backend/app/services/nginx_service.py
index f278bb2c..f8fb82f6 100644
--- a/backend/app/services/nginx_service.py
+++ b/backend/app/services/nginx_service.py
@@ -305,6 +305,60 @@ location = /wordpress {{
}}
'''
+ # ==================== MICRO-CACHE (task #21) ====================
+ # Opt-in per-site micro-cache: a very short (10s) full-page cache in front
+ # of proxied/PHP sites, with hard bypasses for anything personalized.
+ #
+ # Design tradeoff — ONE shared zone/path for every opted-in site: nginx
+ # cache zones must be declared statically in the http context, so a zone
+ # per site does not scale (and can't be added/removed without touching a
+ # global file per site). Consequence: a manual purge is a full-zone wipe
+ # that clears cached entries for ALL opted-in sites. That is acceptable
+ # because the TTL is only 10 seconds — the purge button exists for the
+ # "I need it gone *now*" case, not for cache hygiene. proxy_* and
+ # fastcgi_* caches cannot share a keys_zone, hence two zones over one
+ # base directory (both wiped together on purge).
+ MICROCACHE_CONF_NAME = 'serverkit-microcache.conf'
+ MICROCACHE_DIR = '/var/cache/nginx/serverkit-microcache'
+
+ MICROCACHE_ZONE_SNIPPET = '''# ServerKit micro-cache zones (auto-generated; do not edit).
+# One shared zone pair serves every site with micro-cache enabled — nginx
+# requires cache zones to be declared statically in the http context, so
+# per-site zones are not practical. Entries expire after 10s; a manual purge
+# wipes the whole directory (all opted-in sites).
+proxy_cache_path /var/cache/nginx/serverkit-microcache/proxy levels=1:2 keys_zone=serverkit_microcache:10m max_size=256m inactive=10m use_temp_path=off;
+fastcgi_cache_path /var/cache/nginx/serverkit-microcache/fastcgi levels=1:2 keys_zone=serverkit_microcache_php:10m max_size=256m inactive=10m use_temp_path=off;
+'''
+
+ # Server-level bypass logic, shared by the proxy and fastcgi variants.
+ # Cached responses are never stored/served for: non-GET/HEAD requests,
+ # requests with a query string (safer default), session/auth/cart cookies,
+ # or admin/login/cart paths.
+ MICROCACHE_SKIP_BLOCK = ''' # ServerKit micro-cache bypass (never cache personalized responses)
+ set $sk_skip_cache 0;
+ if ($request_method !~ ^(GET|HEAD)$) { set $sk_skip_cache 1; }
+ if ($query_string != "") { set $sk_skip_cache 1; }
+ if ($http_cookie ~* "wordpress_logged_in_|wp-postpass|woocommerce_cart_hash|woocommerce_items_in_cart|comment_author|PHPSESSID|session|auth") { set $sk_skip_cache 1; }
+ if ($request_uri ~* "^/(wp-admin|wp-login|admin|login|cart|checkout|my-account)") { set $sk_skip_cache 1; }
+'''
+
+ MICROCACHE_PROXY_BLOCK = ''' proxy_cache serverkit_microcache;
+ proxy_cache_valid 200 301 10s;
+ proxy_cache_use_stale updating error timeout;
+ proxy_cache_lock on;
+ proxy_no_cache $sk_skip_cache;
+ add_header X-SK-Cache $upstream_cache_status;
+'''
+
+ MICROCACHE_FASTCGI_BLOCK = ''' fastcgi_cache serverkit_microcache_php;
+ fastcgi_cache_valid 200 301 10s;
+ fastcgi_cache_use_stale updating error timeout;
+ fastcgi_cache_lock on;
+ fastcgi_cache_bypass $sk_skip_cache;
+ fastcgi_no_cache $sk_skip_cache;
+ add_header X-SK-Cache $upstream_cache_status;
+'''
+
PRIVATE_URL_MAIN_CONFIG = '''# ServerKit Private URL Routes
# This file is auto-generated. Do not edit manually.
# Generated at: {timestamp}
@@ -436,15 +490,19 @@ location /p/ {{
return config
@classmethod
- def create_site(cls, name: str, app_type: str, domains: List[str],
- root_path: str, port: int = None, php_version: str = '8.2',
- ssl_cert: str = None, ssl_key: str = None,
- upstream: str = None) -> Dict:
- """Create a new site configuration.
-
- When ``ssl_cert``/``ssl_key`` are given the generated vhost serves HTTPS
- (443) from that cert with an HTTP->HTTPS redirect — used to point managed
- subdomains at the base-domain wildcard cert.
+ def render_site_config(cls, name: str, app_type: str, domains: List[str],
+ root_path: str = None, port: int = None,
+ php_version: str = '8.2',
+ ssl_cert: str = None, ssl_key: str = None,
+ upstream: str = None,
+ micro_cache: bool = False) -> Dict:
+ """Render the vhost config for a site to a string — no side effects.
+
+ This is the exact template pipeline :meth:`create_site` writes to disk;
+ it is exposed separately so callers (e.g. drift detection) can compute
+ the expected on-disk content without touching the filesystem.
+ Returns ``{'success': True, 'config': str}`` or
+ ``{'success': False, 'error': msg}``.
"""
if not domains:
return {'success': False, 'error': 'At least one domain is required'}
@@ -504,9 +562,136 @@ location /p/ {{
else:
return {'success': False, 'error': f'Unknown app type: {app_type}'}
+ if micro_cache:
+ # Inject before the SSL wrap so the redirect server block (which
+ # also carries a server_name line) never receives cache directives.
+ config = cls._with_micro_cache(config, app_type)
+
if ssl_cert and ssl_key:
config = cls._with_ssl(config, domains_str, ssl_cert, ssl_key)
+ return {'success': True, 'config': config}
+
+ @classmethod
+ def _with_micro_cache(cls, config: str, app_type: str) -> str:
+ """Inject the shared-zone micro-cache directives into a rendered vhost.
+
+ fastcgi_cache for PHP-FPM-served sites, proxy_cache for reverse-proxied
+ ones; static sites are a no-op (files already come straight off disk).
+ Scheme-agnostic — nothing here depends on HTTP vs HTTPS. The referenced
+ zones are declared once in conf.d by :meth:`ensure_cache_zone`.
+ """
+ t = (app_type or '').lower()
+ if t in ('php', 'wordpress'):
+ anchor = ' include fastcgi_params;\n'
+ if anchor not in config:
+ return config
+ config = config.replace(anchor, anchor + cls.MICROCACHE_FASTCGI_BLOCK, 1)
+ elif t in ('flask', 'django', 'python', 'docker', 'remote'):
+ # proxy_cache_bypass may only be declared once per location, so
+ # fold $sk_skip_cache into the template's existing $http_upgrade
+ # bypass instead of adding a duplicate directive.
+ anchor = ' proxy_cache_bypass $http_upgrade;\n'
+ if anchor not in config:
+ return config
+ config = config.replace(
+ anchor,
+ ' proxy_cache_bypass $sk_skip_cache $http_upgrade;\n'
+ + cls.MICROCACHE_PROXY_BLOCK,
+ 1,
+ )
+ else:
+ return config
+
+ # Server-level $sk_skip_cache logic, right after server_name.
+ match = re.search(r'^( server_name [^;]+;\n)', config, re.MULTILINE)
+ if match:
+ config = config.replace(
+ match.group(1), match.group(1) + '\n' + cls.MICROCACHE_SKIP_BLOCK, 1)
+ return config
+
+ @classmethod
+ def ensure_cache_zone(cls) -> Dict:
+ """Write the shared micro-cache zone declaration to conf.d (idempotent).
+
+ The zone must live in the http context, so it is a conf.d snippet
+ written once — not part of any per-site vhost. Also pre-creates the
+ on-disk cache directories. Skips the write when the snippet on disk
+ already matches.
+ """
+ conf_path = os.path.join(cls.NGINX_CONF_DIR, 'conf.d', cls.MICROCACHE_CONF_NAME)
+ try:
+ if os.path.isfile(conf_path):
+ with open(conf_path, 'r') as f:
+ if f.read() == cls.MICROCACHE_ZONE_SNIPPET:
+ return {'success': True, 'changed': False, 'path': conf_path,
+ 'message': 'Micro-cache zone already configured'}
+ run_privileged(['mkdir', '-p',
+ os.path.join(cls.MICROCACHE_DIR, 'proxy'),
+ os.path.join(cls.MICROCACHE_DIR, 'fastcgi')])
+ process = run_privileged(['tee', conf_path], input=cls.MICROCACHE_ZONE_SNIPPET)
+ if process.returncode != 0:
+ return {'success': False, 'error': process.stderr}
+ return {'success': True, 'changed': True, 'path': conf_path,
+ 'message': 'Micro-cache zone configured'}
+ except Exception as e:
+ return {'success': False, 'error': str(e)}
+
+ @classmethod
+ def purge_micro_cache(cls) -> Dict:
+ """Wipe the shared micro-cache directory contents. Linux-only.
+
+ Full-zone wipe by design (see the tradeoff note at the MICROCACHE_*
+ constants): the zone is shared across all opted-in sites, and with a
+ 10s TTL a per-site purge buys almost nothing. nginx recreates cache
+ entries on demand — no reload needed.
+ """
+ if os.name == 'nt':
+ return {'success': False,
+ 'error': 'Micro-cache purge is only available on Linux hosts'}
+ try:
+ subdirs = [os.path.join(cls.MICROCACHE_DIR, d) for d in ('proxy', 'fastcgi')]
+ process = run_privileged(['rm', '-rf'] + subdirs)
+ if process.returncode != 0:
+ return {'success': False, 'error': process.stderr}
+ run_privileged(['mkdir', '-p'] + subdirs)
+ return {'success': True, 'message': 'Micro-cache cleared',
+ 'note': ('The micro-cache is one shared zone, so purging clears '
+ 'cached entries for every site that uses it. Entries '
+ 'expire within 10 seconds regardless.')}
+ except Exception as e:
+ return {'success': False, 'error': str(e)}
+
+ @classmethod
+ def create_site(cls, name: str, app_type: str, domains: List[str],
+ root_path: str = None, port: int = None, php_version: str = '8.2',
+ ssl_cert: str = None, ssl_key: str = None,
+ upstream: str = None, micro_cache: bool = False) -> Dict:
+ """Create a new site configuration.
+
+ When ``ssl_cert``/``ssl_key`` are given the generated vhost serves HTTPS
+ (443) from that cert with an HTTP->HTTPS redirect — used to point managed
+ subdomains at the base-domain wildcard cert. ``micro_cache`` opts the
+ site into the shared 10s micro-cache (the global zone snippet is
+ ensured first, since the vhost references it).
+ """
+ rendered = cls.render_site_config(
+ name, app_type, domains, root_path=root_path, port=port,
+ php_version=php_version, ssl_cert=ssl_cert, ssl_key=ssl_key,
+ upstream=upstream, micro_cache=micro_cache,
+ )
+ if not rendered.get('success'):
+ return rendered
+ config = rendered['config']
+
+ # The vhost references the shared cache zone — declare it (once)
+ # before the write so `nginx -t` on the next reload passes.
+ if micro_cache:
+ zone = cls.ensure_cache_zone()
+ if not zone.get('success'):
+ return {'success': False,
+ 'error': f"micro-cache zone setup failed: {zone.get('error')}"}
+
# Write config file
config_path = os.path.join(cls.SITES_AVAILABLE, name)
try:
diff --git a/backend/app/services/site_domain_service.py b/backend/app/services/site_domain_service.py
index 7ad5fa5e..bd55326b 100644
--- a/backend/app/services/site_domain_service.py
+++ b/backend/app/services/site_domain_service.py
@@ -400,7 +400,12 @@ class SiteDomainService:
says ``wordpress`` (whose stock template is php-fpm, not a proxy).
"""
t = (force_type or app.app_type or '').lower()
- base = dict(name=app.name, domains=domains, ssl_cert=ssl_cert, ssl_key=ssl_key)
+ # micro_cache rides in the shared kwargs so the write path
+ # (write_app_vhost -> create_site) and the drift re-render
+ # (app_vhost_kwargs -> render_site_config) always agree on it —
+ # an enabled cache must never show up as config drift.
+ base = dict(name=app.name, domains=domains, ssl_cert=ssl_cert, ssl_key=ssl_key,
+ micro_cache=bool(getattr(app, 'micro_cache_enabled', False)))
# Reverse-proxy to a local container/app port.
if t in ('docker', 'wordpress'):
if not app.port:
@@ -423,23 +428,21 @@ class SiteDomainService:
return None, f"app type '{t}' cannot be published via host nginx."
@classmethod
- def write_app_vhost(cls, app, force_type=None):
- """(Re)write and enable the host-nginx vhost publishing ``app`` at every
- one of its Domain rows (``server_name`` = all domains).
-
- Handles all host-nginx app types: docker/wordpress and
- python/flask/django reverse-proxy to the app's port; php/static serve a
- filesystem root. Serves a base's wildcard cert when every domain is a
- subdomain of that *same* base and its HTTPS is enabled (custom domains
- bring their own cert). Best-effort — never raises; returns ``{'nginx',
- 'warning'}`` (``nginx`` is ``None`` when nothing was written).
+ def app_vhost_kwargs(cls, app, force_type=None):
+ """Resolve ``app``'s Domain rows + wildcard-cert choice into the exact
+ ``NginxService.create_site(**kwargs)`` call :meth:`write_app_vhost`
+ makes. Extracted so drift detection can render the *expected* vhost
+ through the same pipeline without writing anything.
+
+ Returns ``(kwargs, warning)`` — ``(None, None)`` when the app has no
+ domains (nothing to publish), ``(None, reason)`` when it can't be
+ published via host nginx.
"""
from app.models.domain import Domain
- from app.services.nginx_service import NginxService
domains = [d.name for d in Domain.query.filter_by(application_id=app.id).all()]
if not domains:
- return {'nginx': None, 'warning': None}
+ return None, None
# Pick a wildcard cert only when all domains sit under one base (whichever
# base covers them) and that base has HTTPS set up.
@@ -448,9 +451,27 @@ class SiteDomainService:
if cover and cls.https_enabled(cover) and all(cls.covering_base(d) == cover for d in domains):
ssl_cert, ssl_key = cls.wildcard_cert_paths(cover)
- kwargs, reason = cls._vhost_create_kwargs(app, domains, ssl_cert, ssl_key, force_type)
+ return cls._vhost_create_kwargs(app, domains, ssl_cert, ssl_key, force_type)
+
+ @classmethod
+ def write_app_vhost(cls, app, force_type=None):
+ """(Re)write and enable the host-nginx vhost publishing ``app`` at every
+ one of its Domain rows (``server_name`` = all domains).
+
+ Handles all host-nginx app types: docker/wordpress and
+ python/flask/django reverse-proxy to the app's port; php/static serve a
+ filesystem root. Serves a base's wildcard cert when every domain is a
+ subdomain of that *same* base and its HTTPS is enabled (custom domains
+ bring their own cert). Best-effort — never raises; returns ``{'nginx',
+ 'warning'}`` (``nginx`` is ``None`` when nothing was written).
+ """
+ from app.services.nginx_service import NginxService
+
+ kwargs, reason = cls.app_vhost_kwargs(app, force_type)
if reason:
return {'nginx': None, 'warning': reason}
+ if kwargs is None:
+ return {'nginx': None, 'warning': None}
try:
res = NginxService.create_site(**kwargs)
diff --git a/backend/tests/test_drift_doctor.py b/backend/tests/test_drift_doctor.py
new file mode 100644
index 00000000..a8aef5a5
--- /dev/null
+++ b/backend/tests/test_drift_doctor.py
@@ -0,0 +1,536 @@
+"""Tests for drift detection/repair (drift_service), the doctor sweep
+(doctor_service), and the /api/v1/doctor contract."""
+import json
+
+import pytest
+
+from app.services import drift_service
+from app.services.drift_service import (
+ DIFF_MAX_LINES,
+ DRIFT_JOB_KIND,
+ DriftService,
+ LAST_REPORT_KEY as DRIFT_REPORT_KEY,
+)
+from app.services.doctor_service import (
+ DOCTOR_JOB_KIND,
+ DoctorService,
+ LAST_REPORT_KEY as DOCTOR_REPORT_KEY,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Fake drift check plumbing
+# --------------------------------------------------------------------------- #
+
+def make_fake_check(tmp_path, expected_by_id, repaired=None, check_type='fake'):
+ """A registry-shaped check whose expected content is table-driven and whose
+ 'actual' files live under tmp_path (the default reader reads real files)."""
+ def render_expected(rid):
+ spec = expected_by_id[rid]
+ if isinstance(spec, Exception):
+ raise spec
+ return {str(tmp_path / path): content for path, content in spec.items()}
+
+ def repair(rid):
+ wrote = []
+ for path, content in (expected_by_id[rid] or {}).items():
+ full = tmp_path / path
+ if content is None:
+ if full.exists():
+ full.unlink()
+ else:
+ full.write_text(content, encoding='utf-8')
+ wrote.append(str(full))
+ if repaired is not None:
+ repaired.append(rid)
+ return {'success': True, 'wrote': wrote, 'reloaded': True}
+
+ return {
+ 'type': check_type,
+ 'title': 'Fake check',
+ 'list_resources': lambda: [(rid, f'res-{rid}') for rid in expected_by_id],
+ 'render_expected': render_expected,
+ 'repair': repair,
+ }
+
+
+def fake_registry(monkeypatch):
+ """Swap the module registry for an empty one so builtin checks stay out."""
+ registry = {}
+ monkeypatch.setattr(drift_service, 'DRIFT_CHECKS', registry)
+ return registry
+
+
+# --------------------------------------------------------------------------- #
+# Detection
+# --------------------------------------------------------------------------- #
+
+def test_check_all_statuses(app, tmp_path, fake_registry):
+ (tmp_path / 'insync.conf').write_text('same\n', encoding='utf-8')
+ (tmp_path / 'drifted.conf').write_text('old\n', encoding='utf-8')
+ (tmp_path / 'stale.conf').write_text('should not exist\n', encoding='utf-8')
+
+ check = make_fake_check(tmp_path, {
+ 'a': {'insync.conf': 'same\n'},
+ 'b': {'drifted.conf': 'new\n'},
+ 'c': {'missing.conf': 'want\n'},
+ 'd': RuntimeError('boom'),
+ 'e': {'stale.conf': None}, # file must NOT exist -> drift
+ 'f': {}, # nothing applies -> in_sync
+ })
+ drift_service.register_check(check)
+
+ results = {r['id']: r for r in DriftService.check_all()}
+
+ assert results['a']['status'] == 'in_sync'
+ assert results['a']['diff'] is None
+
+ assert results['b']['status'] == 'drifted'
+ assert '-old' in results['b']['diff']
+ assert '+new' in results['b']['diff']
+
+ assert results['c']['status'] == 'missing'
+ assert '+want' in results['c']['diff']
+
+ assert results['d']['status'] == 'error'
+ assert 'boom' in results['d']['detail']
+
+ assert results['e']['status'] == 'drifted'
+ assert '-should not exist' in results['e']['diff']
+
+ assert results['f']['status'] == 'in_sync'
+
+ for r in results.values():
+ assert r['type'] == 'fake'
+ assert r['checked_at']
+ assert r['name'].startswith('res-')
+
+
+def test_diff_is_capped(app, tmp_path, fake_registry):
+ (tmp_path / 'big.conf').write_text(
+ '\n'.join(f'old-{i}' for i in range(500)), encoding='utf-8')
+ check = make_fake_check(tmp_path, {
+ 'big': {'big.conf': '\n'.join(f'new-{i}' for i in range(500))},
+ })
+ drift_service.register_check(check)
+
+ [result] = DriftService.check_all()
+
+ lines = result['diff'].splitlines()
+ assert len(lines) == DIFF_MAX_LINES + 1
+ assert 'truncated' in lines[-1]
+
+
+def test_unsupported_check_reports_clean_error(app, fake_registry):
+ drift_service.register_check({
+ 'type': 'linuxish',
+ 'title': 'Linux-only thing',
+ 'supported': lambda: (False, 'unsupported on this host'),
+ 'list_resources': lambda: [(1, 'x')],
+ 'render_expected': lambda rid: {'/nope': 'x'},
+ })
+
+ [result] = DriftService.check_all()
+
+ assert result['status'] == 'error'
+ assert result['detail'] == 'unsupported on this host'
+ assert result['id'] is None
+ assert result['name'] == 'Linux-only thing'
+
+
+def test_builtin_checks_are_registered():
+ # The real module registry (not the fake one) carries the two builtins.
+ assert 'nginx_vhost' in drift_service.DRIFT_CHECKS
+ assert 'compose_override' in drift_service.DRIFT_CHECKS
+
+
+# --------------------------------------------------------------------------- #
+# Repair
+# --------------------------------------------------------------------------- #
+
+def test_repair_writes_and_reports(app, tmp_path, fake_registry):
+ repaired = []
+ check = make_fake_check(tmp_path, {'r1': {'site.conf': 'fixed\n'}},
+ repaired=repaired)
+ drift_service.register_check(check)
+
+ result = DriftService.repair('fake', 'r1')
+
+ assert result['success'] is True
+ assert result['wrote'] == [str(tmp_path / 'site.conf')]
+ assert result['reloaded'] is True
+ assert repaired == ['r1']
+ assert (tmp_path / 'site.conf').read_text(encoding='utf-8') == 'fixed\n'
+
+ # Repaired resource now checks clean.
+ [entry] = [r for r in DriftService.check_all() if r['id'] == 'r1']
+ assert entry['status'] == 'in_sync'
+
+
+def test_repair_unknown_type_and_unrepairable(app, tmp_path, fake_registry):
+ unknown = DriftService.repair('nope', 1)
+ assert unknown['success'] is False
+ assert 'Unknown drift check type' in unknown['error']
+
+ check = make_fake_check(tmp_path, {'r1': {'x': 'y'}})
+ del check['repair']
+ drift_service.register_check(check)
+ result = DriftService.repair('fake', 'r1')
+ assert result['success'] is False
+ assert 'not repairable' in result['error']
+
+
+def test_repair_unsupported_platform(app, fake_registry):
+ drift_service.register_check({
+ 'type': 'gated',
+ 'title': 'Gated',
+ 'supported': lambda: (False, 'unsupported on this host'),
+ 'list_resources': lambda: [],
+ 'render_expected': lambda rid: {},
+ 'repair': lambda rid: {'success': True},
+ })
+ result = DriftService.repair('gated', 1)
+ assert result['success'] is False
+ assert result['error'] == 'unsupported on this host'
+
+
+# --------------------------------------------------------------------------- #
+# Job handler + notification
+# --------------------------------------------------------------------------- #
+
+class _JobStub:
+ def get_payload(self):
+ return {}
+
+
+def test_drift_job_stores_report_and_notifies(app, tmp_path, fake_registry, monkeypatch):
+ from app.services.settings_service import SettingsService
+ import app.plugins_sdk as sdk
+
+ (tmp_path / 'drifted.conf').write_text('old\n', encoding='utf-8')
+ drift_service.register_check(make_fake_check(tmp_path, {
+ 'b': {'drifted.conf': 'new\n'},
+ }))
+
+ sent = []
+ monkeypatch.setattr(sdk.notify, 'send',
+ lambda event, to, data=None, **kw: sent.append((event, to, data)))
+
+ summary = DriftService.run_drift_check_job(_JobStub())
+
+ assert summary == {'drifted': 1, 'errors': 0, 'checked': 1}
+ stored = json.loads(SettingsService.get(DRIFT_REPORT_KEY))
+ assert stored['drifted'] == 1
+ assert stored['results'][0]['status'] == 'drifted'
+
+ assert len(sent) == 1
+ event, to, data = sent[0]
+ assert event == 'drift.detected'
+ assert to == 'admins'
+ assert data['count'] == 1
+ assert 'res-b' in data['resources']
+
+
+def test_drift_job_no_notification_when_clean(app, tmp_path, fake_registry, monkeypatch):
+ import app.plugins_sdk as sdk
+
+ (tmp_path / 'insync.conf').write_text('same\n', encoding='utf-8')
+ drift_service.register_check(make_fake_check(tmp_path, {
+ 'a': {'insync.conf': 'same\n'},
+ }))
+
+ sent = []
+ monkeypatch.setattr(sdk.notify, 'send',
+ lambda *a, **kw: sent.append(a))
+
+ summary = DriftService.run_drift_check_job(_JobStub())
+
+ assert summary['drifted'] == 0
+ assert sent == []
+
+
+def test_drift_event_in_notification_catalog():
+ from app.notifications import catalog
+ entry = catalog.get('drift.detected')
+ assert entry is not None
+ assert entry['severity'] == 'warning'
+ assert entry['category'] == 'system'
+
+
+def test_register_jobs_registers_handlers(app):
+ from app.jobs import registry
+ DriftService.register_jobs()
+ DoctorService.register_jobs()
+ assert registry.get(DRIFT_JOB_KIND) is not None
+ assert registry.get(DOCTOR_JOB_KIND) is not None
+
+
+# --------------------------------------------------------------------------- #
+# Doctor sweep
+# --------------------------------------------------------------------------- #
+
+def _fixed_drift_results():
+ return [
+ {'type': 'fake', 'id': 1, 'name': 'clean-app', 'status': 'in_sync',
+ 'diff': None, 'checked_at': 'now'},
+ {'type': 'fake', 'id': 2, 'name': 'bad-app', 'status': 'drifted',
+ 'diff': '-a\n+b', 'checked_at': 'now'},
+ {'type': 'fake', 'id': None, 'name': 'Gated', 'status': 'error',
+ 'diff': None, 'detail': 'unsupported on this host', 'checked_at': 'now'},
+ ]
+
+
+def test_doctor_run_report_shape(app, monkeypatch):
+ from app.services.settings_service import SettingsService
+
+ monkeypatch.setattr(DriftService, 'check_all',
+ classmethod(lambda cls: _fixed_drift_results()))
+ monkeypatch.setattr(DoctorService, '_service_checks', classmethod(lambda cls: [
+ {'key': 'service.nginx', 'title': 'nginx service', 'status': 'fail',
+ 'detail': 'Not running.', 'repairable': True,
+ 'repair_ref': {'kind': 'service', 'name': 'nginx'}},
+ ]))
+
+ report = DoctorService.run()
+
+ assert report['ran_at']
+ checks = {c['key']: c for c in report['checks']}
+ # Drift entries.
+ assert checks['drift.fake.1']['status'] == 'ok'
+ assert checks['drift.fake.2']['status'] == 'warn'
+ assert checks['drift.fake.2']['repairable'] is True
+ assert checks['drift.fake.2']['repair_ref'] == {'kind': 'drift', 'type': 'fake', 'id': 2}
+ assert checks['drift.fake.2']['diff'] == '-a\n+b'
+ assert checks['drift.fake']['status'] == 'warn'
+ assert checks['drift.fake']['repairable'] is False
+ # Host probes are all present.
+ assert checks['service.nginx']['status'] == 'fail'
+ for key in ('certs.expiry', 'disk.headroom', 'db.reachable'):
+ assert key in checks
+ assert checks[key]['status'] in ('ok', 'warn', 'fail')
+ assert checks['db.reachable']['status'] == 'ok'
+ # Every check carries the full shape.
+ for c in report['checks']:
+ for field in ('key', 'title', 'status', 'detail', 'repairable', 'repair_ref'):
+ assert field in c
+
+ stored = json.loads(SettingsService.get(DOCTOR_REPORT_KEY))
+ assert stored['ran_at'] == report['ran_at']
+
+
+def test_doctor_cert_check_warns_on_near_expiry(app):
+ from datetime import datetime, timedelta
+ from werkzeug.security import generate_password_hash
+ from app import db
+ from app.models import User
+ from app.models.application import Application
+ from app.models.domain import Domain
+
+ user = User(email='[email protected]', username='certuser',
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_ADMIN, is_active=True)
+ db.session.add(user)
+ db.session.flush()
+ site = Application(name='certsite', app_type='static', user_id=user.id)
+ db.session.add(site)
+ db.session.flush()
+ db.session.add(Domain(name='soon.example.com', application_id=site.id,
+ ssl_expires_at=datetime.utcnow() + timedelta(days=5)))
+ db.session.commit()
+
+ check = DoctorService._cert_check()
+ assert check['status'] == 'warn'
+ assert 'soon.example.com' in check['detail']
+
+
+def test_doctor_batch_repair(app, monkeypatch):
+ calls = []
+ monkeypatch.setattr(
+ DriftService, 'repair',
+ classmethod(lambda cls, t, i: calls.append(('drift', t, i)) or
+ {'success': True, 'wrote': ['/x'], 'reloaded': True}))
+ monkeypatch.setattr(
+ DoctorService, '_restart_service',
+ classmethod(lambda cls, name: calls.append(('service', name)) or
+ {'success': True, 'restarted': name}))
+
+ results = DoctorService.repair([
+ {'kind': 'drift', 'type': 'nginx_vhost', 'id': 7},
+ {'kind': 'service', 'name': 'nginx'},
+ {'kind': 'wat'},
+ ])
+
+ assert calls == [('drift', 'nginx_vhost', 7), ('service', 'nginx')]
+ assert results[0]['success'] is True and results[0]['wrote'] == ['/x']
+ assert results[1]['success'] is True and results[1]['restarted'] == 'nginx'
+ assert results[2]['success'] is False
+ assert 'Unknown repair kind' in results[2]['error']
+
+
+def test_restart_service_rejects_unknown_service(app):
+ result = DoctorService._restart_service('sshd')
+ assert result['success'] is False
+ assert 'not repairable' in result['error']
+
+
+# --------------------------------------------------------------------------- #
+# API contract
+# --------------------------------------------------------------------------- #
+
+def doctor_client(app):
+ """Test client with the doctor blueprint mounted (registration in
+ app/__init__.py is wired separately)."""
+ from app.api.doctor import doctor_bp
+ if 'doctor' not in app.blueprints:
+ app.register_blueprint(doctor_bp, url_prefix='/api/v1/doctor')
+ return app.test_client()
+
+
+def viewer_headers(app):
+ """A non-admin (viewer) token, to prove admin-only enforcement."""
+ from app import db
+ from app.models import User
+ from flask_jwt_extended import create_access_token
+ from werkzeug.security import generate_password_hash
+
+ user = User(
+ email='[email protected]', username='vieweruser',
+ password_hash=generate_password_hash('testpass'),
+ role=User.ROLE_VIEWER, is_active=True,
+ )
+ db.session.add(user)
+ db.session.commit()
+ token = create_access_token(identity=user.id)
+ return {'Authorization': f'Bearer {token}'}
+
+
+def test_api_requires_auth(doctor_client):
+ assert doctor_client.get('/api/v1/doctor').status_code == 401
+ assert doctor_client.get('/api/v1/doctor/drift').status_code == 401
+ assert doctor_client.post('/api/v1/doctor/drift/check').status_code == 401
+ assert doctor_client.post('/api/v1/doctor/run').status_code == 401
+ assert doctor_client.post('/api/v1/doctor/repair').status_code == 401
+
+
+def test_api_requires_admin(doctor_client, viewer_headers):
+ resp = doctor_client.get('/api/v1/doctor', headers=viewer_headers)
+ assert resp.status_code == 403
+ assert 'error' in resp.get_json()
+ resp = doctor_client.post('/api/v1/doctor/run', headers=viewer_headers)
+ assert resp.status_code == 403
+
+
+def test_get_drift_report_null_then_value(doctor_client, auth_headers, app):
+ from app.services.settings_service import SettingsService
+
+ resp = doctor_client.get('/api/v1/doctor/drift', headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.get_json() == {'report': None}
+
+ report = {'results': [], 'drifted': 0, 'errors': 0, 'generated_at': 'x'}
+ SettingsService.set(DRIFT_REPORT_KEY, json.dumps(report))
+ resp = doctor_client.get('/api/v1/doctor/drift', headers=auth_headers)
+ assert resp.get_json() == {'report': report}
+
+
+def test_post_drift_check_enqueues(doctor_client, auth_headers, monkeypatch):
+ from app.jobs.service import JobService
+
+ class _FakeJob:
+ id = 'job-drift-1'
+
+ enqueued = []
+
+ def _fake_enqueue(kind, payload=None, max_attempts=3, **kwargs):
+ enqueued.append((kind, payload, max_attempts))
+ return _FakeJob()
+
+ monkeypatch.setattr(JobService, 'enqueue', staticmethod(_fake_enqueue))
+
+ resp = doctor_client.post('/api/v1/doctor/drift/check', headers=auth_headers)
+
+ assert resp.status_code == 202
+ assert resp.get_json() == {'job_id': 'job-drift-1'}
+ assert enqueued == [(DRIFT_JOB_KIND, {}, 1)]
+
+
+def test_drift_repair_requires_confirm(doctor_client, auth_headers):
+ resp = doctor_client.post('/api/v1/doctor/drift/nginx_vhost/1/repair',
+ headers=auth_headers, json={})
+ assert resp.status_code == 400
+ assert 'error' in resp.get_json()
+
+ resp = doctor_client.post('/api/v1/doctor/drift/nginx_vhost/1/repair',
+ headers=auth_headers, json={'confirm': 'yes'})
+ assert resp.status_code == 400
+
+
+def test_drift_repair_with_confirm(doctor_client, auth_headers, monkeypatch):
+ calls = []
+ monkeypatch.setattr(
+ DriftService, 'repair',
+ classmethod(lambda cls, t, i: calls.append((t, i)) or
+ {'success': True, 'wrote': ['/etc/nginx/sites-available/blog'],
+ 'reloaded': True}))
+
+ resp = doctor_client.post('/api/v1/doctor/drift/nginx_vhost/7/repair',
+ headers=auth_headers, json={'confirm': True})
+
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['success'] is True
+ assert body['wrote'] == ['/etc/nginx/sites-available/blog']
+ assert body['reloaded'] is True
+ assert calls == [('nginx_vhost', 7)] # numeric ids are cast to int
+
+
+def test_get_doctor_report_null_then_value(doctor_client, auth_headers, app):
+ from app.services.settings_service import SettingsService
+
+ resp = doctor_client.get('/api/v1/doctor', headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.get_json() == {'report': None}
+
+ report = {'checks': [], 'ran_at': 'x'}
+ SettingsService.set(DOCTOR_REPORT_KEY, json.dumps(report))
+ resp = doctor_client.get('/api/v1/doctor', headers=auth_headers)
+ assert resp.get_json() == {'report': report}
+
+
+def test_post_run_is_synchronous(doctor_client, auth_headers, monkeypatch):
+ fixed = {'checks': [{'key': 'db.reachable', 'title': 'Database',
+ 'status': 'ok', 'detail': 'Reachable.',
+ 'repairable': False, 'repair_ref': None}],
+ 'ran_at': '2026-07-03T00:00:00Z'}
+ monkeypatch.setattr(DoctorService, 'run', classmethod(lambda cls: fixed))
+
+ resp = doctor_client.post('/api/v1/doctor/run', headers=auth_headers)
+
+ assert resp.status_code == 200
+ assert resp.get_json() == {'report': fixed}
+
+
+def test_post_repair_batch(doctor_client, auth_headers, monkeypatch):
+ monkeypatch.setattr(
+ DoctorService, 'repair',
+ classmethod(lambda cls, items: [{'item': i, 'success': True} for i in items]))
+
+ items = [{'kind': 'drift', 'type': 'fake', 'id': 1},
+ {'kind': 'service', 'name': 'nginx'}]
+ resp = doctor_client.post('/api/v1/doctor/repair',
+ headers=auth_headers, json={'items': items})
+
+ assert resp.status_code == 200
+ assert resp.get_json() == {'results': [{'item': items[0], 'success': True},
+ {'item': items[1], 'success': True}]}
+
+
+def test_post_repair_requires_items(doctor_client, auth_headers):
+ resp = doctor_client.post('/api/v1/doctor/repair', headers=auth_headers, json={})
+ assert resp.status_code == 400
+ resp = doctor_client.post('/api/v1/doctor/repair', headers=auth_headers,
+ json={'items': []})
+ assert resp.status_code == 400
diff --git a/frontend/src/components/monitoring/DoctorPanel.jsx b/frontend/src/components/monitoring/DoctorPanel.jsx
new file mode 100644
index 00000000..18673de4
--- /dev/null
+++ b/frontend/src/components/monitoring/DoctorPanel.jsx
@@ -0,0 +1,199 @@
+import { useEffect, useState } from 'react';
+import api from '../../services/api';
+import { useToast } from '../../contexts/ToastContext';
+import { Button } from '@/components/ui/button';
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogTitle,
+} from '@/components/ui/dialog';
+import { Pill } from '@/components/ds';
+import EmptyState from '../EmptyState';
+import { ChevronDown, ChevronRight, Stethoscope, Wrench } from 'lucide-react';
+
+const STATUS_TONE = { ok: 'green', warn: 'amber', fail: 'red' };
+
+function formatRanAt(ranAt) {
+ if (!ranAt) return null;
+ return new Date(ranAt).toLocaleString();
+}
+
+const DoctorPanel = () => {
+ const toast = useToast();
+ const [report, setReport] = useState(null);
+ const [loading, setLoading] = useState(true);
+ const [running, setRunning] = useState(false);
+ const [repairing, setRepairing] = useState(false);
+ const [expanded, setExpanded] = useState({});
+ // { items: [repair_ref...], title, diff } — pending confirmation.
+ const [confirm, setConfirm] = useState(null);
+
+ useEffect(() => {
+ let cancelled = false;
+ api.getDoctorReport()
+ .then((res) => { if (!cancelled) setReport(res.report); })
+ .catch(() => { /* no stored report yet — the empty state covers it */ })
+ .finally(() => { if (!cancelled) setLoading(false); });
+ return () => { cancelled = true; };
+ }, []);
+
+ const runDiagnosis = async () => {
+ try {
+ setRunning(true);
+ const res = await api.runDoctor();
+ setReport(res.report);
+ const bad = (res.report?.checks || []).filter((c) => c.status !== 'ok').length;
+ toast[bad > 0 ? 'warning' : 'success'](
+ bad > 0 ? `Diagnosis finished — ${bad} finding${bad !== 1 ? 's' : ''}` : 'Diagnosis finished — all clear'
+ );
+ } catch (err) {
+ toast.error(err.message || 'Diagnosis failed');
+ } finally {
+ setRunning(false);
+ }
+ };
+
+ const doRepair = async (items) => {
+ try {
+ setRepairing(true);
+ const res = await api.repairDoctorItems(items);
+ const failed = (res.results || []).filter((r) => !r.success);
+ if (failed.length > 0) {
+ toast.error(`${failed.length} repair${failed.length !== 1 ? 's' : ''} failed — ${failed[0].error || 'see report'}`);
+ } else {
+ toast.success(`Repaired ${items.length} item${items.length !== 1 ? 's' : ''}`);
+ }
+ // Re-diagnose so the list reflects the new on-disk state.
+ const fresh = await api.runDoctor();
+ setReport(fresh.report);
+ } catch (err) {
+ toast.error(err.message || 'Repair failed');
+ } finally {
+ setRepairing(false);
+ setConfirm(null);
+ }
+ };
+
+ const checks = report?.checks || [];
+ const repairable = checks.filter((c) => c.repairable && c.repair_ref);
+
+ const toggleDiff = (key) => {
+ setExpanded((cur) => ({ ...cur, [key]: !cur[key] }));
+ };
+
+ return (
+ <div className="doctor-panel">
+ <section className="monitoring-panel">
+ <div className="monitoring-panel__header">
+ <h3>Server Doctor</h3>
+ <div className="doctor-panel__actions">
+ {repairable.length > 0 && (
+ <Button
+ size="sm"
+ variant="outline"
+ disabled={repairing || running}
+ onClick={() => setConfirm({
+ items: repairable.map((c) => c.repair_ref),
+ title: `Repair all ${repairable.length} repairable items?`,
+ diff: null,
+ })}
+ >
+ <Wrench size={14} />
+ Repair all ({repairable.length})
+ </Button>
+ )}
+ <Button size="sm" onClick={runDiagnosis} disabled={running || repairing}>
+ <Stethoscope size={14} />
+ {running ? 'Diagnosing...' : 'Run diagnosis'}
+ </Button>
+ </div>
+ </div>
+
+ <p className="doctor-panel__blurb">
+ One sweep across managed configuration drift, core services, certificates,
+ disk headroom and the database. Nothing is repaired automatically — every
+ fix is a button you press.
+ {report?.ran_at && <span className="doctor-panel__ranat"> Last run {formatRanAt(report.ran_at)}.</span>}
+ </p>
+
+ {loading ? (
+ <EmptyState loading title="Loading last report" />
+ ) : checks.length === 0 ? (
+ <EmptyState
+ icon={Stethoscope}
+ title="No diagnosis yet"
+ description="Run a diagnosis to check this server's managed configuration and core health."
+ />
+ ) : (
+ <div className="doctor-check-list">
+ {checks.map((check) => (
+ <article key={check.key} className={`doctor-check doctor-check--${check.status}`}>
+ <div className="doctor-check__row">
+ <Pill kind={STATUS_TONE[check.status] || 'gray'}>{check.status}</Pill>
+ <div className="doctor-check__body">
+ <span className="doctor-check__title">{check.title}</span>
+ <span className="doctor-check__detail">{check.detail}</span>
+ </div>
+ {check.diff && (
+ <Button
+ size="sm"
+ variant="ghost"
+ className="doctor-check__difftoggle"
+ onClick={() => toggleDiff(check.key)}
+ >
+ {expanded[check.key] ? <ChevronDown size={14} /> : <ChevronRight size={14} />}
+ diff
+ </Button>
+ )}
+ {check.repairable && check.repair_ref && (
+ <Button
+ size="sm"
+ variant="outline"
+ disabled={repairing || running}
+ onClick={() => setConfirm({
+ items: [check.repair_ref],
+ title: `Repair "${check.title}"?`,
+ diff: check.diff || null,
+ })}
+ >
+ <Wrench size={13} />
+ Repair
+ </Button>
+ )}
+ </div>
+ {check.diff && expanded[check.key] && (
+ <pre className="doctor-diff">{check.diff}</pre>
+ )}
+ </article>
+ ))}
+ </div>
+ )}
+ </section>
+
+ <Dialog open={Boolean(confirm)} onOpenChange={(open) => { if (!open) setConfirm(null); }}>
+ <DialogContent className="doctor-confirm">
+ <DialogTitle>{confirm?.title}</DialogTitle>
+ <DialogDescription>
+ This rewrites the managed file(s) from ServerKit&apos;s configuration and
+ reloads the affected service. Manual edits to those files will be lost.
+ </DialogDescription>
+ {confirm?.diff && (
+ <pre className="doctor-diff doctor-diff--modal">{confirm.diff}</pre>
+ )}
+ <div className="doctor-confirm__actions">
+ <Button variant="outline" onClick={() => setConfirm(null)} disabled={repairing}>
+ Cancel
+ </Button>
+ <Button onClick={() => doRepair(confirm.items)} disabled={repairing}>
+ <Wrench size={14} />
+ {repairing ? 'Repairing...' : 'Repair'}
+ </Button>
+ </div>
+ </DialogContent>
+ </Dialog>
+ </div>
+ );
+};
+
+export default DoctorPanel;
diff --git a/frontend/src/pages/Monitoring.jsx b/frontend/src/pages/Monitoring.jsx
index 4322131c..c92a4b38 100644
--- a/frontend/src/pages/Monitoring.jsx
+++ b/frontend/src/pages/Monitoring.jsx
@@ -5,6 +5,7 @@ import api from '../services/api';
import { formatBytes } from '@/utils/formatBytes';
import { useToast } from '../contexts/ToastContext';
import EmptyState from '../components/EmptyState';
+import DoctorPanel from '../components/monitoring/DoctorPanel';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
@@ -32,7 +33,7 @@ import {
Zap,
} from 'lucide-react';
-const VALID_TABS = ['overview', 'alerts', 'config', 'thresholds'];
+const VALID_TABS = ['overview', 'alerts', 'config', 'thresholds', 'doctor'];
const DEFAULT_THRESHOLDS = {
cpu_percent: 80,
@@ -389,6 +390,7 @@ const Monitoring = () => {
<TabsTrigger value="thresholds">Alert Rules</TabsTrigger>
<TabsTrigger value="config">Delivery</TabsTrigger>
<TabsTrigger value="alerts">History</TabsTrigger>
+ <TabsTrigger value="doctor">Doctor</TabsTrigger>
</TabsList>
<TabsContent value="overview">
@@ -702,6 +704,10 @@ const Monitoring = () => {
)}
</section>
</TabsContent>
+
+ <TabsContent value="doctor">
+ <DoctorPanel />
+ </TabsContent>
</Tabs>
</div>
);
diff --git a/frontend/src/services/api/doctor.js b/frontend/src/services/api/doctor.js
new file mode 100644
index 00000000..7c691ea3
--- /dev/null
+++ b/frontend/src/services/api/doctor.js
@@ -0,0 +1,32 @@
+// Doctor / drift API — health sweep + configuration drift surface
+// (Monitoring → Doctor tab). Admin-only endpoints under /api/v1/doctor.
+
+export async function getDoctorReport() {
+ return this.request('/doctor');
+}
+
+export async function runDoctor() {
+ return this.request('/doctor/run', { method: 'POST' });
+}
+
+export async function repairDoctorItems(items) {
+ return this.request('/doctor/repair', {
+ method: 'POST',
+ body: JSON.stringify({ items }),
+ });
+}
+
+export async function getDriftReport() {
+ return this.request('/doctor/drift');
+}
+
+export async function runDriftCheck() {
+ return this.request('/doctor/drift/check', { method: 'POST' });
+}
+
+export async function repairDrift(type, id) {
+ return this.request(`/doctor/drift/${type}/${id}/repair`, {
+ method: 'POST',
+ body: JSON.stringify({ confirm: true }),
+ });
+}
diff --git a/frontend/src/styles/pages/_doctor.scss b/frontend/src/styles/pages/_doctor.scss
new file mode 100644
index 00000000..90242b71
--- /dev/null
+++ b/frontend/src/styles/pages/_doctor.scss
@@ -0,0 +1,110 @@
+// ============================================
+// DOCTOR TAB (Monitoring → Doctor)
+// One-shot health sweep: check list + drift diffs + explicit repairs.
+// NOTE: imported from main.scss (wired by the orchestrator).
+// ============================================
+
+.doctor-panel {
+ display: grid;
+ gap: $space-5;
+
+ &__actions {
+ display: flex;
+ align-items: center;
+ gap: $space-2;
+ }
+
+ &__blurb {
+ margin: 0 0 $space-4;
+ font-size: 12.5px;
+ line-height: 1.5;
+ color: var(--text-dim);
+ max-width: 68ch;
+ }
+
+ &__ranat {
+ color: var(--text-faint);
+ }
+}
+
+.doctor-check-list {
+ display: grid;
+ gap: $space-2;
+}
+
+.doctor-check {
+ border: 1px solid var(--border-soft);
+ border-radius: var(--radius);
+ background: var(--surface);
+ padding: $space-3 $space-4;
+
+ &--warn {
+ border-color: rgba(245, 179, 66, 0.3);
+ }
+
+ &--fail {
+ border-color: rgba(240, 82, 82, 0.35);
+ }
+
+ &__row {
+ display: flex;
+ align-items: center;
+ gap: $space-3;
+ }
+
+ &__body {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ min-width: 0;
+ flex: 1;
+ }
+
+ &__title {
+ font-size: 13px;
+ font-weight: $font-weight-semibold;
+ color: var(--text);
+ }
+
+ &__detail {
+ font-size: 12px;
+ color: var(--text-dim);
+ overflow-wrap: anywhere;
+ }
+
+ // Rendered as a ghost Button — just tighten it to a mono affordance.
+ &__difftoggle {
+ font-family: var(--mono);
+ font-size: 11px;
+ color: var(--text-dim);
+ }
+}
+
+// Unified diff viewer — monospace pre, collapsed by default (toggle-rendered).
+.doctor-diff {
+ margin: $space-3 0 0;
+ padding: $space-3;
+ border: 1px solid var(--border-soft);
+ border-radius: var(--radius);
+ background: var(--surface-2);
+ font-family: var(--mono);
+ font-size: 11.5px;
+ line-height: 1.5;
+ color: var(--text-dim);
+ max-height: 320px;
+ overflow: auto;
+ white-space: pre;
+
+ &--modal {
+ max-height: 220px;
+ }
+}
+
+.doctor-confirm {
+ &__actions {
+ display: flex;
+ justify-content: flex-end;
+ gap: $space-2;
+ margin-top: $space-4;
+ }
+}