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.

fix(recovery): restore agent scopes, DNS preflight, catalog events, thread guards

Juan Denisea07a1ec14d6
diff --git a/backend/app/api/servers.py b/backend/app/api/servers.py
index f0e28d6d..08da1953 100644
--- a/backend/app/api/servers.py
+++ b/backend/app/api/servers.py
@@ -112,6 +112,11 @@ PERMISSION_PROFILES = {
'docker:volume:read',
'docker:network:read',
'system:metrics:read',
+ # Fleet doctor / survey reads (plan 28 #7): let the panel probe
+ # host health without granting any mutating verb.
+ 'doctor:read',
+ 'systemd:read',
+ 'survey:read',
]
},
'docker_manager': {
@@ -125,6 +130,9 @@ PERMISSION_PROFILES = {
'docker:network:*',
'system:metrics:read',
'system:logs:read',
+ 'doctor:read',
+ 'systemd:read',
+ 'survey:read',
]
},
'deployment_runner': {
@@ -141,6 +149,9 @@ PERMISSION_PROFILES = {
'file:list',
'system:metrics:read',
'system:logs:read',
+ 'doctor:read',
+ 'systemd:read',
+ 'survey:read',
]
},
'full_access': {
diff --git a/backend/app/middleware/api_analytics.py b/backend/app/middleware/api_analytics.py
index aee428d9..e3aa3d72 100644
--- a/backend/app/middleware/api_analytics.py
+++ b/backend/app/middleware/api_analytics.py
@@ -73,7 +73,14 @@ def register_api_analytics(app):
def start_analytics_flush_thread(app):
- """Start background thread to flush analytics buffer to DB."""
+ """Start background thread to flush analytics buffer to DB.
+
+ Skipped under testing: the app fixture is function-scoped, so an
+ unconditional per-create_app() flusher would leak one immortal writer per
+ test and race the suite's shared database (mirrors the queue-bus consumers).
+ """
+ if app.config.get('ENV') == 'testing' or app.config.get('TESTING'):
+ return None
def flush_loop():
while True:
diff --git a/backend/app/models/server.py b/backend/app/models/server.py
index 32ebbfe0..1e29748f 100644
--- a/backend/app/models/server.py
+++ b/backend/app/models/server.py
@@ -340,8 +340,24 @@ class Server(db.Model):
'read', 'get', 'inspect', 'status', 'info',
'search', 'logs', 'stats', 'available',
'installed', 'current', 'show',
+ # Fleet doctor / survey probes are Observed-safe reads (plan 28 #7):
+ # they only discover host state, so they classify as reads and expand
+ # to `<ns>:read` rather than `<ns>:write`.
+ 'probe', 'survey',
}
+ @classmethod
+ def is_read_action(cls, action):
+ """Return True when an agent action is a non-mutating read.
+
+ Classified purely by the leaf verb: ``doctor:probe`` / ``systemd:status``
+ are reads (Observed-safe), while ``cron:update`` / ``systemd:restart``
+ are mutating. Used by the fleet doctor to decide whether a command may
+ run under the Observed (read-only) trust level.
+ """
+ parts = action.split(':')
+ return bool(parts) and parts[-1] in cls.READ_ACTION_VERBS
+
@classmethod
def _expand_permission_scope(cls, scope):
"""Add profile and legacy aliases for an agent command scope."""
diff --git a/backend/app/notifications/catalog.py b/backend/app/notifications/catalog.py
index 4fab0ad8..191bf3be 100644
--- a/backend/app/notifications/catalog.py
+++ b/backend/app/notifications/catalog.py
@@ -41,6 +41,32 @@ _CATALOG = {
'severity': 'critical',
'category': 'backups',
},
+ # Restore-proof edge alerts (plan 23 #17): fire once on a state transition
+ # when a restore drill or backup verification starts failing / recovers.
+ 'backup.drill_failed': {
+ 'title': 'Restore drill failed: {target}',
+ 'template': 'generic',
+ 'severity': 'critical',
+ 'category': 'backups',
+ },
+ 'backup.drill_recovered': {
+ 'title': 'Restore drills passing again: {target}',
+ 'template': 'generic',
+ 'severity': 'success',
+ 'category': 'backups',
+ },
+ 'backup.verify_failed': {
+ 'title': 'Backup verification failed: {target}',
+ 'template': 'generic',
+ 'severity': 'critical',
+ 'category': 'backups',
+ },
+ 'backup.verify_recovered': {
+ 'title': 'Backups verifying cleanly again: {target}',
+ 'template': 'generic',
+ 'severity': 'success',
+ 'category': 'backups',
+ },
# --- security ---
'security.alert': {
'title': 'Security alert: {alert_type}',
diff --git a/backend/app/plugins/serverkit-email/__init__.py b/backend/app/plugins/serverkit-email/__init__.py
deleted file mode 100644
index 51e67b6d..00000000
--- a/backend/app/plugins/serverkit-email/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-"""ServerKit Email extension backend package."""
diff --git a/backend/app/plugins/serverkit-email/plugin.json b/backend/app/plugins/serverkit-email/plugin.json
deleted file mode 100644
index 5d38180a..00000000
--- a/backend/app/plugins/serverkit-email/plugin.json
+++ /dev/null
@@ -1,51 +0,0 @@
-{
- "name": "serverkit-email",
- "display_name": "Email Server",
- "version": "1.0.0",
- "description": "Full mail-server stack — Postfix/Dovecot, domains, mailboxes, aliases, DKIM/SPF/DMARC, SpamAssassin filtering, and Roundcube webmail. Most panels never run a mail server, so it ships as an opt-in extension.",
- "author": "ServerKit",
- "license": "MIT",
- "category": "integration",
- "homepage": "https://github.com/jhd3197/ServerKit",
- "permissions": [
- "shell",
- "filesystem",
- "network"
- ],
- "min_panel_version": "1.7.0",
- "entry_point": "email:email_bp",
- "url_prefix": "/api/v1/email",
- "icon": "<path d=\"M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z\"/><polyline points=\"22,6 12,13 2,6\"/>",
- "contributions": {
- "nav": [
- {
- "id": "email",
- "label": "Email Server",
- "route": "/email",
- "category": "operations",
- "icon": "<path d=\"M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z\"/><polyline points=\"22,6 12,13 2,6\"/>"
- }
- ],
- "routes": [
- {
- "path": "email",
- "component": "EmailPage"
- },
- {
- "path": "email/:tab",
- "component": "EmailPage"
- }
- ],
- "page_titles": {
- "/email": "Email Server"
- },
- "command_palette": [
- {
- "label": "Email",
- "path": "/email",
- "category": "Pages",
- "keywords": "smtp postfix dovecot mail imap dkim webmail"
- }
- ]
- }
-}
diff --git a/backend/app/plugins/serverkit-email/roundcube_service.py b/backend/app/plugins/serverkit-email/roundcube_service.py
deleted file mode 100644
index 85c93253..00000000
--- a/backend/app/plugins/serverkit-email/roundcube_service.py
+++ /dev/null
@@ -1,213 +0,0 @@
-"""Roundcube webmail management service (Docker-based)."""
-import subprocess
-from typing import Dict
-
-from app.utils.system import run_privileged, is_command_available
-
-
-class RoundcubeService:
- """Service for managing Roundcube webmail via Docker."""
-
- CONTAINER_NAME = 'serverkit-roundcube'
- VOLUME_NAME = 'roundcube_data'
- IMAGE = 'roundcube/roundcubemail:latest'
- HOST_PORT = 9000
-
- @classmethod
- def get_status(cls) -> Dict:
- """Get Roundcube container status."""
- if not is_command_available('docker'):
- return {'installed': False, 'running': False, 'error': 'Docker not available'}
-
- try:
- result = subprocess.run(
- ['docker', 'inspect', '--format', '{{.State.Status}}', cls.CONTAINER_NAME],
- capture_output=True, text=True,
- )
- if result.returncode != 0:
- return {'installed': False, 'running': False}
-
- status = result.stdout.strip()
- return {
- 'installed': True,
- 'running': status == 'running',
- 'status': status,
- 'port': cls.HOST_PORT,
- }
- except Exception as e:
- return {'installed': False, 'running': False, 'error': str(e)}
-
- @classmethod
- def install(cls, imap_host: str = 'host.docker.internal',
- smtp_host: str = 'host.docker.internal',
- domain: str = None) -> Dict:
- """Install Roundcube via Docker container."""
- if not is_command_available('docker'):
- return {'success': False, 'error': 'Docker is not installed'}
-
- try:
- # Remove existing container if any
- subprocess.run(
- ['docker', 'rm', '-f', cls.CONTAINER_NAME],
- capture_output=True, text=True,
- )
-
- # Create volume
- subprocess.run(
- ['docker', 'volume', 'create', cls.VOLUME_NAME],
- capture_output=True, text=True,
- )
-
- # Run container
- result = subprocess.run([
- 'docker', 'run', '-d',
- '--name', cls.CONTAINER_NAME,
- '--restart', 'unless-stopped',
- '--add-host', 'host.docker.internal:host-gateway',
- '-p', f'{cls.HOST_PORT}:80',
- '-e', f'ROUNDCUBEMAIL_DEFAULT_HOST=ssl://{imap_host}',
- '-e', f'ROUNDCUBEMAIL_SMTP_SERVER=tls://{smtp_host}',
- '-e', 'ROUNDCUBEMAIL_DEFAULT_PORT=993',
- '-e', 'ROUNDCUBEMAIL_SMTP_PORT=587',
- '-e', 'ROUNDCUBEMAIL_UPLOAD_MAX_FILESIZE=25M',
- '-e', 'ROUNDCUBEMAIL_SKIN=elastic',
- '-v', f'{cls.VOLUME_NAME}:/var/roundcube/db',
- cls.IMAGE,
- ], capture_output=True, text=True)
-
- if result.returncode != 0:
- return {'success': False, 'error': result.stderr or 'Failed to start container'}
-
- # Build a public URL: prefer a supplied domain, then auto-generate
- # webmail.<panel_domain>, and only fall back to localhost:port.
- from app.services.site_domain_service import SiteDomainService
- public_url = None
- warning = None
- if domain:
- public_url = f'http://{domain}'
- proxy_res = cls.configure_nginx_proxy(domain)
- if not proxy_res.get('success'):
- warning = proxy_res.get('error')
- else:
- panel_origin = SiteDomainService.panel_origin()
- panel_host = None
- if panel_origin:
- from urllib.parse import urlparse
- panel_host = urlparse(panel_origin).hostname
- if panel_host:
- webmail_domain = f'webmail.{panel_host}'
- public_url = f'http://{webmail_domain}'
- proxy_res = cls.configure_nginx_proxy(webmail_domain)
- if not proxy_res.get('success'):
- warning = proxy_res.get('error')
-
- if not public_url:
- public_url = f'http://localhost:{cls.HOST_PORT}'
-
- result = {
- 'success': True,
- 'message': 'Roundcube installed successfully',
- 'port': cls.HOST_PORT,
- 'url': public_url,
- }
- if warning:
- result['warning'] = warning
- return result
- except Exception as e:
- return {'success': False, 'error': str(e)}
-
- @classmethod
- def uninstall(cls) -> Dict:
- """Stop and remove Roundcube container."""
- try:
- subprocess.run(['docker', 'rm', '-f', cls.CONTAINER_NAME], capture_output=True, text=True)
- return {'success': True, 'message': 'Roundcube uninstalled'}
- except Exception as e:
- return {'success': False, 'error': str(e)}
-
- @classmethod
- def start(cls) -> Dict:
- """Start Roundcube container."""
- try:
- result = subprocess.run(
- ['docker', 'start', cls.CONTAINER_NAME],
- capture_output=True, text=True,
- )
- if result.returncode == 0:
- return {'success': True, 'message': 'Roundcube started'}
- return {'success': False, 'error': result.stderr or 'Start failed'}
- except Exception as e:
- return {'success': False, 'error': str(e)}
-
- @classmethod
- def stop(cls) -> Dict:
- """Stop Roundcube container."""
- try:
- result = subprocess.run(
- ['docker', 'stop', cls.CONTAINER_NAME],
- capture_output=True, text=True,
- )
- if result.returncode == 0:
- return {'success': True, 'message': 'Roundcube stopped'}
- return {'success': False, 'error': result.stderr or 'Stop failed'}
- except Exception as e:
- return {'success': False, 'error': str(e)}
-
- @classmethod
- def restart(cls) -> Dict:
- """Restart Roundcube container."""
- try:
- result = subprocess.run(
- ['docker', 'restart', cls.CONTAINER_NAME],
- capture_output=True, text=True,
- )
- if result.returncode == 0:
- return {'success': True, 'message': 'Roundcube restarted'}
- return {'success': False, 'error': result.stderr or 'Restart failed'}
- except Exception as e:
- return {'success': False, 'error': str(e)}
-
- @classmethod
- def configure_nginx_proxy(cls, domain: str) -> Dict:
- """Create Nginx reverse proxy config for Roundcube."""
- try:
- from app.services.nginx_service import NginxService
-
- config = f"""# Roundcube Webmail - Managed by ServerKit
-server {{
- listen 80;
- server_name {domain};
-
- location / {{
- proxy_pass http://127.0.0.1:{cls.HOST_PORT};
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- client_max_body_size 25m;
- }}
-}}
-"""
- site_name = f'roundcube-{domain.replace(".", "-")}'
- config_path = f'/etc/nginx/sites-available/{site_name}'
- enabled_path = f'/etc/nginx/sites-enabled/{site_name}'
-
- run_privileged(['tee', config_path], input=config)
- run_privileged(['ln', '-sf', config_path, enabled_path])
-
- # Test and reload
- test = run_privileged(['nginx', '-t'])
- if test.returncode != 0:
- # Rollback
- run_privileged(['rm', '-f', enabled_path])
- return {'success': False, 'error': f'Nginx config test failed: {test.stderr}'}
-
- run_privileged(['systemctl', 'reload', 'nginx'])
-
- return {
- 'success': True,
- 'message': f'Nginx proxy configured for {domain}',
- 'url': f'http://{domain}',
- }
- except Exception as e:
- return {'success': False, 'error': str(e)}
diff --git a/backend/app/services/metrics_history_service.py b/backend/app/services/metrics_history_service.py
index 00caac19..e381b883 100644
--- a/backend/app/services/metrics_history_service.py
+++ b/backend/app/services/metrics_history_service.py
@@ -361,6 +361,13 @@ class MetricsHistoryService:
logger.warning("Metrics collection already running")
return
+ # Never spawn the collector under testing: the app fixture is
+ # function-scoped, so one immortal writer would leak per create_app()
+ # call and race the suite's shared SQLite file (see the queue-bus
+ # consumers, which gate the same way).
+ if app.config.get('ENV') == 'testing' or app.config.get('TESTING'):
+ return
+
cls._stop_collection = False
cls._is_running = True
diff --git a/backend/app/services/site_domain_service.py b/backend/app/services/site_domain_service.py
index bd55326b..8bb8f65c 100644
--- a/backend/app/services/site_domain_service.py
+++ b/backend/app/services/site_domain_service.py
@@ -22,6 +22,19 @@ from app.utils.slug import slugify as _slugify
class SiteDomainService:
DEFAULT_BASE_DOMAIN = 'lvh.me'
+ # Deep-link a publishing gap / preflight warning to the page that fixes it,
+ # in the Setup Health item shape ``{'kind': 'link', 'to': <path>}``. The
+ # config gaps are fixed in Settings → Managed Sites; an unresolved host is
+ # fixed from Monitoring → Doctor (one-click record create when a provider is
+ # connected).
+ _GAP_FIX_LINKS = {
+ 'no_base_domain': {'kind': 'link', 'to': '/settings/site'},
+ 'base_overlaps_panel': {'kind': 'link', 'to': '/settings/site'},
+ 'http_only': {'kind': 'link', 'to': '/settings/site'},
+ 'no_server_ip': {'kind': 'link', 'to': '/settings/site'},
+ 'host_unresolved': {'kind': 'link', 'to': '/monitoring/doctor'},
+ }
+
@staticmethod
def _norm(value):
return (str(value).strip().lstrip('.').lower()) if value else ''
@@ -389,6 +402,80 @@ class SiteDomainService:
continue
return {'sent': sent}
+ # ------------------------------------------------------------------ #
+ # Creation-time preflight (advisory)
+ # ------------------------------------------------------------------ #
+
+ @staticmethod
+ def _host_resolves(host, timeout=2.0):
+ """True when ``host`` currently resolves to at least one A/AAAA address.
+
+ Runs the blocking ``socket.getaddrinfo`` lookup in a worker thread with a
+ hard ``timeout`` so a slow or unreachable resolver must not produce a
+ false 'does not resolve' warning at create time — but also can never
+ stall the create flow. A lookup that errors, times out, or yields nothing
+ counts as 'does not resolve'.
+ """
+ import socket
+ from concurrent.futures import ThreadPoolExecutor
+ from concurrent.futures import TimeoutError as FTimeout
+
+ def _resolve():
+ try:
+ return bool(socket.getaddrinfo(host, None))
+ except OSError:
+ return False
+
+ pool = ThreadPoolExecutor(max_workers=1)
+ try:
+ future = pool.submit(_resolve)
+ try:
+ return bool(future.result(timeout=timeout))
+ except FTimeout:
+ return False
+ finally:
+ pool.shutdown(wait=False)
+
+ @staticmethod
+ def _skip_dns_host(host):
+ """True for hosts the resolvability probe skips entirely: loopback / bare
+ labels / IP literals / dev + reserved suffixes (``lvh.me``, ``localhost``,
+ ``.test`` …). Reuses the doctor's own public-host filter so both surfaces
+ agree on what is worth a real DNS lookup."""
+ from app.services.doctor_service import _is_public_site_host
+ return not _is_public_site_host(host)
+
+ @classmethod
+ def creation_warnings(cls, host=None):
+ """Preflight warnings for a just-created site: every open publishing gap
+ (:meth:`publishing_gaps`) plus, when ``host`` is a real public name, a
+ resolvability probe of it.
+
+ Returns ``[{code, message, fix}]`` (empty when fully set up). Never blocks
+ a create — this is advisory. ``fix`` is a ``{kind:'link', to}`` deep-link,
+ matching the Setup Health item shape.
+ """
+ warnings = []
+ for gap in cls.publishing_gaps():
+ code = gap['code']
+ warnings.append({
+ 'code': code,
+ 'message': gap['message'],
+ 'fix': cls._GAP_FIX_LINKS.get(code, {'kind': 'link', 'to': '/settings/site'}),
+ })
+
+ if host and not cls._skip_dns_host(host) and not cls._host_resolves(host):
+ warnings.append({
+ 'code': 'host_unresolved',
+ 'message': (
+ f'{host} does not resolve yet, so visitors get a DNS error '
+ '(NXDOMAIN) until its record exists. If a DNS provider is '
+ 'connected, use Monitoring → Doctor to create the record in one '
+ 'click; otherwise add the record at your DNS host.'),
+ 'fix': cls._GAP_FIX_LINKS['host_unresolved'],
+ })
+ return warnings
+
@classmethod
def _vhost_create_kwargs(cls, app, domains, ssl_cert, ssl_key, force_type=None):
"""Build ``NginxService.create_site(**kwargs)`` for ``app``, or
@@ -492,8 +579,10 @@ class SiteDomainService:
(re)writes its nginx vhost, and — in per-site DNS mode — auto-creates the A
record (wildcard mode relies on ``*.<base>``).
- Returns ``{success, host, url, dns, nginx, warning}`` or
- ``{success: False, error}``.
+ Returns ``{success, host, url, dns, nginx, warning, warnings}`` or
+ ``{success: False, error}``. ``warning`` is the legacy single string;
+ ``warnings`` is the structured advisory-preflight array
+ (:meth:`creation_warnings`).
"""
from app import db
from app.models.domain import Domain
@@ -538,4 +627,5 @@ class SiteDomainService:
return {'success': True, 'host': host,
'url': cls.site_url(host, ssl=cls.https_enabled(base) and cls.covers(host)),
- 'dns': dns, 'nginx': nginx, 'warning': warning}
+ 'dns': dns, 'nginx': nginx, 'warning': warning,
+ 'warnings': cls.creation_warnings(host)}