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: Phase 4 polish & fleet — onboarding completion, fleet proxy, shared-resource depth, docs

Juan Denisc4f3b4fdac4a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 067cd027..712aa9de 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,39 @@ awaiting a stable release:
### Added
+- **Container status aggregator** — collapses an app's per-container Docker
+ states into one deterministic status (`running:healthy` … `degraded` …
+ `unknown`) at `/api/v1/status/app/<id>` and `/api/v1/status/apps`, with
+ change-only pushes over the `container_status` Socket.IO channel.
+- **API token scopes** — fine-grained, additive scopes for API keys (enforced
+ only for `X-API-Key` requests; JWT/session callers stay RBAC-governed), a
+ `require_scope` decorator, and a scope catalog at `/api/v1/api-keys/scopes`.
+- **Server onboarding state machine** — a linear lifecycle (validating →
+ installing prerequisites → installing Docker → pairing agent → ready/failed)
+ driven on the job bus, with start/retry/status at
+ `/api/v1/servers/<id>/onboarding/*` and an ordered progress log.
+- **Declarative template catalog** — a documented catalog schema
+ (`/api/v1/templates/catalog/schema`) with auto-resolved `${SERVICE_*}` magic
+ variables (password/user/FQDN/URL/base64) so templates never hardcode generated
+ secrets or hosts. See [docs/TEMPLATE_CATALOG_SCHEMA.md](docs/TEMPLATE_CATALOG_SCHEMA.md).
+- **Build packs** — zero-Dockerfile detection that inspects a repo and generates
+ a Dockerfile + compose from a build plan (`/api/v1/buildpacks/detect`,
+ `/generate`), persisted on the application row; defers to an author-provided
+ Dockerfile when present.
+- **Deployment config snapshots** — immutable, secret-masked config snapshots
+ captured before each deploy, with diff and one-click restore + redeploy at
+ `/api/v1/apps/<id>/snapshots[/<id>/diff|/restore]`.
+- **Projects & Environments** — a Workspace → Project → Environment → Apps
+ hierarchy (`/api/v1/projects`, `/api/v1/environments`) with workspace-scoped
+ access and resource counts.
+- **Shared resources** — polymorphic tags and attachable shared variable groups
+ with a merged "resolved" view and masked secrets (`/api/v1/shared/...`).
+- **PR preview environments** — ephemeral previews driven by a pull-request
+ webhook (`/api/v1/webhooks/pull-request/<token>`) that open, redeploy, and tear
+ down per PR, managed at `/api/v1/apps/<id>/previews`.
+- **Per-server managed proxy stack** — opt-in Dockerized Traefik or Caddy per
+ server with a compose preview before switching, host nginx remaining the
+ default (`/api/v1/servers/<id>/proxy*`).
- **Multi-platform agent & fleet management** — native Go agent for Linux,
Windows, and macOS with HMAC-SHA256 auth and WebSocket + HTTP-poll transports,
plus a fleet dashboard (inventory, connection status, approval queue,
diff --git a/README.md b/README.md
index b57c0519..b0f610cb 100644
--- a/README.md
+++ b/README.md
@@ -232,6 +232,18 @@ English | [Español](docs/README.es.md) | [中文版](docs/README.zh-CN.md) | [P
**Marketplace** — Over 60+ one-click templates for popular apps (Immich, Ghost, Authelia, etc.)
+**Build Packs** — Zero-Dockerfile detection that inspects a repo and generates a Dockerfile + compose from a build plan (defers to an author-provided Dockerfile when present)
+
+**Declarative Templates** — A documented catalog schema with auto-resolved `${SERVICE_*}` magic variables (password/user/FQDN/URL/base64) so templates never hardcode generated secrets or hosts
+
+**Projects & Environments** — Group applications into a Workspace → Project → Environment hierarchy with workspace-scoped access and resource counts
+
+**Config Snapshots** — Immutable, secret-masked configuration snapshots captured before each deploy, with diff and one-click restore + redeploy
+
+**Container Status** — One deterministic health status per app, aggregated from its containers and pushed live (healthy / degraded / restarting / unhealthy)
+
+**PR Preview Environments** — Ephemeral previews driven by a pull-request webhook that open, redeploy, and tear down per PR
+
### 🏗️ Infrastructure
**Domain Management** — Nginx virtual hosts with easy configuration
@@ -306,6 +318,10 @@ English | [Español](docs/README.es.md) | [中文版](docs/README.zh-CN.md) | [P
**API Key Rotation** — Secure credential rotation with acknowledgment handshake
+**Server Onboarding** — A guided onboarding state machine (validate → install prerequisites → install Docker → pair agent → ready) driven on the job bus with a live progress log
+
+**Per-Server Proxy Stack** — Opt-in Dockerized Traefik or Caddy per server with a compose preview before switching; host nginx remains the default
+
**Cross-Server Metrics** — Historical metrics with comparison charts and retention policies
### 📊 Monitoring & Alerts
@@ -336,6 +352,10 @@ English | [Español](docs/README.es.md) | [中文版](docs/README.zh-CN.md) | [P
**API Keys** — Tiered API keys (standard/elevated/unlimited) with rate limiting, usage analytics, and OpenAPI documentation
+**API Token Scopes** — Fine-grained, additive scopes for API keys (enforced for programmatic `X-API-Key` callers; JWT/session users stay RBAC-governed)
+
+**Shared Resources** — Polymorphic tags and attachable shared variable groups with a merged "resolved" view and masked secrets
+
**Webhook Subscriptions** — Event-driven webhooks with HMAC signatures, retry logic, and custom headers
### 🎨 Customization
@@ -533,6 +553,7 @@ Full details: [ROADMAP.md](ROADMAP.md)
| [Agent Pairing](docs/pairing.md) | Secure short-code agent enrollment |
| [API Reference](docs/API.md) | REST API endpoints |
| [New Features](docs/NEW_FEATURES.md) | Endpoint & page reference for the latest `dev` features |
+| [Enhancements](docs/ENHANCEMENTS.md) | Guide to the ten developer-experience, team/scale, fleet, and security capabilities |
| [Changelog](CHANGELOG.md) | Release history and notable changes |
| [Roadmap](ROADMAP.md) | Development roadmap and planned features |
| [Contributing](CONTRIBUTING.md) | How to contribute |
diff --git a/backend/app/api/proxy.py b/backend/app/api/proxy.py
index 81208023..d49c0156 100644
--- a/backend/app/api/proxy.py
+++ b/backend/app/api/proxy.py
@@ -28,6 +28,19 @@ def _require_server(server_id):
return server, None
+@proxy_bp.route('/proxy/overview', methods=['GET'])
+@jwt_required()
+def proxy_overview():
+ """Fleet-wide proxy posture: one row per server.
+
+ Mounted under ``/api/v1/servers`` → full path ``/api/v1/servers/proxy/
+ overview``. The static ``proxy`` segment can't match the ``<server_id>``
+ converter on ``/<server_id>/proxy``, and Werkzeug prefers static rules over
+ dynamic ones, so the two never collide. Best-effort; always returns JSON.
+ """
+ return jsonify({'servers': ProxyStackService.fleet_overview()})
+
+
@proxy_bp.route('/<server_id>/proxy', methods=['GET'])
@jwt_required()
def get_proxy(server_id):
diff --git a/backend/app/api/shared_resources.py b/backend/app/api/shared_resources.py
index a62d2679..7dcbf574 100644
--- a/backend/app/api/shared_resources.py
+++ b/backend/app/api/shared_resources.py
@@ -257,3 +257,39 @@ def resolved():
'groups': [g.to_dict() for g in groups],
}
return jsonify(mask_sensitive(payload))
+
+
+@shared_resources_bp.route('/resolved/hierarchical', methods=['GET'])
+@jwt_required()
+def resolved_hierarchical():
+ """Hierarchical effective variables for a resource (secrets masked).
+
+ Merges scope-inherited groups with the resource's directly-attached groups.
+ Precedence, lowest → highest:
+
+ workspace < project < environment < direct attachments
+
+ Each returned variable carries a ``source_scope`` provenance marker. Pass the
+ scope ids via ``?workspace_id=&project_id=&environment_id=``; any omitted
+ scope simply contributes no layer.
+ """
+ resource_type = request.args.get('resource_type')
+ resource_id = request.args.get('resource_id')
+ if not resource_type or resource_id in (None, ''):
+ return _bad('resource_type and resource_id are required')
+
+ context = {
+ 'workspace_id': request.args.get('workspace_id'),
+ 'project_id': request.args.get('project_id'),
+ 'environment_id': request.args.get('environment_id'),
+ }
+ variables = SharedResourceService.resolve_hierarchical(
+ resource_type, resource_id, context=context, mask_secrets=True
+ )
+ payload = {
+ 'resource_type': resource_type,
+ 'resource_id': str(resource_id),
+ 'context': {k: v for k, v in context.items() if v not in (None, '')},
+ 'variables': variables,
+ }
+ return jsonify(mask_sensitive(payload))
diff --git a/backend/app/services/proxy_stack_service.py b/backend/app/services/proxy_stack_service.py
index b3616e37..eb1e0e88 100644
--- a/backend/app/services/proxy_stack_service.py
+++ b/backend/app/services/proxy_stack_service.py
@@ -477,6 +477,71 @@ class ProxyStackService:
logger.warning(f"backup_config failed: {e}")
return None
+ @staticmethod
+ def fleet_overview():
+ """Fleet-wide proxy posture: one row per server.
+
+ Best-effort and guarded — never raises. Joins every ``Server`` with its
+ ``ProxyStack`` (if one exists). Servers that never opted into a managed
+ stack report the host-nginx default (``proxy_type='nginx'``,
+ ``status='host'``) rather than being omitted, so the dashboard shows the
+ *whole* fleet, not just the servers with a configured stack.
+
+ Returns a list of flat dicts:
+ ``{server_id, server_name, proxy_type, status, last_regenerated_at,
+ networks_count}``
+ """
+ try:
+ from app.models.server import Server
+ from app.models.proxy_stack import ProxyStack
+ except Exception as e: # pragma: no cover - import guard
+ logger.warning(f"fleet_overview imports failed: {e}")
+ return []
+
+ try:
+ servers = Server.query.order_by(Server.name).all()
+ except Exception as e: # pragma: no cover - DB guard
+ logger.warning(f"fleet_overview server query failed: {e}")
+ return []
+
+ # One query for all stacks, keyed by server_id, to avoid N+1 lookups.
+ stacks_by_server = {}
+ try:
+ for stack in ProxyStack.query.all():
+ stacks_by_server[stack.server_id] = stack
+ except Exception as e: # pragma: no cover - DB guard
+ logger.warning(f"fleet_overview stack query failed: {e}")
+
+ overview = []
+ for server in servers:
+ stack = stacks_by_server.get(server.id)
+ if stack is not None:
+ overview.append({
+ 'server_id': server.id,
+ 'server_name': server.name,
+ 'proxy_type': stack.proxy_type or 'nginx',
+ 'status': stack.status or 'unknown',
+ 'last_regenerated_at': (
+ stack.last_regenerated_at.isoformat()
+ if stack.last_regenerated_at else None
+ ),
+ 'networks_count': len(stack.networks_list()),
+ })
+ else:
+ # No managed stack → host nginx is in charge. 'host' is a
+ # distinct status from the stack states (running/stopped/...) so
+ # the UI can render "host default" rather than a runtime state.
+ overview.append({
+ 'server_id': server.id,
+ 'server_name': server.name,
+ 'proxy_type': 'nginx',
+ 'status': 'host',
+ 'last_regenerated_at': None,
+ 'networks_count': 0,
+ })
+
+ return overview
+
@staticmethod
def status(server_id):
"""Best-effort runtime status of the proxy stack.
diff --git a/backend/app/services/server_onboarding_service.py b/backend/app/services/server_onboarding_service.py
index c88a26e6..8521ada5 100644
--- a/backend/app/services/server_onboarding_service.py
+++ b/backend/app/services/server_onboarding_service.py
@@ -5,13 +5,18 @@ Formalizes "add a server" as an observable lifecycle:
pending -> validating -> installing_prerequisites -> installing_docker
-> pairing_agent -> ready (or -> failed at any step)
-Phase 1 scope:
+Phase 4 scope:
+ * A pure :meth:`pre_flight_check` compatibility gate (arch / distro family /
+ kernel / CPU / memory) that is fully unit-testable and runs at the top of
+ `validate`.
* `validate` is a real, best-effort transition (server exists, has an
- endpoint or agent, optional reachability probe).
- * `install_prerequisites` / `install_docker` / `pair_agent` are structured,
- idempotent STUBS — they record a started/succeeded pair and advance. The
- real install automation lands in a later phase. They must never crash on
- Windows/dev (all Unix-only work is guarded).
+ endpoint or agent, optional reachability probe + pre-flight gate).
+ * `install_prerequisites` / `install_docker` / `pair_agent` are REAL but
+ heavily GUARDED. On Linux with a package manager / sudo they do real work
+ (best-effort); on Windows/dev, or when the host lacks the tooling, they log
+ a ``skipped`` detail and succeed. They are idempotent and never raise.
+ * Every transition emits an :class:`AuditService` row, and `ready` / `failed`
+ fire a best-effort notification.
Each transition appends a `ServerOnboardingLog` row and mirrors a compact
snapshot onto `Server.onboarding_progress` so the wizard can poll cheaply.
@@ -23,6 +28,8 @@ callers drive the machine synchronously via `start()` / `validate()` /
"""
import json
import logging
+import os
+import re
from datetime import datetime
from flask import current_app, has_app_context
@@ -39,6 +46,25 @@ ONBOARDING_JOB_KIND = 'server.onboarding.advance'
# Number of recent log rows mirrored into Server.onboarding_progress.
_PROGRESS_SNAPSHOT_LIMIT = 40
+# Base packages every managed host should carry. Kept small + universally
+# available across Debian/RHEL families so the install is unlikely to fail.
+_BASE_PACKAGES = ('curl', 'ca-certificates')
+
+# Pre-flight compatibility envelope.
+_SUPPORTED_ARCHES = {
+ 'x86_64': 'x86_64', 'amd64': 'x86_64', 'x64': 'x86_64',
+ 'arm64': 'arm64', 'aarch64': 'arm64',
+}
+_SUPPORTED_DISTRO_FAMILIES = {
+ 'debian', 'ubuntu', 'rhel', 'redhat', 'fedora', 'centos', 'rocky',
+ 'almalinux', 'alma', 'amazon', 'amzn', 'linux',
+}
+# Conservative floors. Docker + the agent are light, but these guard against
+# obviously-too-small hosts (and stale/embedded kernels).
+_MIN_KERNEL = (3, 10) # RHEL 7 era — Docker's documented floor.
+_MIN_CPU_CORES = 1
+_MIN_MEMORY_BYTES = 512 * 1024 * 1024 # 512 MiB
+
class ServerOnboardingService:
"""Drives a server through its provisioning lifecycle."""
@@ -142,21 +168,200 @@ class ServerOnboardingService:
db.session.commit()
cls._audit('server.onboarding.failed', server,
{'state': state, 'message': message})
+ cls._notify('server.onboarding.failed', server,
+ {'state': state, 'message': message, 'summary': message})
@classmethod
def _audit(cls, action, server, details):
- """Best-effort audit; never let an audit failure break onboarding."""
+ """Best-effort audit; never let an audit failure break onboarding.
+
+ ``AuditLog.target_id`` is an Integer column while ``Server.id`` is a
+ UUID string, so we stash the server id inside ``details`` (where it's
+ always queryable) and leave ``target_id`` unset.
+ """
try:
from app.services.audit_service import AuditService
+ payload = {'server_id': server.id}
+ payload.update(details or {})
AuditService.log(
action=action,
target_type='server',
- target_id=server.id,
- details=details or {},
+ details=payload,
)
except Exception as exc: # pragma: no cover - defensive
logger.debug('onboarding audit %s failed: %s', action, exc)
+ @classmethod
+ def _notify(cls, event, server, data):
+ """Best-effort terminal-state notification. Never raises."""
+ try:
+ from app.plugins_sdk import notify
+ payload = {
+ 'server': server.name or server.id,
+ 'server_id': server.id,
+ 'hostname': server.hostname,
+ }
+ payload.update(data or {})
+ notify.send(event, to='admins', data=payload, category='system')
+ except Exception as exc: # pragma: no cover - defensive
+ logger.debug('onboarding notify %s failed: %s', event, exc)
+
+ # ------------------------------------------------------------------ #
+ # Pre-flight compatibility check (PURE — fully unit-testable)
+ # ------------------------------------------------------------------ #
+
+ @staticmethod
+ def _coerce_int(value):
+ """Best-effort int from possibly-stringy/None system_info values."""
+ if value is None:
+ return None
+ if isinstance(value, bool):
+ return None
+ if isinstance(value, (int, float)):
+ return int(value)
+ try:
+ return int(str(value).strip())
+ except (TypeError, ValueError):
+ return None
+
+ @classmethod
+ def _parse_kernel(cls, raw):
+ """Return a (major, minor) tuple from a kernel string like
+ ``5.15.0-89-generic`` / ``4.18.0-477.el8`` — or None if unparseable."""
+ if not raw:
+ return None
+ m = re.match(r'\s*(\d+)\.(\d+)', str(raw))
+ if not m:
+ return None
+ return (int(m.group(1)), int(m.group(2)))
+
+ @classmethod
+ def pre_flight_check(cls, system_info):
+ """Pure compatibility gate for a candidate host.
+
+ ``system_info`` is a plain dict (typically derived from the agent's
+ capabilities report or the Server row). Recognized keys (all optional):
+
+ architecture / arch e.g. 'x86_64', 'arm64', 'amd64'
+ os_type e.g. 'linux', 'windows', 'darwin'
+ distro / distro_family / e.g. 'ubuntu', 'debian', 'rocky'
+ os_id / platform
+ kernel / kernel_version e.g. '5.15.0-89-generic'
+ cpu_cores int
+ total_memory bytes (int)
+
+ Returns::
+
+ {
+ 'compatible': bool, # False iff any blocking check failed
+ 'checks': [{'name','ok','detail'}, ...],
+ 'blocking': ['<name>', ...], # subset of failed, hard checks
+ }
+
+ A check with ``ok is None`` is "unknown" (info not supplied) — never
+ blocking, so a sparse system_info won't wrongly reject a host. Only a
+ check that is *known and bad* blocks.
+ """
+ info = system_info or {}
+ checks = []
+ blocking = []
+
+ def add(name, ok, detail, hard=True):
+ checks.append({'name': name, 'ok': ok, 'detail': detail})
+ if hard and ok is False:
+ blocking.append(name)
+
+ # --- architecture ---
+ raw_arch = (info.get('architecture') or info.get('arch') or '')
+ arch = str(raw_arch).strip().lower()
+ if not arch:
+ add('architecture', None, 'Architecture not reported')
+ elif arch in _SUPPORTED_ARCHES:
+ add('architecture', True,
+ f'{raw_arch} (supported as {_SUPPORTED_ARCHES[arch]})')
+ else:
+ add('architecture', False,
+ f'Unsupported architecture: {raw_arch}')
+
+ # --- OS / distro family ---
+ os_type = str(info.get('os_type') or '').strip().lower()
+ if os_type and os_type not in ('linux', ''):
+ add('os', False,
+ f'Unsupported OS: {os_type} (Linux required for provisioning)')
+ else:
+ distro = str(info.get('distro') or info.get('distro_family')
+ or info.get('os_id') or info.get('platform')
+ or '').strip().lower()
+ if not distro:
+ add('distro', None, 'Distro not reported')
+ else:
+ family = distro.split()[0] if distro else ''
+ if any(fam in distro for fam in _SUPPORTED_DISTRO_FAMILIES) \
+ or family in _SUPPORTED_DISTRO_FAMILIES:
+ add('distro', True, f'Supported distro family: {distro}')
+ else:
+ add('distro', False, f'Unrecognized distro: {distro}')
+
+ # --- kernel ---
+ kernel = cls._parse_kernel(info.get('kernel')
+ or info.get('kernel_version'))
+ if kernel is None:
+ add('kernel', None, 'Kernel version not reported')
+ elif kernel >= _MIN_KERNEL:
+ add('kernel', True,
+ f'Kernel {kernel[0]}.{kernel[1]} OK '
+ f'(>= {_MIN_KERNEL[0]}.{_MIN_KERNEL[1]})')
+ else:
+ add('kernel', False,
+ f'Kernel {kernel[0]}.{kernel[1]} too old '
+ f'(need >= {_MIN_KERNEL[0]}.{_MIN_KERNEL[1]})')
+
+ # --- CPU ---
+ cores = cls._coerce_int(info.get('cpu_cores'))
+ if cores is None:
+ add('cpu', None, 'CPU core count not reported')
+ elif cores >= _MIN_CPU_CORES:
+ add('cpu', True, f'{cores} core(s)')
+ else:
+ add('cpu', False,
+ f'{cores} core(s) (need >= {_MIN_CPU_CORES})')
+
+ # --- memory ---
+ mem = cls._coerce_int(info.get('total_memory'))
+ if mem is None:
+ add('memory', None, 'Total memory not reported')
+ elif mem >= _MIN_MEMORY_BYTES:
+ add('memory', True,
+ f'{mem // (1024 * 1024)} MiB')
+ else:
+ add('memory', False,
+ f'{mem // (1024 * 1024)} MiB '
+ f'(need >= {_MIN_MEMORY_BYTES // (1024 * 1024)} MiB)')
+
+ return {
+ 'compatible': len(blocking) == 0,
+ 'checks': checks,
+ 'blocking': blocking,
+ }
+
+ @staticmethod
+ def _system_info_for(server):
+ """Build the pre_flight_check input dict from a Server row.
+
+ Prefers the agent's cached capability snapshot where available, falling
+ back to the columns the row already carries.
+ """
+ caps = server.cached_capabilities or {}
+ return {
+ 'architecture': server.architecture or caps.get('architecture'),
+ 'os_type': server.os_type or caps.get('os_type'),
+ 'distro': server.platform or caps.get('distro'),
+ 'os_id': server.os_version,
+ 'kernel': caps.get('kernel') or caps.get('kernel_version'),
+ 'cpu_cores': server.cpu_cores,
+ 'total_memory': server.total_memory,
+ }
+
@staticmethod
def _is_testing():
if not has_app_context():
@@ -235,12 +440,17 @@ class ServerOnboardingService:
reachable = cls._check_reachable(server)
+ # Pure compatibility gate — only blocks when the host reports something
+ # known-incompatible. A sparse/unknown system_info passes.
+ preflight = cls.pre_flight_check(cls._system_info_for(server))
+
detail = {
'has_endpoint': has_endpoint,
'has_agent': has_agent,
'reachable': reachable,
'hostname': server.hostname,
'ip_address': server.ip_address,
+ 'preflight': preflight,
}
if not has_endpoint and not has_agent:
@@ -251,10 +461,21 @@ class ServerOnboardingService:
)
return cls.get_status(server.id)
+ if not preflight['compatible']:
+ cls._fail(
+ server, cls.STATE_VALIDATING,
+ 'Host failed the pre-flight compatibility check: '
+ + ', '.join(preflight['blocking']),
+ detail=detail,
+ )
+ return cls.get_status(server.id)
+
cls._log(server, cls.STATE_VALIDATING, ServerOnboardingLog.STATUS_SUCCEEDED,
message='Validation passed', detail=detail, commit=False)
cls._set_state(server, cls.STATE_INSTALLING_PREREQS)
db.session.commit()
+ cls._audit('server.onboarding.step', server,
+ {'state': cls.STATE_VALIDATING, 'status': 'succeeded'})
# Continue down the chain.
return cls.advance(server)
@@ -278,66 +499,197 @@ class ServerOnboardingService:
@classmethod
def install_prerequisites(cls, server):
- """STUB: install base prerequisites. Idempotent + safe on any OS.
-
- Phase 4 will run real package installs via the agent. For now we record
- a started/succeeded pair and advance.
+ """Install base prerequisites — real on Linux, a safe no-op elsewhere.
+
+ On a Linux host with a detectable package manager we install a small,
+ universally-available base set (curl, ca-certificates) via
+ ``PackageManager.install``. On Windows/dev, or when no package manager
+ is present, we record a ``skipped`` detail and succeed. Idempotent:
+ already-installed packages are detected and not reinstalled.
+ Never raises.
"""
- return cls._run_stub_step(
+ done_msg, detail = cls._do_install_prerequisites()
+ return cls._run_step(
server,
state=cls.STATE_INSTALLING_PREREQS,
start_msg='Installing prerequisites',
- done_msg='Prerequisites ready (stub)',
- detail={'stub': True, 'note': 'real installs land in a later phase'},
+ done_msg=done_msg,
+ detail=detail,
)
@classmethod
- def install_docker(cls, server):
- """STUB: ensure Docker is installed. Idempotent + safe on any OS."""
- from app.utils.system import is_command_available
+ def _do_install_prerequisites(cls):
+ """Best-effort prerequisite install. Returns (done_msg, detail)."""
+ from app.utils.system import PackageManager
+
+ if os.name == 'nt':
+ return ('Prerequisites skipped (not a Linux host)',
+ {'skipped': True, 'reason': 'windows/dev'})
- docker_present = False
try:
- docker_present = is_command_available('docker')
+ manager = PackageManager.detect()
except Exception as exc: # pragma: no cover - defensive
- logger.debug('docker presence check failed: %s', exc)
+ return ('Prerequisites skipped (package manager probe failed)',
+ {'skipped': True, 'reason': f'detect error: {exc}'})
+
+ if not manager:
+ return ('Prerequisites skipped (no supported package manager)',
+ {'skipped': True, 'reason': 'no package manager'})
+
+ # Idempotent: only install what's missing.
+ missing = []
+ for pkg in _BASE_PACKAGES:
+ try:
+ if not PackageManager.is_installed(pkg):
+ missing.append(pkg)
+ except Exception: # pragma: no cover - defensive
+ missing.append(pkg)
+
+ if not missing:
+ return ('Prerequisites already present',
+ {'manager': manager, 'installed': [],
+ 'already_present': list(_BASE_PACKAGES)})
- return cls._run_stub_step(
+ try:
+ result = PackageManager.install(list(missing))
+ ok = getattr(result, 'returncode', 1) == 0
+ except Exception as exc:
+ return (f'Prerequisite install best-effort failed: {exc}',
+ {'manager': manager, 'attempted': missing,
+ 'best_effort_error': str(exc)})
+
+ if ok:
+ return (f'Installed prerequisites: {", ".join(missing)}',
+ {'manager': manager, 'installed': missing})
+ return ('Prerequisite install completed with warnings',
+ {'manager': manager, 'attempted': missing,
+ 'returncode': getattr(result, 'returncode', None)})
+
+ @classmethod
+ def install_docker(cls, server):
+ """Ensure Docker is available — real on Linux, a safe no-op elsewhere.
+
+ If ``docker`` is already on PATH we record it and succeed. Otherwise on
+ a Linux host with sudo/a package manager we make a best-effort install
+ attempt (the distro's docker.io / docker package); on Windows/dev or
+ without the tooling we record a ``skipped`` detail and succeed so the
+ pipeline still completes. Never raises.
+ """
+ done_msg, detail = cls._do_install_docker()
+ return cls._run_step(
server,
state=cls.STATE_INSTALLING_DOCKER,
start_msg='Installing Docker',
- done_msg=('Docker already present' if docker_present
- else 'Docker install queued (stub)'),
- detail={'stub': True, 'docker_present': docker_present},
+ done_msg=done_msg,
+ detail=detail,
)
@classmethod
- def pair_agent(cls, server):
- """STUB: pair the management agent. Idempotent + safe on any OS.
+ def _do_install_docker(cls):
+ """Best-effort Docker install. Returns (done_msg, detail)."""
+ from app.utils.system import PackageManager, is_command_available
- If an agent is already connected we treat pairing as satisfied; the
- real token mint / install handshake lands in a later phase.
- """
- already_paired = False
+ docker_present = False
try:
- from app.services.agent_registry import agent_registry
- already_paired = agent_registry.is_agent_connected(server.id)
+ docker_present = is_command_available('docker')
except Exception as exc: # pragma: no cover - defensive
- logger.debug('agent pairing check failed: %s', exc)
+ logger.debug('docker presence check failed: %s', exc)
+
+ if docker_present:
+ return 'Docker already present', {'docker_present': True}
- return cls._run_stub_step(
+ if os.name == 'nt':
+ return ('Docker install skipped (not a Linux host)',
+ {'skipped': True, 'reason': 'windows/dev',
+ 'docker_present': False})
+
+ try:
+ manager = PackageManager.detect()
+ except Exception as exc: # pragma: no cover - defensive
+ manager = None
+ logger.debug('docker install pm probe failed: %s', exc)
+
+ if not manager:
+ return ('Docker install skipped (no supported package manager)',
+ {'skipped': True, 'reason': 'no package manager',
+ 'docker_present': False})
+
+ # Distro-appropriate package name. Debian/Ubuntu ship docker.io; the
+ # RHEL family uses the docker package (or podman-docker on minimal
+ # images). This is intentionally best-effort — a full
+ # get.docker.com convenience-script run lands with agent-driven
+ # provisioning; here we just try the distro package so a fresh host
+ # isn't left empty-handed.
+ pkg = 'docker.io' if manager == 'apt' else 'docker'
+ try:
+ result = PackageManager.install(pkg)
+ ok = getattr(result, 'returncode', 1) == 0
+ except Exception as exc:
+ return (f'Docker install best-effort failed: {exc}',
+ {'manager': manager, 'attempted': pkg,
+ 'best_effort_error': str(exc), 'docker_present': False})
+
+ if ok:
+ return (f'Installed Docker ({pkg})',
+ {'manager': manager, 'installed': pkg})
+ return ('Docker install completed with warnings',
+ {'manager': manager, 'attempted': pkg,
+ 'returncode': getattr(result, 'returncode', None)})
+
+ @classmethod
+ def pair_agent(cls, server):
+ """Pair the management agent — guarded, idempotent, never raises.
+
+ Resolution order:
+ * Agent already connected (live socket) -> satisfied.
+ * Server row already carries agent credentials/id -> satisfied
+ (registered, may just be momentarily offline).
+ * Otherwise -> the step succeeds but records a ``waiting`` detail
+ describing what the operator must do (run the install/enroll
+ command on the host). We don't hard-fail: a server can be fully
+ "ready" in the panel and have its agent connect a moment later.
+ """
+ done_msg, detail = cls._do_pair_agent(server)
+ return cls._run_step(
server,
state=cls.STATE_PAIRING_AGENT,
start_msg='Pairing agent',
- done_msg=('Agent already paired' if already_paired
- else 'Agent pairing prepared (stub)'),
- detail={'stub': True, 'already_paired': already_paired},
+ done_msg=done_msg,
+ detail=detail,
)
@classmethod
- def _run_stub_step(cls, server, state, start_msg, done_msg, detail=None):
- """Shared body for the stubbed install/pair steps: log started, log
- succeeded, advance to the next state, return status."""
+ def _do_pair_agent(cls, server):
+ """Best-effort agent pairing resolution. Returns (done_msg, detail)."""
+ connected = False
+ try:
+ from app.services.agent_registry import agent_registry
+ connected = agent_registry.is_agent_connected(server.id)
+ except Exception as exc: # pragma: no cover - defensive
+ logger.debug('agent pairing check failed: %s', exc)
+
+ if connected:
+ return 'Agent connected', {'connected': True, 'registered': True}
+
+ # Credentials/identity already minted for this server?
+ registered = bool(server.agent_id or server.api_key_hash
+ or server.registration_token_hash)
+
+ if registered:
+ return ('Agent registered (awaiting connection)',
+ {'connected': False, 'registered': True,
+ 'waiting': 'Agent enrolled but not currently connected.'})
+
+ return ('Agent not yet enrolled',
+ {'connected': False, 'registered': False,
+ 'waiting': ('Run the agent install/enroll command on the '
+ 'host to complete pairing. Onboarding will '
+ 'finish; the agent can connect afterward.')})
+
+ @classmethod
+ def _run_step(cls, server, state, start_msg, done_msg, detail=None):
+ """Shared body for the install/pair steps: log started, log succeeded,
+ emit an audit row, advance to the next state, return status."""
cls._set_state(server, state)
cls._log(server, state, ServerOnboardingLog.STATUS_STARTED,
message=start_msg, commit=True)
@@ -349,6 +701,8 @@ class ServerOnboardingService:
if nxt:
cls._set_state(server, nxt)
db.session.commit()
+ cls._audit('server.onboarding.step', server,
+ {'state': state, 'status': 'succeeded', 'message': done_msg})
return cls.advance(server)
# ------------------------------------------------------------------ #
@@ -403,8 +757,10 @@ class ServerOnboardingService:
if state in (cls.STATE_INSTALLING_PREREQS, cls.STATE_INSTALLING_DOCKER,
cls.STATE_PAIRING_AGENT):
- # Wrap stubbed steps so an unexpected error fails gracefully
- # instead of crashing the consumer.
+ # Wrap the install/pair steps so an unexpected error fails
+ # gracefully instead of crashing the consumer. The steps are
+ # already guarded + never raise on their own; this is belt-and-
+ # suspenders for anything truly unforeseen.
try:
return step(server)
except Exception as exc: # pragma: no cover - defensive
@@ -427,6 +783,8 @@ class ServerOnboardingService:
cls._log(server, cls.STATE_READY, ServerOnboardingLog.STATUS_SUCCEEDED,
message='Server ready', commit=True)
cls._audit('server.onboarding.completed', server, {'server_id': server.id})
+ cls._notify('server.onboarding.ready', server,
+ {'summary': f'Server {server.name or server.id} is ready.'})
@classmethod
def retry(cls, server_id):
diff --git a/backend/app/services/shared_resource_service.py b/backend/app/services/shared_resource_service.py
index 52b41f23..02b40774 100644
--- a/backend/app/services/shared_resource_service.py
+++ b/backend/app/services/shared_resource_service.py
@@ -16,6 +16,8 @@ group wins** on key collisions ("last attachment wins"). Each resolved entry
records the ``group_id``/``group_name`` it came from so callers can show
provenance.
"""
+import re
+
from app import db
from app.models.shared_resource import (
ResourceTag,
@@ -25,6 +27,33 @@ from app.models.shared_resource import (
)
+def _audit(action, **kwargs):
+ """Best-effort audit log for a shared-resource mutation.
+
+ Audit logging must never break the underlying write, so any failure here
+ (missing request context, telemetry hiccup, etc.) is swallowed. We reuse
+ the generic ``resource.*`` actions plus a ``feature: 'shared_resource'``
+ marker in ``details`` so these rows are filterable without a new action
+ constant or DB table.
+ """
+ try:
+ from app.services.audit_service import AuditService
+ details = kwargs.pop('details', None) or {}
+ details.setdefault('feature', 'shared_resource')
+ AuditService.log(action, details=details, **kwargs)
+ except Exception:
+ pass
+
+
+def _current_user_id():
+ """Resolve the acting user id from the JWT, or None outside a request."""
+ try:
+ from flask_jwt_extended import get_jwt_identity
+ return get_jwt_identity()
+ except Exception:
+ return None
+
+
class SharedResourceService:
"""Static facade for tags and shared variable groups."""
@@ -69,6 +98,12 @@ class SharedResourceService:
return ResourceTag.query.filter_by(
resource_type=resource_type, resource_id=rid, tag=tag
).first()
+ _audit(
+ 'resource.update',
+ user_id=_current_user_id(),
+ target_type=resource_type,
+ details={'op': 'tag.add', 'resource_id': rid, 'tag': tag},
+ )
return row
@staticmethod
@@ -82,6 +117,13 @@ class SharedResourceService:
return False
db.session.delete(row)
db.session.commit()
+ _audit(
+ 'resource.update',
+ user_id=_current_user_id(),
+ target_type=resource_type,
+ details={'op': 'tag.remove', 'resource_id': rid,
+ 'tag': (tag or '').strip()},
+ )
return True
@staticmethod
@@ -121,6 +163,15 @@ class SharedResourceService:
)
db.session.add(group)
db.session.commit()
+ _audit(
+ 'resource.create',
+ user_id=_current_user_id(),
+ target_type='shared_variable_group',
+ target_id=group.id,
+ details={'op': 'group.create', 'scope_type': scope_type,
+ 'scope_id': SharedResourceService._rid(scope_id),
+ 'name': group.name},
+ )
return group
@staticmethod
@@ -150,6 +201,13 @@ class SharedResourceService:
if description is not None:
group.description = description or None
db.session.commit()
+ _audit(
+ 'resource.update',
+ user_id=_current_user_id(),
+ target_type='shared_variable_group',
+ target_id=group.id,
+ details={'op': 'group.update', 'name': group.name},
+ )
return group
@staticmethod
@@ -158,8 +216,16 @@ class SharedResourceService:
group = SharedVariableGroup.query.get(group_id)
if not group:
return False
+ name = group.name
db.session.delete(group)
db.session.commit()
+ _audit(
+ 'resource.delete',
+ user_id=_current_user_id(),
+ target_type='shared_variable_group',
+ target_id=group_id,
+ details={'op': 'group.delete', 'name': name},
+ )
return True
# --------------------------------------------- variables within a group
@@ -175,6 +241,7 @@ class SharedResourceService:
raise ValueError('key is required')
var = SharedVariable.query.filter_by(group_id=group_id, key=key).first()
+ created = var is None
if var is None:
var = SharedVariable(group_id=group_id, key=key, is_secret=bool(is_secret))
var.value = value if value is not None else ''
@@ -183,6 +250,14 @@ class SharedResourceService:
var.value = value if value is not None else ''
var.is_secret = bool(is_secret)
db.session.commit()
+ _audit(
+ 'resource.update',
+ user_id=_current_user_id(),
+ target_type='shared_variable_group',
+ target_id=group_id,
+ details={'op': 'variable.create' if created else 'variable.update',
+ 'key': key, 'is_secret': bool(is_secret)},
+ )
return var
@staticmethod
@@ -195,6 +270,14 @@ class SharedResourceService:
if is_secret is not None:
var.is_secret = bool(is_secret)
db.session.commit()
+ _audit(
+ 'resource.update',
+ user_id=_current_user_id(),
+ target_type='shared_variable_group',
+ target_id=var.group_id,
+ details={'op': 'variable.update', 'key': var.key,
+ 'is_secret': bool(var.is_secret)},
+ )
return var
@staticmethod
@@ -202,8 +285,16 @@ class SharedResourceService:
var = SharedVariable.query.get(variable_id)
if not var:
return False
+ group_id, key = var.group_id, var.key
db.session.delete(var)
db.session.commit()
+ _audit(
+ 'resource.update',
+ user_id=_current_user_id(),
+ target_type='shared_variable_group',
+ target_id=group_id,
+ details={'op': 'variable.delete', 'key': key},
+ )
return True
@staticmethod
@@ -239,6 +330,13 @@ class SharedResourceService:
return SharedVariableGroupAttachment.query.filter_by(
group_id=group_id, resource_type=resource_type, resource_id=rid
).first()
+ _audit(
+ 'resource.update',
+ user_id=_current_user_id(),
+ target_type=resource_type,
+ details={'op': 'group.attach', 'resource_id': rid,
+ 'group_id': group_id},
+ )
return att
@staticmethod
@@ -252,6 +350,13 @@ class SharedResourceService:
return False
db.session.delete(att)
db.session.commit()
+ _audit(
+ 'resource.update',
+ user_id=_current_user_id(),
+ target_type=resource_type,
+ details={'op': 'group.detach', 'resource_id': rid,
+ 'group_id': group_id},
+ )
return True
@staticmethod
@@ -295,3 +400,134 @@ class SharedResourceService:
}
return [resolved[k] for k in sorted(resolved.keys())]
+
+ # ------------------------------------------------ hierarchical resolve
+
+ # Precedence ladder, lowest → highest. The most specific scope wins on a
+ # key collision, with directly-attached groups overriding every inherited
+ # scope. ``resource`` is reserved for a resource's own direct variables and
+ # always wins last.
+ SCOPE_PRECEDENCE = ('workspace', 'project', 'environment', 'direct', 'resource')
+
+ # Matches ``{{group.KEY}}`` references for cross-variable interpolation.
+ _REF_RE = re.compile(r'\{\{\s*group\.([A-Za-z0-9_.\-]+)\s*\}\}')
+
+ @staticmethod
+ def _interpolate(value, plaintext_by_key, _depth=0):
+ """Resolve ``{{group.KEY}}`` references within a plaintext value.
+
+ References point at other resolved keys (the plaintext map). Unknown
+ references are left verbatim. Recursion is depth-bounded so a cycle
+ (A→B→A) degrades to the raw token instead of looping forever. This only
+ runs on already-decrypted plaintext, so secrets are interpolated before
+ masking — never the mask glyphs.
+ """
+ if not isinstance(value, str) or '{{' not in value or _depth > 8:
+ return value
+
+ def _sub(match):
+ ref_key = match.group(1)
+ if ref_key not in plaintext_by_key:
+ return match.group(0) # leave unknown refs untouched
+ return SharedResourceService._interpolate(
+ plaintext_by_key[ref_key], plaintext_by_key, _depth + 1
+ )
+
+ return SharedResourceService._REF_RE.sub(_sub, value)
+
+ @staticmethod
+ def resolve_hierarchical_from_layers(layers, direct_vars=None,
+ mask_secrets=True, interpolate=True):
+ """Pure merge over pre-fetched layers — the unit-testable core.
+
+ ``layers`` is an ordered iterable of ``(source_scope, groups)`` tuples
+ applied lowest → highest precedence; each ``groups`` is an iterable of
+ :class:`SharedVariableGroup`. ``direct_vars`` is an optional iterable of
+ :class:`SharedVariable` representing the resource's own direct variables,
+ which always take top precedence (``source_scope='resource'``).
+
+ A later layer overrides an earlier one on key collisions ("most specific
+ wins"). Each resolved entry records the ``source_scope`` it won at plus
+ its source group. Secrets are masked in the returned ``value`` when
+ ``mask_secrets`` is set, but ``{{group.KEY}}`` interpolation runs on the
+ decrypted plaintext first so references resolve correctly regardless of
+ masking.
+ """
+ # First pass (lowest → highest): accumulate the winning entry per key
+ # along with its decrypted plaintext, so interpolation can see the
+ # final effective set.
+ resolved = {}
+ plaintext_by_key = {}
+
+ def _apply(source_scope, var, group):
+ plaintext = var.value # decrypted
+ resolved[var.key] = {
+ 'key': var.key,
+ 'plaintext': plaintext,
+ 'is_secret': bool(var.is_secret),
+ 'group_id': group.id if group is not None else None,
+ 'group_name': group.name if group is not None else None,
+ 'source_scope': source_scope,
+ }
+ plaintext_by_key[var.key] = plaintext
+
+ for source_scope, groups in layers:
+ for group in (groups or []):
+ for var in group.variables:
+ _apply(source_scope, var, group)
+
+ for var in (direct_vars or []):
+ _apply('resource', var, None)
+
+ # Second pass: interpolate references against the final plaintext map,
+ # then mask. Two passes keep references stable even when the referenced
+ # value is overridden by a more specific scope.
+ out = []
+ for key in sorted(resolved.keys()):
+ entry = resolved[key]
+ plaintext = entry.pop('plaintext')
+ if interpolate:
+ plaintext = SharedResourceService._interpolate(
+ plaintext, plaintext_by_key
+ )
+ entry['value'] = ('••••••••' if (mask_secrets and entry['is_secret'])
+ else plaintext)
+ out.append(entry)
+ return out
+
+ @staticmethod
+ def resolve_hierarchical(resource_type, resource_id, context=None,
+ mask_secrets=True, interpolate=True):
+ """DB-backed hierarchical resolution for a resource.
+
+ ``context`` may carry ``workspace_id``, ``project_id`` and
+ ``environment_id``. Groups scoped to each (by ``scope_type``/``scope_id``)
+ form the inherited layers; the resource's directly-attached groups form
+ the ``direct`` layer on top. Precedence, lowest → highest:
+
+ workspace < project < environment < direct attachments
+
+ See :meth:`resolve_hierarchical_from_layers` for the pure merge.
+ """
+ context = context or {}
+ layers = []
+
+ def _scoped(scope_type, scope_id):
+ if scope_id in (None, ''):
+ return []
+ return SharedResourceService.list_groups(
+ scope_type=scope_type, scope_id=scope_id
+ )
+
+ layers.append(('workspace', _scoped('workspace', context.get('workspace_id'))))
+ layers.append(('project', _scoped('project', context.get('project_id'))))
+ layers.append(('environment',
+ _scoped('environment', context.get('environment_id'))))
+ layers.append(('direct',
+ SharedResourceService.list_attached_groups(
+ resource_type, resource_id)))
+
+ return SharedResourceService.resolve_hierarchical_from_layers(
+ layers, direct_vars=None, mask_secrets=mask_secrets,
+ interpolate=interpolate,
+ )
diff --git a/backend/tests/test_enhancements_integration.py b/backend/tests/test_enhancements_integration.py
new file mode 100644
index 00000000..faba9fcb
--- /dev/null
+++ b/backend/tests/test_enhancements_integration.py
@@ -0,0 +1,417 @@
+"""Cross-cutting smoke/integration test for the recently shipped capabilities.
+
+This is deliberately broad and shallow: the goal is to prove the new endpoints
+are *wired and responding sensibly* (registered on the URL map, auth enforced
+where expected, list endpoints return their documented envelope), NOT to
+re-test deep behavior — each capability already has a focused suite
+(``test_buildpacks``, ``test_proxy_stack``, ``test_projects``, ``test_previews``,
+``test_container_status``, ``test_api_scopes``, ``test_config_snapshots``,
+``test_shared_resources``, ``test_server_onboarding``, ``test_template_*``).
+
+Capabilities exercised here (matches docs/ENHANCEMENTS.md):
+
+ 1. Container status aggregator /api/v1/status/app/<id>, /api/v1/status/apps
+ 2. API token scopes /api/v1/api-keys/scopes
+ 3. Server onboarding state mc. /api/v1/servers/<id>/onboarding/*
+ 4. Declarative template catalog /api/v1/templates/catalog/schema
+ 5. Build packs /api/v1/buildpacks/detect|generate
+ 6. Deployment config snapshots /api/v1/apps/<id>/snapshots[...]
+ 7. Projects / Environments /api/v1/projects, /api/v1/environments
+ 8. Polymorphic shared resources /api/v1/shared/...
+ 9. PR preview environments /api/v1/apps/<id>/previews, webhook
+ 10. Per-server proxy stack /api/v1/servers/<id>/proxy/compose-preview
+
+Models imported at module top so they are registered on ``db.metadata`` before
+the ``app`` fixture's ``create_all()`` runs (several services import them lazily).
+"""
+import pytest
+import yaml
+
+# Force-register the new tables on the shared metadata before create_all().
+from app.models.proxy_stack import ProxyStack # noqa: F401
+from app.models.deployment_snapshot import DeploymentSnapshot # noqa: F401
+from app.models.application_preview import ApplicationPreview # noqa: F401
+from app.models.project import Project # noqa: F401
+from app.models.environment import Environment # noqa: F401
+from app.models.shared_resource import ( # noqa: F401
+ ResourceTag,
+ SharedVariableGroup,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Module-scoped app/client/auth fixtures.
+#
+# conftest's `app` fixture is function-scoped: every test spins up a fresh
+# create_app() (which starts background workers) and drop_all/create_all's the
+# *shared file-backed* test DB. Running this whole cross-cutting module that way
+# races those background workers against teardown's drop_all ("no such table"
+# during a later setup). Overriding the fixtures at MODULE scope means ONE app
+# and ONE schema for the entire module — deterministic, and still a real
+# end-to-end exercise of the live routes. These overrides shadow conftest's for
+# this module only.
+# --------------------------------------------------------------------------- #
[email protected](scope='module')
+def app():
+ from app import create_app
+ from app import db as _db
+
+ application = create_app('testing')
+ with application.app_context():
+ _db.create_all()
+ yield application
+ _db.session.remove()
+ _db.drop_all()
+
+
[email protected](scope='module')
+def client(app):
+ return app.test_client()
+
+
[email protected](scope='module')
+def auth_headers(app):
+ """An admin JWT, created once for the module (idempotent)."""
+ from app import db
+ from app.models import User
+ from flask_jwt_extended import create_access_token
+ from werkzeug.security import generate_password_hash
+
+ with app.app_context():
+ user = User.query.filter_by(username='enh-testadmin').first()
+ if user is None:
+ user = User(
+ email='[email protected]', username='enh-testadmin',
+ password_hash=generate_password_hash('testpass'),
+ role=User.ROLE_ADMIN, is_active=True,
+ )
+ db.session.add(user)
+ db.session.commit()
+ token = create_access_token(identity=user.id)
+ return {'Authorization': f'Bearer {token}'}
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+_counter = {'n': 0}
+
+
+def _uniq(prefix):
+ _counter['n'] += 1
+ return f'{prefix}-{_counter["n"]}'
+
+
+def _has_rule(app, rule_substr):
+ """True if any registered URL rule contains ``rule_substr``."""
+ return any(rule_substr in str(r) for r in app.url_map.iter_rules())
+
+
+def _make_server(app):
+ """Create one Server row, return its (string UUID) id."""
+ from app import db
+ from app.models.server import Server
+ s = Server(name=_uniq('enh-host'), agent_id=_uniq('agent-enh'))
+ db.session.add(s)
+ db.session.commit()
+ return s.id
+
+
+def _make_app(app, name='enh-app'):
+ """Create a minimal Application row (owned by a throwaway user), return id."""
+ from app import db
+ from app.models.application import Application
+ from app.models.user import User
+ from werkzeug.security import generate_password_hash
+
+ owner = User.query.filter_by(username='enh-owner').first()
+ if owner is None:
+ owner = User(
+ email='[email protected]', username='enh-owner',
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_ADMIN, is_active=True,
+ )
+ db.session.add(owner)
+ db.session.commit()
+ a = Application(name=_uniq(name), app_type='docker', user_id=owner.id)
+ db.session.add(a)
+ db.session.commit()
+ return a.id
+
+
+# --------------------------------------------------------------------------- #
+# 0. auth is enforced
+# --------------------------------------------------------------------------- #
+# Consolidated into one test (one app instance): the file-backed test DB is
+# shared across the suite and each create_app() spins up background workers, so
+# minimizing app churn keeps the cross-cutting module deterministic.
+def test_new_protected_endpoints_require_auth(client):
+ """Every new JWT-protected endpoint rejects an anonymous request."""
+ read_paths = [
+ '/api/v1/status/apps',
+ '/api/v1/api-keys/scopes',
+ '/api/v1/templates/catalog/schema',
+ '/api/v1/projects',
+ '/api/v1/shared/resource-types',
+ ]
+ for path in read_paths:
+ resp = client.get(path)
+ assert resp.status_code in (401, 422), (path, resp.status_code)
+
+ # A protected write endpoint behaves the same.
+ resp = client.post('/api/v1/buildpacks/generate', json={'plan': {}})
+ assert resp.status_code in (401, 422)
+
+
+# --------------------------------------------------------------------------- #
+# 1. Container status aggregator
+# --------------------------------------------------------------------------- #
+def test_container_status_apps_returns_list(client, auth_headers):
+ resp = client.get('/api/v1/status/apps', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert isinstance(body.get('statuses'), list)
+
+
+def test_container_status_single_app_responds(client, auth_headers, app):
+ with app.app_context():
+ app_id = _make_app(app, 'status-app')
+ resp = client.get(f'/api/v1/status/app/{app_id}', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ # Aggregator always yields a status string (never raises), even with no
+ # Docker available in the test environment.
+ assert 'status' in body
+
+
+# --------------------------------------------------------------------------- #
+# 2. API token scopes catalog
+# --------------------------------------------------------------------------- #
+def test_api_key_scopes_catalog_non_empty(client, auth_headers):
+ resp = client.get('/api/v1/api-keys/scopes', headers=auth_headers)
+ assert resp.status_code == 200
+ scopes = resp.get_json().get('scopes')
+ assert isinstance(scopes, list) and len(scopes) > 0
+ # Each row is the documented {key,label,group,description} shape.
+ assert all('key' in s for s in scopes)
+ keys = {s['key'] for s in scopes}
+ assert 'read' in keys and 'write' in keys
+
+
+# --------------------------------------------------------------------------- #
+# 3. Server onboarding state machine
+# --------------------------------------------------------------------------- #
+def test_onboarding_status_responds_for_server(client, auth_headers, app):
+ with app.app_context():
+ server_id = _make_server(app)
+ resp = client.get(
+ f'/api/v1/servers/{server_id}/onboarding/status', headers=auth_headers)
+ # 200 with a state machine payload (or a graceful service error), never 404.
+ assert resp.status_code == 200, resp.get_json()
+
+
+def test_onboarding_status_unknown_server_404(client, auth_headers):
+ resp = client.get(
+ '/api/v1/servers/does-not-exist/onboarding/status', headers=auth_headers)
+ assert resp.status_code == 404
+
+
+def test_onboarding_routes_registered(app):
+ for sub in ('/onboarding/start', '/onboarding/retry', '/onboarding/status'):
+ assert _has_rule(app, sub), sub
+
+
+# --------------------------------------------------------------------------- #
+# 4. Declarative template catalog schema
+# --------------------------------------------------------------------------- #
+def test_template_catalog_schema_exposes_magic_variables(client, auth_headers):
+ resp = client.get('/api/v1/templates/catalog/schema', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert 'variable_types' in body and body['variable_types']
+ tokens = {mv['token'] for mv in body.get('magic_variables', [])}
+ # The documented SERVICE_* magic-variable family.
+ assert '${SERVICE_PASSWORD_<NAME>}' in tokens
+ assert '${SERVICE_USER_<NAME>}' in tokens
+ assert '${SERVICE_FQDN_<NAME>}' in tokens
+ assert '${SERVICE_URL_<NAME>}' in tokens
+ assert '${SERVICE_BASE64_<NAME>}' in tokens
+
+
+# --------------------------------------------------------------------------- #
+# 5. Build packs — generate is pure, returns a Dockerfile for a simple plan
+# --------------------------------------------------------------------------- #
+def test_buildpacks_generate_returns_dockerfile(client, auth_headers):
+ plan = {
+ 'builder': 'nixpacks', 'language': 'node', 'framework': 'express',
+ 'versions': {'node': '20'}, 'build_command': 'npm run build',
+ 'start_command': 'node server.js', 'port': 3000,
+ }
+ resp = client.post(
+ '/api/v1/buildpacks/generate',
+ json={'plan': plan, 'name': 'demo'},
+ headers=auth_headers,
+ )
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert 'FROM node:20' in body['dockerfile']
+ assert 'EXPOSE 3000' in body['dockerfile']
+ assert 'services:' in body['compose']
+
+
+def test_buildpacks_generate_rejects_missing_plan(client, auth_headers):
+ resp = client.post(
+ '/api/v1/buildpacks/generate', json={}, headers=auth_headers)
+ assert resp.status_code == 400
+
+
+# --------------------------------------------------------------------------- #
+# 6. Deployment config snapshots
+# --------------------------------------------------------------------------- #
+def test_snapshots_list_returns_envelope(client, auth_headers, app):
+ with app.app_context():
+ app_id = _make_app(app, 'snap-app')
+ resp = client.get(
+ f'/api/v1/apps/{app_id}/snapshots', headers=auth_headers)
+ assert resp.status_code == 200
+ assert isinstance(resp.get_json().get('snapshots'), list)
+
+
+def test_snapshots_unknown_app_404(client, auth_headers):
+ resp = client.get('/api/v1/apps/999999/snapshots', headers=auth_headers)
+ assert resp.status_code == 404
+
+
+# --------------------------------------------------------------------------- #
+# 7. Projects / Environments round-trip
+# --------------------------------------------------------------------------- #
+def test_projects_create_and_list_roundtrip(client, auth_headers):
+ # List starts as a well-formed envelope.
+ resp = client.get('/api/v1/projects', headers=auth_headers)
+ assert resp.status_code == 200
+ assert isinstance(resp.get_json().get('projects'), list)
+
+ # Create a project (auto-creates a default environment).
+ created = client.post(
+ '/api/v1/projects',
+ json={'name': 'Integration Project'},
+ headers=auth_headers,
+ )
+ assert created.status_code == 201, created.get_json()
+ project = created.get_json()['project']
+ assert project['name'] == 'Integration Project'
+ assert project.get('environments'), 'a default environment should exist'
+
+ # It now shows up in the list.
+ listed = client.get('/api/v1/projects', headers=auth_headers).get_json()
+ assert any(p['id'] == project['id'] for p in listed['projects'])
+
+
+def test_environment_create_under_project(client, auth_headers):
+ created = client.post(
+ '/api/v1/projects', json={'name': 'Env Host Project'},
+ headers=auth_headers,
+ )
+ project_id = created.get_json()['project']['id']
+ env = client.post(
+ '/api/v1/environments',
+ json={'project_id': project_id, 'name': 'staging'},
+ headers=auth_headers,
+ )
+ assert env.status_code == 201, env.get_json()
+ assert env.get_json()['environment']['name'] == 'staging'
+
+
+# --------------------------------------------------------------------------- #
+# 8. Polymorphic shared resources
+# --------------------------------------------------------------------------- #
+def test_shared_resource_types_listed(client, auth_headers):
+ resp = client.get('/api/v1/shared/resource-types', headers=auth_headers)
+ assert resp.status_code == 200
+ assert isinstance(resp.get_json().get('resource_types'), list)
+
+
+def test_shared_variable_groups_list_envelope(client, auth_headers):
+ resp = client.get('/api/v1/shared/variable-groups', headers=auth_headers)
+ assert resp.status_code == 200
+ assert isinstance(resp.get_json().get('groups'), list)
+
+
+# --------------------------------------------------------------------------- #
+# 9. PR preview environments
+# --------------------------------------------------------------------------- #
+def test_previews_list_returns_envelope(client, auth_headers, app):
+ with app.app_context():
+ app_id = _make_app(app, 'preview-app')
+ resp = client.get(
+ f'/api/v1/apps/{app_id}/previews', headers=auth_headers)
+ assert resp.status_code == 200
+ assert isinstance(resp.get_json().get('previews'), list)
+
+
+def test_pull_request_webhook_registered_and_handles_unknown_source(app, client):
+ # Route is mounted (public — no JWT).
+ assert _has_rule(app, '/webhooks/pull-request/')
+ # An unsigned, source-less delivery is rejected cleanly (not a 500).
+ resp = client.post('/api/v1/webhooks/pull-request/sometoken', json={})
+ assert resp.status_code in (400, 404)
+
+
+# --------------------------------------------------------------------------- #
+# 10. Per-server managed proxy stack
+# --------------------------------------------------------------------------- #
+def test_proxy_compose_preview_returns_yaml_for_traefik(client, auth_headers, app):
+ with app.app_context():
+ server_id = _make_server(app)
+ resp = client.get(
+ f'/api/v1/servers/{server_id}/proxy/compose-preview?proxy_type=traefik',
+ headers=auth_headers,
+ )
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['proxy_type'] == 'traefik'
+ # The compose is real, parseable YAML describing a proxy service.
+ doc = yaml.safe_load(body['compose'])
+ assert 'proxy' in doc['services']
+
+
+def test_proxy_compose_preview_nginx_is_null(client, auth_headers, app):
+ with app.app_context():
+ server_id = _make_server(app)
+ resp = client.get(
+ f'/api/v1/servers/{server_id}/proxy/compose-preview?proxy_type=nginx',
+ headers=auth_headers,
+ )
+ assert resp.status_code == 200
+ # Host nginx is the default — no managed compose to render.
+ assert resp.get_json()['compose'] is None
+
+
+# --------------------------------------------------------------------------- #
+# cross-cutting: every new blueprint is actually mounted
+# --------------------------------------------------------------------------- #
+def test_enhancement_routes_registered(app):
+ """All ten capabilities expose their advertised routes on the URL map."""
+ expected = [
+ '/api/v1/status/apps',
+ '/api/v1/status/app/',
+ '/api/v1/api-keys/scopes',
+ '/api/v1/templates/catalog/schema',
+ '/api/v1/buildpacks/detect',
+ '/api/v1/buildpacks/generate',
+ '/api/v1/apps/<int:app_id>/snapshots',
+ '/api/v1/apps/<int:app_id>/snapshots/<int:snap_id>/diff',
+ '/api/v1/apps/<int:app_id>/snapshots/<int:snap_id>/restore',
+ '/api/v1/projects',
+ '/api/v1/environments',
+ '/api/v1/shared/resource-types',
+ '/api/v1/shared/variable-groups',
+ '/api/v1/apps/<int:app_id>/previews',
+ '/api/v1/webhooks/pull-request/',
+ '/proxy/compose-preview',
+ '/proxy/configure',
+ '/proxy/switch',
+ ]
+ rules = {str(r) for r in app.url_map.iter_rules()}
+ missing = [e for e in expected if not any(e in r for r in rules)]
+ assert not missing, f'missing routes: {missing}'
diff --git a/backend/tests/test_fleet_proxy.py b/backend/tests/test_fleet_proxy.py
new file mode 100644
index 00000000..8f065f97
--- /dev/null
+++ b/backend/tests/test_fleet_proxy.py
@@ -0,0 +1,134 @@
+"""Fleet-wide proxy overview tests (Phase 4 of C6).
+
+Covers the new ``ProxyStackService.fleet_overview()`` aggregator and the
+``GET /api/v1/servers/proxy/overview`` endpoint. The endpoint is mounted under
+``/api/v1/servers`` and must resolve to the static ``/proxy/overview`` rule
+without colliding with the per-server ``/<server_id>/proxy`` route.
+"""
+import pytest
+
+from app.services.proxy_stack_service import ProxyStackService as PS
+# Import the model at module top so it's registered on db.metadata before the
+# `app` fixture runs db.create_all() (the service imports it lazily).
+from app.models.proxy_stack import ProxyStack # noqa: F401
+
+
+def _make_server(name, agent_id):
+ from app import db
+ from app.models.server import Server
+ s = Server(name=name, agent_id=agent_id)
+ db.session.add(s)
+ db.session.commit()
+ return s.id
+
+
+# ---------------------------------------------------------------------------
+# Service: fleet_overview
+# ---------------------------------------------------------------------------
+
+def test_fleet_overview_empty_when_no_servers(app):
+ with app.app_context():
+ assert PS.fleet_overview() == []
+
+
+def test_fleet_overview_one_row_per_server(app):
+ with app.app_context():
+ sid_a = _make_server('alpha', 'agent-fp-a')
+ sid_b = _make_server('bravo', 'agent-fp-b')
+ sid_c = _make_server('charlie', 'agent-fp-c')
+
+ overview = PS.fleet_overview()
+ # A row for every server, even ones that never opted into a stack.
+ assert len(overview) == 3
+ ids = {row['server_id'] for row in overview}
+ assert ids == {sid_a, sid_b, sid_c}
+
+ # Each row carries the expected flat shape.
+ row = overview[0]
+ assert set(row.keys()) == {
+ 'server_id', 'server_name', 'proxy_type', 'status',
+ 'last_regenerated_at', 'networks_count',
+ }
+
+
+def test_fleet_overview_host_default_for_unconfigured(app):
+ with app.app_context():
+ sid = _make_server('hostonly', 'agent-fp-host')
+ overview = PS.fleet_overview()
+ assert len(overview) == 1
+ row = overview[0]
+ # No managed stack → host nginx, status 'host'.
+ assert row['server_id'] == sid
+ assert row['proxy_type'] == 'nginx'
+ assert row['status'] == 'host'
+ assert row['last_regenerated_at'] is None
+ assert row['networks_count'] == 0
+
+
+def test_fleet_overview_reflects_configured_stack(app):
+ with app.app_context():
+ sid_default = _make_server('default-srv', 'agent-fp-def')
+ sid_traefik = _make_server('traefik-srv', 'agent-fp-trf')
+
+ # Configure one server onto a managed Traefik stack.
+ PS.configure(sid_traefik, proxy_type='traefik')
+
+ overview = PS.fleet_overview()
+ by_id = {row['server_id']: row for row in overview}
+
+ # Configured server reflects its stack type; not the host default.
+ assert by_id[sid_traefik]['proxy_type'] == 'traefik'
+ assert by_id[sid_traefik]['status'] != 'host'
+ # networks_count comes from the stack's networks list (defaults to the
+ # shared serverkit network on get_or_create).
+ assert by_id[sid_traefik]['networks_count'] >= 1
+
+ # Untouched server still reports the host default.
+ assert by_id[sid_default]['proxy_type'] == 'nginx'
+ assert by_id[sid_default]['status'] == 'host'
+
+
+# ---------------------------------------------------------------------------
+# Endpoint: GET /api/v1/servers/proxy/overview
+# ---------------------------------------------------------------------------
+
+def test_overview_endpoint_resolves_and_returns_json(app, client, auth_headers):
+ with app.app_context():
+ _make_server('endpoint-srv', 'agent-fp-ep')
+
+ resp = client.get('/api/v1/servers/proxy/overview', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert isinstance(body, dict)
+ assert 'servers' in body
+ assert isinstance(body['servers'], list)
+ assert len(body['servers']) == 1
+ assert body['servers'][0]['server_name'] == 'endpoint-srv'
+
+
+def test_overview_endpoint_requires_auth(app, client):
+ # No Authorization header → JWT-protected route rejects.
+ resp = client.get('/api/v1/servers/proxy/overview')
+ assert resp.status_code in (401, 422)
+
+
+def test_overview_does_not_collide_with_per_server_proxy(app, client, auth_headers):
+ """The static /proxy/overview rule must not be captured by the dynamic
+ /<server_id>/proxy route (which would 404 'Server not found' for the
+ pseudo-id 'proxy')."""
+ with app.app_context():
+ _make_server('collide-srv', 'agent-fp-col')
+
+ overview_resp = client.get('/api/v1/servers/proxy/overview', headers=auth_headers)
+ assert overview_resp.status_code == 200
+ # If it had matched /<server_id>/proxy with server_id='proxy', the body
+ # would be a single stack dict with an 'error' or stack shape — not a
+ # 'servers' list. Assert we got the fleet shape.
+ assert 'servers' in overview_resp.get_json()
+
+
+def test_create_app_testing_still_works():
+ """Sanity: the app factory imports + builds cleanly with our additions."""
+ from app import create_app
+ app = create_app('testing')
+ assert app is not None
diff --git a/backend/tests/test_server_onboarding.py b/backend/tests/test_server_onboarding.py
index c1fb9ddc..81ec8fa0 100644
--- a/backend/tests/test_server_onboarding.py
+++ b/backend/tests/test_server_onboarding.py
@@ -7,6 +7,7 @@ after `validating` are idempotent stubs that chain via `advance`).
import pytest
from app import db
+from app.models.audit_log import AuditLog
from app.models.server import Server
from app.models.server_onboarding_log import ServerOnboardingLog
from app.services.server_onboarding_service import ServerOnboardingService as SOS
@@ -146,3 +147,196 @@ def test_register_jobs_is_callable(app):
from app.jobs import registry
from app.services.server_onboarding_service import ONBOARDING_JOB_KIND
assert registry.is_registered(ONBOARDING_JOB_KIND)
+
+
+# --------------------------------------------------------------------------- #
+# pre_flight_check — PURE function matrices (no app context needed)
+# --------------------------------------------------------------------------- #
+
+def test_preflight_fully_compatible_host():
+ result = SOS.pre_flight_check({
+ 'architecture': 'x86_64',
+ 'os_type': 'linux',
+ 'distro': 'ubuntu',
+ 'kernel': '5.15.0-89-generic',
+ 'cpu_cores': 4,
+ 'total_memory': 8 * 1024 * 1024 * 1024,
+ })
+ assert result['compatible'] is True
+ assert result['blocking'] == []
+ by_name = {c['name']: c for c in result['checks']}
+ assert by_name['architecture']['ok'] is True
+ assert by_name['distro']['ok'] is True
+ assert by_name['kernel']['ok'] is True
+ assert by_name['cpu']['ok'] is True
+ assert by_name['memory']['ok'] is True
+
+
+def test_preflight_arm64_alias_supported():
+ result = SOS.pre_flight_check({'architecture': 'aarch64', 'os_type': 'linux'})
+ assert result['compatible'] is True
+ by_name = {c['name']: c for c in result['checks']}
+ assert by_name['architecture']['ok'] is True
+
+
+def test_preflight_unsupported_arch_blocks():
+ result = SOS.pre_flight_check({'architecture': 'ppc64le', 'os_type': 'linux'})
+ assert result['compatible'] is False
+ assert 'architecture' in result['blocking']
+
+
+def test_preflight_non_linux_os_blocks():
+ result = SOS.pre_flight_check({
+ 'architecture': 'x86_64', 'os_type': 'windows',
+ })
+ assert result['compatible'] is False
+ assert 'os' in result['blocking']
+
+
+def test_preflight_old_kernel_blocks():
+ result = SOS.pre_flight_check({
+ 'architecture': 'x86_64', 'os_type': 'linux', 'kernel': '2.6.32',
+ })
+ assert result['compatible'] is False
+ assert 'kernel' in result['blocking']
+
+
+def test_preflight_too_little_memory_blocks():
+ result = SOS.pre_flight_check({
+ 'architecture': 'x86_64', 'os_type': 'linux',
+ 'total_memory': 128 * 1024 * 1024, # 128 MiB
+ })
+ assert result['compatible'] is False
+ assert 'memory' in result['blocking']
+
+
+def test_preflight_zero_cpu_blocks():
+ result = SOS.pre_flight_check({
+ 'architecture': 'x86_64', 'os_type': 'linux', 'cpu_cores': 0,
+ })
+ assert result['compatible'] is False
+ assert 'cpu' in result['blocking']
+
+
+def test_preflight_sparse_info_is_unknown_not_blocking():
+ # Empty system_info: nothing is known, so nothing blocks.
+ result = SOS.pre_flight_check({})
+ assert result['compatible'] is True
+ assert result['blocking'] == []
+ # All checks are "unknown" (ok is None).
+ assert all(c['ok'] is None for c in result['checks'])
+
+
+def test_preflight_unrecognized_distro_blocks():
+ result = SOS.pre_flight_check({
+ 'architecture': 'x86_64', 'os_type': 'linux', 'distro': 'plan9',
+ })
+ assert result['compatible'] is False
+ assert 'distro' in result['blocking']
+
+
+def test_preflight_none_input_safe():
+ # None must not crash and must be treated as fully-unknown.
+ result = SOS.pre_flight_check(None)
+ assert result['compatible'] is True
+
+
+def test_preflight_stringy_values_coerced():
+ result = SOS.pre_flight_check({
+ 'architecture': 'amd64', 'os_type': 'linux',
+ 'cpu_cores': '2', 'total_memory': str(2 * 1024 * 1024 * 1024),
+ })
+ assert result['compatible'] is True
+ by_name = {c['name']: c for c in result['checks']}
+ assert by_name['cpu']['ok'] is True
+ assert by_name['memory']['ok'] is True
+
+
+# --------------------------------------------------------------------------- #
+# Real-but-guarded steps + audit emission
+# --------------------------------------------------------------------------- #
+
+def test_incompatible_host_fails_at_validate(app):
+ with app.app_context():
+ # Reachable endpoint but a known-bad architecture -> preflight blocks.
+ server = _make_server(architecture='ppc64le', os_type='linux')
+ status = SOS.start(server.id)
+ assert status['state'] == SOS.STATE_FAILED
+
+ failed = ServerOnboardingLog.query.filter_by(
+ server_id=server.id, status=ServerOnboardingLog.STATUS_FAILED
+ ).all()
+ assert any(f.state == SOS.STATE_VALIDATING for f in failed)
+ # The failure detail carries the pre-flight result.
+ detail = failed[0].get_detail()
+ assert detail.get('preflight', {}).get('compatible') is False
+
+
+def test_guarded_steps_reach_ready_on_dev(app):
+ # On Windows/dev (and on Linux without the tooling) every install/pair step
+ # degrades to a safe success, so the pipeline still completes.
+ with app.app_context():
+ server = _make_server()
+ status = SOS.start(server.id)
+ assert status['state'] == SOS.STATE_READY
+
+ # Each step logged a succeeded row with a human-readable message.
+ succeeded = ServerOnboardingLog.query.filter_by(
+ server_id=server.id, status=ServerOnboardingLog.STATUS_SUCCEEDED
+ ).all()
+ states_done = {r.state for r in succeeded}
+ assert SOS.STATE_INSTALLING_PREREQS in states_done
+ assert SOS.STATE_INSTALLING_DOCKER in states_done
+ assert SOS.STATE_PAIRING_AGENT in states_done
+
+
+def test_install_prerequisites_idempotent_detail(app):
+ # Calling the underlying helper twice must never raise and must return a
+ # (message, detail) pair both times (degrades on dev).
+ with app.app_context():
+ msg1, detail1 = SOS._do_install_prerequisites()
+ msg2, detail2 = SOS._do_install_prerequisites()
+ assert isinstance(msg1, str) and isinstance(detail1, dict)
+ assert isinstance(msg2, str) and isinstance(detail2, dict)
+
+
+def test_pair_agent_records_waiting_when_not_enrolled(app):
+ with app.app_context():
+ # Endpoint present (so validate passes) but no agent credentials.
+ server = _make_server(agent_id=None)
+ SOS.start(server.id)
+
+ pair_logs = ServerOnboardingLog.query.filter_by(
+ server_id=server.id, state=SOS.STATE_PAIRING_AGENT,
+ status=ServerOnboardingLog.STATUS_SUCCEEDED,
+ ).all()
+ assert len(pair_logs) >= 1
+ detail = pair_logs[-1].get_detail()
+ assert detail.get('registered') is False
+ assert 'waiting' in detail
+
+
+def test_audit_rows_written_for_transitions(app):
+ with app.app_context():
+ server = _make_server()
+ SOS.start(server.id)
+
+ actions = {a.action for a in AuditLog.query.all()}
+ assert 'server.onboarding.started' in actions
+ assert 'server.onboarding.step' in actions
+ assert 'server.onboarding.completed' in actions
+
+ # The started audit stashes the server id inside details (target_id is
+ # an Integer column, server ids are UUID strings).
+ started = AuditLog.query.filter_by(
+ action='server.onboarding.started').first()
+ assert started is not None
+ assert started.get_details().get('server_id') == server.id
+
+
+def test_audit_failure_row_written(app):
+ with app.app_context():
+ server = _make_server(hostname=None, ip_address=None, agent_id=None)
+ SOS.start(server.id)
+ actions = {a.action for a in AuditLog.query.all()}
+ assert 'server.onboarding.failed' in actions
diff --git a/backend/tests/test_shared_resources.py b/backend/tests/test_shared_resources.py
index fbb204a2..a81fe451 100644
--- a/backend/tests/test_shared_resources.py
+++ b/backend/tests/test_shared_resources.py
@@ -240,3 +240,171 @@ def test_api_tag_and_resolve_roundtrip(app, client, auth):
def test_api_requires_auth(app, client):
assert client.get('/api/v1/shared/variable-groups').status_code == 401
+
+
+# ----------------------------------------------------- hierarchical resolve
+
+def test_hierarchical_precedence_workspace_to_direct(app):
+ """workspace < project < environment < direct attachments (most specific wins)."""
+ from app.services.shared_resource_service import SharedResourceService as S
+
+ ws = S.create_group('workspace', 'ws-1', 'Workspace')
+ S.set_variable(ws.id, 'TIER', 'workspace', is_secret=False)
+ S.set_variable(ws.id, 'WS_ONLY', 'w', is_secret=False)
+
+ proj = S.create_group('project', 'proj-1', 'Project')
+ S.set_variable(proj.id, 'TIER', 'project', is_secret=False)
+ S.set_variable(proj.id, 'PROJ_ONLY', 'p', is_secret=False)
+
+ envg = S.create_group('environment', 'env-1', 'Environment')
+ S.set_variable(envg.id, 'TIER', 'environment', is_secret=False)
+
+ direct = S.create_group('workspace', 'ws-1', 'Direct Override')
+ S.set_variable(direct.id, 'TIER', 'direct', is_secret=False)
+ S.attach_group(direct.id, 'application', 100)
+
+ resolved = S.resolve_hierarchical(
+ 'application', 100,
+ context={'workspace_id': 'ws-1', 'project_id': 'proj-1',
+ 'environment_id': 'env-1'},
+ mask_secrets=True,
+ )
+ by_key = {v['key']: v for v in resolved}
+
+ # Direct attachment wins the collision across every inherited scope.
+ assert by_key['TIER']['value'] == 'direct'
+ assert by_key['TIER']['source_scope'] == 'direct'
+ # Inherited-only keys survive with their own provenance.
+ assert by_key['WS_ONLY']['source_scope'] == 'workspace'
+ assert by_key['PROJ_ONLY']['source_scope'] == 'project'
+
+
+def test_hierarchical_environment_overrides_project_and_workspace(app):
+ from app.services.shared_resource_service import SharedResourceService as S
+
+ ws = S.create_group('workspace', 'ws-2', 'WS')
+ S.set_variable(ws.id, 'REGION', 'global', is_secret=False)
+ proj = S.create_group('project', 'proj-2', 'P')
+ S.set_variable(proj.id, 'REGION', 'project-region', is_secret=False)
+ envg = S.create_group('environment', 'env-2', 'E')
+ S.set_variable(envg.id, 'REGION', 'eu-west', is_secret=False)
+
+ resolved = S.resolve_hierarchical(
+ 'service', 'web-7',
+ context={'workspace_id': 'ws-2', 'project_id': 'proj-2',
+ 'environment_id': 'env-2'},
+ )
+ by_key = {v['key']: v for v in resolved}
+ assert by_key['REGION']['value'] == 'eu-west'
+ assert by_key['REGION']['source_scope'] == 'environment'
+
+
+def test_hierarchical_masks_secrets_but_keeps_provenance(app):
+ from app.services.shared_resource_service import SharedResourceService as S
+
+ ws = S.create_group('workspace', 'ws-3', 'WS')
+ S.set_variable(ws.id, 'API_TOKEN', 'tok-abc', is_secret=True)
+
+ masked = S.resolve_hierarchical(
+ 'database', 5, context={'workspace_id': 'ws-3'}, mask_secrets=True)
+ tok = {v['key']: v for v in masked}['API_TOKEN']
+ assert tok['value'] == '••••••••'
+ assert tok['is_secret'] is True
+ assert tok['source_scope'] == 'workspace'
+
+ revealed = S.resolve_hierarchical(
+ 'database', 5, context={'workspace_id': 'ws-3'}, mask_secrets=False)
+ assert {v['key']: v['value'] for v in revealed}['API_TOKEN'] == 'tok-abc'
+
+
+def test_hierarchical_pure_layers_helper(app):
+ """The pure helper merges pre-fetched layers with provenance (no DB lookups)."""
+ from app.services.shared_resource_service import SharedResourceService as S
+
+ low = S.create_group('workspace', 'ws-pure', 'Low')
+ S.set_variable(low.id, 'X', 'low', is_secret=False)
+ S.set_variable(low.id, 'ONLY_LOW', 'l', is_secret=False)
+ high = S.create_group('environment', 'env-pure', 'High')
+ S.set_variable(high.id, 'X', 'high', is_secret=False)
+
+ resolved = S.resolve_hierarchical_from_layers(
+ [('workspace', [low]), ('environment', [high])], mask_secrets=True)
+ by_key = {v['key']: v for v in resolved}
+ assert by_key['X']['value'] == 'high'
+ assert by_key['X']['source_scope'] == 'environment'
+ assert by_key['ONLY_LOW']['source_scope'] == 'workspace'
+
+
+def test_hierarchical_interpolation_of_group_refs(app):
+ """{{group.KEY}} references resolve against the effective set; secrets ok."""
+ from app.services.shared_resource_service import SharedResourceService as S
+
+ g = S.create_group('workspace', 'ws-int', 'Refs')
+ S.set_variable(g.id, 'HOST', 'db.internal', is_secret=False)
+ S.set_variable(g.id, 'PORT', '5432', is_secret=False)
+ S.set_variable(g.id, 'DSN', 'postgres://{{group.HOST}}:{{group.PORT}}/app',
+ is_secret=False)
+ # Unknown refs are left verbatim.
+ S.set_variable(g.id, 'KEEP', 'prefix-{{group.MISSING}}', is_secret=False)
+
+ resolved = S.resolve_hierarchical(
+ 'application', 200, context={'workspace_id': 'ws-int'})
+ by_key = {v['key']: v['value'] for v in resolved}
+ assert by_key['DSN'] == 'postgres://db.internal:5432/app'
+ assert by_key['KEEP'] == 'prefix-{{group.MISSING}}'
+
+
+def test_hierarchical_api_roundtrip(app, client, auth):
+ # Seed a workspace-scoped group + attach a direct override, then resolve.
+ r = client.post('/api/v1/shared/variable-groups',
+ json={'scope_type': 'workspace', 'scope_id': 'ws-api',
+ 'name': 'WS'}, headers=auth)
+ ws_id = r.get_json()['id']
+ client.post(f'/api/v1/shared/variable-groups/{ws_id}/variables',
+ json={'key': 'TIER', 'value': 'workspace'}, headers=auth)
+
+ r = client.post('/api/v1/shared/variable-groups',
+ json={'scope_type': 'workspace', 'scope_id': 'ws-api',
+ 'name': 'Direct'}, headers=auth)
+ direct_id = r.get_json()['id']
+ client.post(f'/api/v1/shared/variable-groups/{direct_id}/variables',
+ json={'key': 'TIER', 'value': 'direct'}, headers=auth)
+ client.post(f'/api/v1/shared/variable-groups/{direct_id}/attach',
+ json={'resource_type': 'application', 'resource_id': 99},
+ headers=auth)
+
+ r = client.get('/api/v1/shared/resolved/hierarchical'
+ '?resource_type=application&resource_id=99&workspace_id=ws-api',
+ headers=auth)
+ assert r.status_code == 200
+ body = r.get_json()
+ by_key = {v['key']: v for v in body['variables']}
+ assert by_key['TIER']['value'] == 'direct'
+ assert by_key['TIER']['source_scope'] == 'direct'
+
+
+# --------------------------------------------------------------- audit trail
+
+def test_audit_rows_written_on_mutations(app):
+ """Tag/group/variable/attachment mutations emit best-effort audit rows."""
+ from app.services.shared_resource_service import SharedResourceService as S
+ from app.models import AuditLog
+
+ before = AuditLog.query.count()
+
+ S.add_tag('application', 1, 'prod')
+ group = S.create_group('workspace', 'ws-a', 'Audited')
+ S.set_variable(group.id, 'K', 'v')
+ S.attach_group(group.id, 'application', 1)
+ S.detach_group(group.id, 'application', 1)
+ S.remove_tag('application', 1, 'prod')
+ S.delete_group(group.id)
+
+ rows = AuditLog.query.filter(AuditLog.id > 0).all()
+ ops = {r.get_details().get('op')
+ for r in rows
+ if r.get_details().get('feature') == 'shared_resource'}
+ # Every mutation kind left a marker row.
+ assert {'tag.add', 'tag.remove', 'group.create', 'variable.create',
+ 'group.attach', 'group.detach', 'group.delete'} <= ops
+ assert AuditLog.query.count() > before
diff --git a/docs/ENHANCEMENTS.md b/docs/ENHANCEMENTS.md
new file mode 100644
index 00000000..18ff336b
--- /dev/null
+++ b/docs/ENHANCEMENTS.md
@@ -0,0 +1,376 @@
+# Platform Enhancements
+
+A brand-neutral reference for ten capabilities that extend ServerKit's
+developer-experience, team/scale, fleet, and security surfaces. Each entry
+covers **what it is**, the **API endpoints** (verified against the live
+blueprints), the **new models/tables**, and **how it fits** the existing
+architecture — the Queue Bus job system, the Notifications layer, RBAC, and the
+agent fleet.
+
+All routes are under the `/api/v1` prefix and require a JWT
+(`@jwt_required()`) unless explicitly noted. Programmatic clients may instead
+present an `X-API-Key` header, in which case the key's **scopes** are enforced on
+top of RBAC (see [API token scopes](#2-api-token-scopes)).
+
+> **Verification note.** A cross-cutting smoke test,
+> `backend/tests/test_enhancements_integration.py`, asserts every endpoint below
+> is registered and responds sensibly. Run it with
+> `cd backend && python -m pytest tests/test_enhancements_integration.py -q`.
+
+---
+
+## Theme: Developer experience
+
+### 1. Container status aggregator
+
+**What it is.** Collapses the per-container Docker states of an application
+(its app/service/database containers) into **one** deterministic status using a
+fixed priority hierarchy:
+
+```
+degraded > restarting > running:unhealthy > starting > running:healthy
+> exited > unknown
+```
+
+The aggregation function is pure (no Docker dependency, unit-testable); the
+status-fetch helpers wire it to live Docker data behind a short-TTL cache. The
+aggregator never raises — with Docker unavailable it returns `unknown`.
+
+**Endpoints** (blueprint `container_status`, mounted at `/api/v1/status`):
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1/status/app/<int:app_id>` | Full aggregated status for one application. |
+| `GET /api/v1/status/apps` | Lightweight summary for every app: `{ "statuses": [ {app_id, status, total, healthy}, … ] }`. |
+
+**Real-time.** Clients emit the Socket.IO event `subscribe_container_status`;
+the server pushes deltas on the `container_status` channel (only changed apps
+are sent). This rides the existing Socket.IO infrastructure in
+`app/sockets.py`.
+
+**Models/tables.** None — this is a read-through aggregator over live Docker
+state plus the existing `applications` table.
+
+**Fits.** Single-status-per-app is the primitive the UI uses for status badges
+without each page re-deriving Docker state.
+
+---
+
+### 4. Declarative template catalog
+
+**What it is.** A declarative schema for the one-click application templates,
+including auto-resolved **"magic variables"** so a template never has to declare
+a generated secret/host by hand. The schema is documented in
+[`TEMPLATE_CATALOG_SCHEMA.md`](TEMPLATE_CATALOG_SCHEMA.md); the endpoint below
+surfaces it to the UI/editor so the supported tokens are never hardcoded.
+
+**Endpoint** (blueprint `templates`, mounted at `/api/v1/templates`):
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1/templates/catalog/schema` | The catalog schema: `schema_version`, the supported variable `type` values, and the magic-variable token catalog. |
+
+**Variable types.** `string`, `password` (auto-generated), `port` (always
+auto-assigned to a free host port), `uuid`, `random`.
+
+**Magic variables.** Resolved at install time and persisted to `.env` /
+surfaced post-install. `<NAME>` groups related tokens so the same `<NAME>`
+resolves consistently within one install:
+
+| Token | Resolves to |
+|---|---|
+| `${SERVICE_PASSWORD_<NAME>}` | A generated strong password, stable per `<NAME>`. |
+| `${SERVICE_USER_<NAME>}` | A generated service username (`svc_<name>_<rand>`). |
+| `${SERVICE_FQDN_<NAME>}` | Auto-assigned hostname (`<slug>.<base_domain>`) when an auto-domain is set; else a localhost placeholder. |
+| `${SERVICE_URL_<NAME>}` | Full URL derived from the FQDN and scheme. |
+| `${SERVICE_BASE64_<NAME>}` | Base64 of a freshly generated secret. |
+
+**Models/tables.** None new for the schema endpoint — templates are
+file-backed; installs continue through the existing application/template flow.
+
+**Fits.** Template installs are dispatched as Queue Bus jobs by
+`DeploymentJobService.install_template` (`POST /api/v1/templates/<id>/install`),
+so a long install runs asynchronously like every other deployment.
+
+---
+
+### 5. Build packs
+
+**What it is.** A transparent, zero-Dockerfile build layer. It inspects a
+repository for language/framework markers (e.g. `package.json`,
+`requirements.txt`, `go.mod`, `index.html`), produces a **build plan**, and
+generates a `Dockerfile` + `docker-compose` from that plan. If the repo already
+ships a `Dockerfile`, detection defers to it (`dockerfile-present`).
+
+**Endpoints** (blueprint `buildpacks`, mounted at `/api/v1/buildpacks`):
+
+| Method & path | Description |
+|---|---|
+| `POST /api/v1/buildpacks/detect` | Body `{repo_url?, branch?, source_connection_id?, repository_full_name?, path?}`. Clones to a throwaway workspace (or uses a supplied `path`), runs detection, returns `{plan, dockerfile, compose}`. Results are cached by `(repo_url, commit)`. |
+| `POST /api/v1/buildpacks/generate` | Pure. Body `{plan, overrides?, name?}`. Returns `{plan, dockerfile, compose}` with no clone. |
+
+A plan carries `builder`, `language`, `framework`, `versions`,
+`build_command`, `start_command`, `port`, `confidence`, and `notes`.
+
+**Models/tables.** No new table. The detected plan is persisted **on the
+application row**: `applications.buildpack_type`, `applications.buildpack_plan`
+(JSON), and `applications.buildpack_overrides` (JSON).
+
+**Fits.** `detect` can resolve a clone URL through a stored source connection,
+reusing the existing Connections layer; tokens are never leaked back in error
+messages.
+
+---
+
+### 6. Deployment config snapshots
+
+**What it is.** An immutable configuration snapshot captured before each
+deployment (environment variables and domains), enabling a side-by-side diff and
+a one-click restore + redeploy. Secret values are masked at snapshot time, so
+listings and diffs never leak secrets.
+
+**Endpoints** (blueprint `snapshots`, mounted at `/api/v1/apps`):
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1/apps/<int:app_id>/snapshots` | List snapshots (newest first); `?limit=` (default 50, max 200). The list view omits the full payload. |
+| `GET /api/v1/apps/<int:app_id>/snapshots/<int:snap_id>` | One snapshot including its resolved config. |
+| `GET /api/v1/apps/<int:app_id>/snapshots/<int:snap_id>/diff` | Diff against another snapshot. `?against=<id|previous>` (default `previous`). Returns `{diff, summary, has_changes, …}`. |
+| `POST /api/v1/apps/<int:app_id>/snapshots/<int:snap_id>/restore` | Restore the snapshot's config and trigger a redeploy. **Requires developer access.** |
+
+**Models/tables.** `deployment_snapshots`
+(`app/models/deployment_snapshot.py`).
+
+**Fits.** Restore goes through `ConfigurationService.restore_snapshot`, which
+re-uses the normal deployment path; RBAC gates the restore via
+`@developer_required`.
+
+---
+
+## Theme: Team & scale
+
+### 7. Projects & Environments
+
+**What it is.** A grouping hierarchy layered above applications:
+**Workspace → Project → Environment → Applications**. Creating a project
+auto-creates a default environment. Projects are workspace-scoped; access is
+derived from workspace membership (the active workspace is resolved from the
+`X-Workspace-Id` header or `?workspace_id=`, falling back to the user's
+accessible workspaces).
+
+**Endpoints** (blueprints `projects` at `/api/v1/projects`, `environments` at
+`/api/v1/environments`):
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1/projects` | List projects across accessible workspace(s), each with resource counts. |
+| `POST /api/v1/projects` | Create a project (`{name, description?, metadata?, default_environment?}`); auto-creates a default environment. Returns `201` with the project + its environments. |
+| `GET /api/v1/projects/<int:project_id>` | Project with environments and counts. |
+| `PUT /api/v1/projects/<int:project_id>` | Update name/description/metadata. |
+| `DELETE /api/v1/projects/<int:project_id>` | Delete; refuses (`409`) if applications are still assigned. |
+| `POST /api/v1/environments` | Create under a project (`{project_id, name, is_default?}`). |
+| `PUT /api/v1/environments/<int:environment_id>` | Update name / default flag. |
+| `DELETE /api/v1/environments/<int:environment_id>` | Delete; refuses (`409`) the project's only environment; otherwise detaches assigned apps. |
+| `POST /api/v1/environments/reorder` | Reorder a project's environments (`{project_id, ordered_ids}`). |
+
+**Models/tables.** `projects` (`app/models/project.py`), `environments`
+(`app/models/environment.py`). Applications gain `applications.project_id` and
+`applications.environment_id` (both nullable FKs).
+
+**Fits.** Write access is gated by `WorkspaceService.can_write_in_workspace`,
+so the existing workspace RBAC governs who may create/modify project structure.
+
+---
+
+### 8. Polymorphic shared resources (tags + variable groups)
+
+**What it is.** Two cross-resource primitives:
+
+- **Tags** — attach a label to any supported resource type and look up resources
+ by tag.
+- **Shared variable groups** — named groups of variables that can be *attached*
+ to multiple resources; an effective, merged ("resolved") view is exposed per
+ resource. Secret values are always masked in responses (group-level masking
+ plus a defense-in-depth pass through `app/utils/sensitive_data_filter.py`).
+
+**Endpoints** (blueprint `shared_resources`, mounted at `/api/v1/shared`):
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1/shared/resource-types` | The catalog of supported polymorphic resource types. |
+| `GET /api/v1/shared/tags` | Tags on a resource (`?resource_type=&resource_id=`) or resources by tag (`?tag=`). |
+| `POST /api/v1/shared/tags` | Add a tag (`{resource_type, resource_id, tag}`). |
+| `DELETE /api/v1/shared/tags` | Remove a tag (body or query params). |
+| `GET /api/v1/shared/variable-groups` | List groups (optionally scoped). |
+| `POST /api/v1/shared/variable-groups` | Create a group (`{scope_type, scope_id, name, description?}`). |
+| `GET/PUT/DELETE /api/v1/shared/variable-groups/<int:group_id>` | Fetch (with masked variables + attachments), update, or delete a group. |
+| `POST /api/v1/shared/variable-groups/<int:group_id>/variables` | Add a variable (`{key, value?, is_secret?}`). |
+| `PUT/DELETE /api/v1/shared/variable-groups/<int:group_id>/variables/<int:variable_id>` | Update / delete a variable. |
+| `POST /api/v1/shared/variable-groups/<int:group_id>/attach` | Attach the group to a resource (`{resource_type, resource_id}`). |
+| `POST /api/v1/shared/variable-groups/<int:group_id>/detach` | Detach. |
+| `GET /api/v1/shared/resolved` | Effective merged variables for a resource (`?resource_type=&resource_id=`), secrets masked. |
+
+**Models/tables.** `resource_tags`, `shared_variable_groups`,
+`shared_variables`, `shared_variable_group_attachments`
+(all in `app/models/shared_resource.py`).
+
+**Fits.** Masking reuses the central sensitive-data filter, the same primitive
+used elsewhere (e.g. API-key responses), so secrets never leak through this
+surface.
+
+---
+
+### 9. PR preview environments
+
+**What it is.** Ephemeral preview deployments driven by pull-request webhooks.
+Opening a PR provisions a preview; new commits redeploy it; closing the PR tears
+it down. Per-app settings control whether previews are enabled, the preview
+domain template, and a TTL.
+
+**Endpoints** (blueprint `previews`, mounted at `/api/v1/apps`):
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1/apps/<int:app_id>/previews` | List non-destroyed previews (newest PR first). |
+| `GET /api/v1/apps/<int:app_id>/previews/settings` | Per-app preview settings (defaults when never configured). |
+| `PUT /api/v1/apps/<int:app_id>/previews/settings` | Enable/disable + set domain template & TTL. **Developer.** |
+| `POST /api/v1/apps/<int:app_id>/previews/sync` | Reconcile previews against open PRs (best-effort). **Developer.** |
+| `POST /api/v1/apps/<int:app_id>/previews/<int:preview_id>/redeploy` | Re-provision for the same PR. **Developer.** |
+| `DELETE /api/v1/apps/<int:app_id>/previews/<int:preview_id>` | Tear down and mark destroyed. **Developer.** |
+
+**Webhook** (blueprint `preview_webhooks`, mounted at `/api/v1/webhooks`):
+
+| Method & path | Description |
+|---|---|
+| `POST /api/v1/webhooks/pull-request/<token>` | **Public** (no JWT) — authenticated by webhook signature, like the push webhook. Maps the PR action to a preview job: opened/reopened → `preview.create`, synchronize/edited → `preview.sync`, closed → `preview.destroy`. Always returns `200` with an `action` descriptor so a harmless delivery never trips provider retries. |
+
+The webhook recognizes the major hosted Git providers via their event headers
+and reuses the **push webhook's signature verification** (same secret).
+
+**Models/tables.** `application_previews` and `application_preview_settings`
+(`app/models/application_preview.py`).
+
+**Fits.** PR actions are enqueued as Queue Bus jobs
+(`preview.create` / `preview.sync` / `preview.destroy`); handlers are registered
+by `PreviewService.register_jobs()` at startup. Under the testing config the job
+system is a no-op, so a webhook never fails on enqueue.
+
+---
+
+## Theme: Fleet
+
+### 3. Server onboarding state machine
+
+**What it is.** A linear lifecycle for bringing a server under management:
+
+```
+pending → validating → installing_prerequisites → installing_docker
+ → pairing_agent → ready (or → failed)
+```
+
+State advances on the Queue Bus; the panel exposes start/retry plus a status
+read with an ordered progress log.
+
+**Endpoints** (blueprint `servers`, mounted at `/api/v1/servers`; server ids are
+UUID strings):
+
+| Method & path | Description |
+|---|---|
+| `POST /api/v1/servers/<server_id>/onboarding/start` | Begin onboarding (`pending → validating → …`). **Developer.** |
+| `POST /api/v1/servers/<server_id>/onboarding/retry` | Clear a failed onboarding and resume from validation. **Developer.** |
+| `GET /api/v1/servers/<server_id>/onboarding/status` | Current state + ordered progress log. |
+
+**Models/tables.** `server_onboarding_logs`
+(`app/models/server_onboarding_log.py`) holds the authoritative step history.
+The `servers` table caches the latest state on `onboarding_state`,
+`onboarding_progress` (JSON snapshot), and `onboarding_updated_at`.
+
+**Fits.** Advancement runs as the job kind `server.onboarding.advance` on the
+Queue Bus (handlers registered via `ServerOnboardingService.register_jobs()`),
+and the final pairing step joins the existing agent-pairing flow.
+
+---
+
+### 10. Per-server proxy stack
+
+**What it is.** An opt-in, Dockerized reverse-proxy stack selectable **per
+server**. Host nginx remains the default; an operator can switch a server to a
+managed Traefik or Caddy stack, preview the generated compose before switching,
+and (best-effort) regenerate/deploy it.
+
+**Endpoints** (blueprint `proxy`, mounted at `/api/v1/servers`; server ids are
+UUID strings):
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1/servers/<server_id>/proxy` | Managed proxy stack state for a server (best-effort status). |
+| `GET /api/v1/servers/<server_id>/proxy/compose-preview` | Preview the generated `docker-compose` for a proxy type without writing. `?proxy_type=traefik\|caddy\|nginx` (returns `compose: null` for nginx). Optional `?acme_email=` and `?dashboard=`. |
+| `POST /api/v1/servers/<server_id>/proxy/configure` | Update `proxy_type` / `custom_snippet`; optional `deploy`. **Developer.** |
+| `POST /api/v1/servers/<server_id>/proxy/regenerate` | Rewrite config and best-effort hot-reload. **Developer.** |
+| `POST /api/v1/servers/<server_id>/proxy/switch` | Switch a server's proxy type (`{proxy_type}`). **Developer.** |
+
+The generated Traefik/Caddy compose joins an external `serverkit` Docker
+network, publishes ports 80/443, and (for Caddy) persists certs/config in named
+volumes; ACME email is optional.
+
+**Models/tables.** `proxy_stacks` (`app/models/proxy_stack.py`); one row per
+server, defaulting to `nginx`.
+
+**Fits.** Reads require auth; mutations require developer access, matching the
+RBAC posture of the rest of the servers blueprint. The stack is per-server, so
+the choice is recorded against the fleet's existing server inventory.
+
+---
+
+## Theme: Security & access
+
+### 2. API token scopes
+
+**What it is.** Fine-grained, additive scopes for API keys. Scopes are
+**orthogonal to RBAC**: RBAC governs *who the user is*; a key's scopes govern
+*what that key may do*. The `require_scope` decorator is a **pass-through for
+JWT/session requests** (those are governed by RBAC) and only enforces scopes
+when a request is authenticated with an `X-API-Key` header. A `*` master scope
+grants full access; `resource:*` wildcards are honored.
+
+**Endpoint** (blueprint `api_keys`, mounted at `/api/v1/api-keys`):
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1/api-keys/scopes` | The canonical, non-empty catalog of assignable scopes. Each entry is `{key, label, group, description}`. |
+
+The catalog includes coarse-grained scopes (`read`, `write`) and resource-scoped
+entries (e.g. `apps:read`, `apps:write`, `apps:deploy`, `databases:*`,
+`domains:*`, `dns:*`, `backups:*`, `servers:read`, `servers:admin`,
+`secrets:read`). The full key lifecycle (`GET/POST /`, `GET/PUT/DELETE
+/<id>`, `POST /<id>/rotate`) lives in the same blueprint.
+
+**Secret masking.** Secret values in API responses are masked through
+`app/utils/sensitive_data_filter.py`; a key's raw value is returned exactly once,
+at creation/rotation.
+
+**Models/tables.** `api_keys` (`app/models/api_key.py`) stores the assigned
+scopes per key. The canonical scope catalog itself lives in
+`app/middleware/api_scope_middleware.py` (no table).
+
+**Fits.** `require_scope` composes with the existing auth decorators, letting one
+endpoint safely serve both the web UI (JWT + RBAC) and programmatic clients
+(API key + scopes). Key actions are written to the existing audit log.
+
+---
+
+## How these fit together
+
+- **Queue Bus jobs.** Template installs, deployment-snapshot restores, server
+ onboarding advancement, and PR-preview lifecycle all run as Queue Bus jobs —
+ the same unified orchestration the rest of ServerKit uses — so long-running
+ work is asynchronous and observable, and is a no-op under the testing config.
+- **Notifications.** Job outcomes flow through the existing notifications layer;
+ these capabilities add work to that bus rather than introducing a parallel one.
+- **RBAC + scopes.** Reads require a valid JWT; mutating/privileged routes add
+ `@developer_required` (snapshots restore, previews, proxy config, onboarding).
+ API-key callers are additionally gated by scopes.
+- **Agent fleet.** Onboarding and the per-server proxy stack are per-server and
+ recorded against the existing server inventory and agent-pairing flow.
+- **Secret hygiene.** Shared variable groups, config snapshots, and API-key
+ responses all route secret values through the central sensitive-data filter.
diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx
index 6aaa5569..1d0aa970 100644
--- a/frontend/src/App.jsx
+++ b/frontend/src/App.jsx
@@ -62,6 +62,7 @@ import WorkspaceDetail from './pages/WorkspaceDetail';
import Projects from './pages/Projects';
import ProjectDetail from './pages/ProjectDetail';
import SharedVariables from './pages/SharedVariables';
+import FleetProxy from './pages/FleetProxy';
import CloudflareZoneSettings from './pages/CloudflareZoneSettings';
import StatusPages from './pages/StatusPages';
import PublicStatusPage from './pages/PublicStatusPage';
@@ -92,6 +93,7 @@ const PAGE_TITLES = {
'/services/new': 'New Service',
'/projects': 'Projects',
'/shared-variables': 'Shared Variables',
+ '/fleet-proxy': 'Fleet Proxy',
'/apps': 'Applications',
'/wordpress': 'WordPress Sites',
'/wordpress/projects': 'WordPress Projects',
@@ -352,6 +354,7 @@ function AppRoutes() {
<Route path="servers" element={<Servers />} />
<Route path="fleet" element={<AgentFleet />} />
<Route path="fleet-monitor" element={<FleetMonitor />} />
+ <Route path="fleet-proxy" element={<FleetProxy />} />
<Route path="cloud" element={<CloudProvision />} />
<Route path="remote-access" element={<RemoteAccess />} />
<Route path="server-templates" element={<ServerTemplates />} />
diff --git a/frontend/src/components/server/OnboardingWizard.jsx b/frontend/src/components/server/OnboardingWizard.jsx
index 27c9a689..5bc1ace4 100644
--- a/frontend/src/components/server/OnboardingWizard.jsx
+++ b/frontend/src/components/server/OnboardingWizard.jsx
@@ -1,15 +1,15 @@
-import { useState, useEffect, useCallback, useRef } from 'react';
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
import api from '../../services/api';
import { useToast } from '../../contexts/ToastContext';
import { Button } from '@/components/ui/button';
import { Pill } from '../ds';
-import { CheckCircle2, Loader2, Circle, XCircle, RotateCw } from 'lucide-react';
+import { CheckCircle2, Loader2, Circle, XCircle, RotateCw, Clock } from 'lucide-react';
// The canonical ordered lifecycle steps. The backend returns the same list in
// `status.states`, but we keep a labeled copy so the wizard renders before the
// first poll resolves.
const STEPS = [
- { id: 'validating', label: 'Validate', description: 'Check server details & reachability' },
+ { id: 'validating', label: 'Validate', description: 'Check server details & compatibility' },
{ id: 'installing_prerequisites', label: 'Prerequisites', description: 'Install base packages' },
{ id: 'installing_docker', label: 'Docker', description: 'Ensure Docker is available' },
{ id: 'pairing_agent', label: 'Pair Agent', description: 'Connect the management agent' },
@@ -27,9 +27,8 @@ const IN_FLIGHT = new Set([
// Map a step's position relative to the current state to a visual status.
function stepStatus(stepId, currentState) {
if (currentState === 'failed') {
- // On failure, mark everything up to (but not including) the failed step
- // as done; we can't always know which step failed here, so lean on the
- // progress log for per-step detail. The header pill carries the failure.
+ // On failure, lean on the per-step failed log row (computed by the
+ // caller) to mark the failed step; everything else stays pending here.
return 'pending';
}
const currentIdx = STEPS.findIndex((s) => s.id === currentState);
@@ -47,10 +46,28 @@ const STEP_ICON = {
pending: Circle,
};
+// Format an elapsed duration (ms) as a compact "1m 12s" / "8s" string.
+function formatElapsed(ms) {
+ if (ms == null || ms < 0) return '0s';
+ const totalSeconds = Math.floor(ms / 1000);
+ const minutes = Math.floor(totalSeconds / 60);
+ const seconds = totalSeconds % 60;
+ if (minutes > 0) return `${minutes}m ${seconds}s`;
+ return `${seconds}s`;
+}
+
+// Short HH:MM:SS clock for a log row's created_at timestamp.
+function formatLogTime(iso) {
+ if (!iso) return '';
+ const d = new Date(iso);
+ if (Number.isNaN(d.getTime())) return '';
+ return d.toLocaleTimeString([], { hour12: false });
+}
+
/**
* OnboardingWizard — presentational + polling view of a server's onboarding
- * lifecycle. Shows the ordered steps, the current state, per-step log messages,
- * and a Retry button when onboarding has failed.
+ * lifecycle. Shows the ordered steps with per-step status icons, a live
+ * auto-scrolling log trail, elapsed time, and a Retry button on failure.
*
* Props:
* serverId — required
@@ -62,7 +79,10 @@ const OnboardingWizard = ({ serverId, initialState, onStateChange }) => {
const [status, setStatus] = useState(null);
const [loading, setLoading] = useState(true);
const [retrying, setRetrying] = useState(false);
+ // `now` ticks once a second so the elapsed timer stays live while polling.
+ const [now, setNow] = useState(() => Date.now());
const lastStateRef = useRef(initialState || null);
+ const logTrailRef = useRef(null);
const loadStatus = useCallback(async () => {
try {
@@ -93,11 +113,19 @@ const OnboardingWizard = ({ serverId, initialState, onStateChange }) => {
return () => clearInterval(interval);
}, [status, loadStatus]);
+ // Keep the elapsed timer ticking only while non-terminal.
+ useEffect(() => {
+ if (!status || status.is_terminal) return undefined;
+ const tick = setInterval(() => setNow(Date.now()), 1000);
+ return () => clearInterval(tick);
+ }, [status]);
+
async function handleRetry() {
setRetrying(true);
try {
const data = await api.retryServerOnboarding(serverId);
setStatus(data);
+ lastStateRef.current = data?.state || lastStateRef.current;
toast.success('Retrying onboarding');
loadStatus();
} catch (err) {
@@ -110,7 +138,7 @@ const OnboardingWizard = ({ serverId, initialState, onStateChange }) => {
const state = status?.state || initialState || 'pending';
const failed = state === 'failed';
const ready = state === 'ready';
- const progress = status?.progress || [];
+ const progress = useMemo(() => status?.progress || [], [status]);
// Group log messages by step so each step row can show its own trail.
const logsByState = progress.reduce((acc, row) => {
@@ -123,6 +151,23 @@ const OnboardingWizard = ({ serverId, initialState, onStateChange }) => {
? [...progress].reverse().find((r) => r.status === 'failed')
: null;
+ // Elapsed time from the first to the last (or current) log entry.
+ const elapsed = useMemo(() => {
+ if (progress.length === 0) return null;
+ const firstTs = new Date(progress[0].created_at).getTime();
+ if (Number.isNaN(firstTs)) return null;
+ const endTs = (status?.is_terminal && status?.updated_at)
+ ? new Date(status.updated_at).getTime()
+ : now;
+ return endTs - firstTs;
+ }, [progress, status, now]);
+
+ // Auto-scroll the live log trail to the bottom as new rows arrive.
+ useEffect(() => {
+ const el = logTrailRef.current;
+ if (el) el.scrollTop = el.scrollHeight;
+ }, [progress.length]);
+
const headerPillKind = failed ? 'red' : ready ? 'green' : 'amber';
const headerLabel = failed ? 'Failed' : ready ? 'Ready' : 'In progress';
@@ -132,6 +177,12 @@ const OnboardingWizard = ({ serverId, initialState, onStateChange }) => {
<div className="onboarding-wizard__title">
<h3>Server Onboarding</h3>
<Pill kind={headerPillKind}>{headerLabel}</Pill>
+ {elapsed != null && (
+ <span className="onboarding-wizard__elapsed">
+ <Clock size={13} />
+ {formatElapsed(elapsed)}
+ </span>
+ )}
</div>
{failed && (
<Button
@@ -180,24 +231,37 @@ const OnboardingWizard = ({ serverId, initialState, onStateChange }) => {
<span className="onboarding-wizard__step-label">{step.label}</span>
</div>
<p className="onboarding-wizard__step-desc">{step.description}</p>
- {stepLogs.length > 0 && (
- <ul className="onboarding-wizard__step-logs">
- {stepLogs.map((log) => (
- <li
- key={log.id}
- className={`onboarding-wizard__log onboarding-wizard__log--${log.status}`}
- >
- {log.message}
- </li>
- ))}
- </ul>
- )}
</div>
</li>
);
})}
</ol>
+ {progress.length > 0 && (
+ <div className="onboarding-wizard__trail">
+ <div className="onboarding-wizard__trail-head">Activity log</div>
+ <ul
+ ref={logTrailRef}
+ className="onboarding-wizard__trail-list"
+ aria-live="polite"
+ >
+ {progress.map((log) => (
+ <li
+ key={log.id}
+ className={`onboarding-wizard__trail-row onboarding-wizard__trail-row--${log.status}`}
+ >
+ <span className="onboarding-wizard__trail-time">
+ {formatLogTime(log.created_at)}
+ </span>
+ <span className="onboarding-wizard__trail-msg">
+ {log.message || log.status}
+ </span>
+ </li>
+ ))}
+ </ul>
+ </div>
+ )}
+
{loading && !status && (
<p className="onboarding-wizard__loading">Loading onboarding status…</p>
)}
diff --git a/frontend/src/components/servers/serverTabs.jsx b/frontend/src/components/servers/serverTabs.jsx
index f4666283..005fcb71 100644
--- a/frontend/src/components/servers/serverTabs.jsx
+++ b/frontend/src/components/servers/serverTabs.jsx
@@ -10,6 +10,7 @@ export const SERVER_TABS = [
{ to: '/servers', label: 'Servers', end: true, icon: <Server size={15} /> },
{ to: '/fleet', label: 'Agent Fleet', icon: <Users size={15} /> },
{ to: '/fleet-monitor', label: 'Fleet Monitor', icon: <Activity size={15} /> },
+ { to: '/fleet-proxy', label: 'Fleet Proxy', icon: <Network size={15} /> },
{ to: '/cloud', label: 'Cloud Servers', icon: <Cloud size={15} /> },
{ to: '/remote-access', label: 'Remote Access', icon: <Network size={15} /> },
{ to: '/server-templates', label: 'Config Templates', icon: <FileCog size={15} /> },
diff --git a/frontend/src/pages/ApplicationDetail.jsx b/frontend/src/pages/ApplicationDetail.jsx
index 9ef418d4..d86de6fd 100644
--- a/frontend/src/pages/ApplicationDetail.jsx
+++ b/frontend/src/pages/ApplicationDetail.jsx
@@ -18,6 +18,8 @@ import WafPanel from '../components/apps/WafPanel';
import PreviewList from '../components/previews/PreviewList';
import DeploymentTimeline from '../components/deployments/DeploymentTimeline';
import BuildpackPreview from '../components/buildpack/BuildpackPreview';
+import TagsPanel from '../components/shared/TagsPanel';
+import EnvironmentVariablesPanel from '../components/shared/EnvironmentVariablesPanel';
import { getServiceType, getStatusConfig } from '../utils/serviceTypes';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
@@ -541,6 +543,21 @@ const OverviewTab = ({ app, onUpdate }) => {
</div>
</div>
)}
+
+ {/* Tags Panel (polymorphic shared resource) */}
+ <div className="app-panel">
+ <div className="app-panel-header">Tags</div>
+ <div className="app-panel-body">
+ <TagsPanel resourceType="application" resourceId={app.id} />
+ </div>
+ </div>
+
+ {/* Shared Variables Panel (resolved from attached groups) */}
+ <div className="app-panel">
+ <div className="app-panel-body">
+ <EnvironmentVariablesPanel resourceType="application" resourceId={app.id} />
+ </div>
+ </div>
</div>
{showLinkModal && (
diff --git a/frontend/src/pages/FleetProxy.jsx b/frontend/src/pages/FleetProxy.jsx
new file mode 100644
index 00000000..abb983fb
--- /dev/null
+++ b/frontend/src/pages/FleetProxy.jsx
@@ -0,0 +1,207 @@
+import { useState, useEffect, useCallback, useMemo } from 'react';
+import { Link } from 'react-router-dom';
+import { Network, RefreshCw, Server as ServerIcon } from 'lucide-react';
+import api from '../services/api';
+import { useToast } from '../contexts/ToastContext';
+import { useTopbarActions } from '@/hooks/useTopbarActions';
+import { Button } from '@/components/ui/button';
+import { DataTable, Pill } from '@/components/ds';
+import EmptyState from '../components/EmptyState';
+
+// Fleet-wide reverse-proxy dashboard (Phase 4 of C6). Aggregates every
+// server's managed-proxy posture into one table: which proxy each server runs
+// (host nginx by default, or a managed Traefik/Caddy stack), its status, when
+// its config was last regenerated, and how many docker networks it joins.
+// Per-server configuration still lives on each server's Proxy tab — every row
+// links through to it.
+
+// Human label + Pill kind for each proxy type. Host nginx is the default and
+// reads as the "neutral" choice; the managed stacks get accent colors.
+const PROXY_TYPE_META = {
+ nginx: { label: 'Nginx', kind: 'gray' },
+ traefik: { label: 'Traefik', kind: 'cyan' },
+ caddy: { label: 'Caddy', kind: 'violet' },
+};
+
+// Status → Pill kind. 'host' means "host nginx, no managed stack" — a healthy
+// default, not a fault, so it reads green-ish (cyan) rather than amber.
+const STATUS_KIND = {
+ running: 'green',
+ host: 'cyan',
+ stopped: 'gray',
+ error: 'red',
+ unknown: 'amber',
+};
+
+const STATUS_LABEL = {
+ running: 'Running',
+ host: 'Host default',
+ stopped: 'Stopped',
+ error: 'Error',
+ unknown: 'Unknown',
+};
+
+function formatTimestamp(value) {
+ if (!value) return 'Never';
+ const date = new Date(value);
+ if (Number.isNaN(date.getTime())) return 'Never';
+ return date.toLocaleString();
+}
+
+function typeMeta(type) {
+ return PROXY_TYPE_META[type] || { label: type || 'Unknown', kind: 'gray' };
+}
+
+const FleetProxy = () => {
+ const toast = useToast();
+ const [rows, setRows] = useState([]);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState(null);
+
+ const load = useCallback(async () => {
+ setLoading(true);
+ try {
+ const data = await api.getFleetProxyOverview();
+ const list = Array.isArray(data?.servers) ? data.servers : [];
+ setRows(list);
+ setError(null);
+ } catch (err) {
+ setError(err.message || 'Failed to load fleet proxy overview');
+ toast.error('Failed to load fleet proxy overview');
+ } finally {
+ setLoading(false);
+ }
+ }, [toast]);
+
+ useEffect(() => {
+ load();
+ }, [load]);
+
+ // Publish a Refresh button into the shared Servers tab-group top bar.
+ useTopbarActions(() => (
+ <Button size="sm" onClick={load} disabled={loading}>
+ <RefreshCw size={16} className={loading ? 'animate-spin' : ''} />
+ Refresh
+ </Button>
+ ), [loading]);
+
+ // Summary counts by proxy type for the header.
+ const summary = useMemo(() => {
+ const counts = { total: rows.length, nginx: 0, traefik: 0, caddy: 0 };
+ rows.forEach((row) => {
+ const type = row.proxy_type || 'nginx';
+ if (counts[type] != null) counts[type] += 1;
+ });
+ return counts;
+ }, [rows]);
+
+ const summaryTiles = [
+ { key: 'total', label: 'Servers', value: summary.total, icon: ServerIcon, meta: typeMeta('nginx') },
+ { key: 'nginx', label: 'Host Nginx', value: summary.nginx, meta: typeMeta('nginx') },
+ { key: 'traefik', label: 'Traefik', value: summary.traefik, meta: typeMeta('traefik') },
+ { key: 'caddy', label: 'Caddy', value: summary.caddy, meta: typeMeta('caddy') },
+ ];
+
+ const columns = [
+ { key: 'server', header: 'Server' },
+ { key: 'type', header: 'Proxy type' },
+ { key: 'status', header: 'Status' },
+ { key: 'lastRegenerated', header: 'Last regenerated' },
+ { key: 'networks', header: 'Networks' },
+ { key: 'actions', header: '', className: 'fleet-proxy__col-actions' },
+ ];
+
+ return (
+ <div className="sk-tabgroup__inner fleet-proxy">
+ <header className="fleet-proxy__intro">
+ <div className="fleet-proxy__intro-icon">
+ <Network size={18} />
+ </div>
+ <div className="fleet-proxy__intro-text">
+ <h1>Fleet Proxy</h1>
+ <p>
+ Reverse-proxy posture across every server. Host Nginx is the default;
+ servers can opt into a managed Traefik or Caddy stack. Open a server&apos;s
+ Proxy tab to configure it.
+ </p>
+ </div>
+ </header>
+
+ <div className="fleet-proxy__summary">
+ {summaryTiles.map((tile) => {
+ const Icon = tile.icon;
+ return (
+ <div key={tile.key} className="fleet-proxy__summary-tile">
+ <span className="fleet-proxy__summary-label">
+ {Icon ? <Icon size={14} /> : (
+ <span className={`fleet-proxy__swatch fleet-proxy__swatch--${tile.meta.kind}`} />
+ )}
+ {tile.label}
+ </span>
+ <strong className="fleet-proxy__summary-value">{tile.value}</strong>
+ </div>
+ );
+ })}
+ </div>
+
+ {error ? (
+ <div className="fleet-proxy__error">
+ <p>{error}</p>
+ <Button variant="outline" size="sm" onClick={load}>Retry</Button>
+ </div>
+ ) : (
+ <div className="fleet-proxy__table">
+ <DataTable
+ loading={loading}
+ sortable={false}
+ columns={columns}
+ data={rows}
+ keyField="server_id"
+ emptyState={(
+ <EmptyState
+ icon={Network}
+ title="No servers in the fleet"
+ description="Add a server to see its reverse-proxy posture here."
+ />
+ )}
+ renderRow={(row, { key }) => {
+ const meta = typeMeta(row.proxy_type);
+ return (
+ <tr key={key} className="fleet-proxy__row">
+ <td>
+ <Link
+ to={`/servers/${row.server_id}/proxy`}
+ className="fleet-proxy__server"
+ >
+ <ServerIcon size={14} />
+ <span>{row.server_name || 'Unnamed server'}</span>
+ </Link>
+ </td>
+ <td>
+ <Pill kind={meta.kind} dot={false}>{meta.label}</Pill>
+ </td>
+ <td>
+ <Pill kind={STATUS_KIND[row.status] || 'gray'}>
+ {STATUS_LABEL[row.status] || row.status || 'Unknown'}
+ </Pill>
+ </td>
+ <td className="fleet-proxy__muted">
+ {formatTimestamp(row.last_regenerated_at)}
+ </td>
+ <td className="fleet-proxy__muted">{row.networks_count ?? 0}</td>
+ <td className="fleet-proxy__col-actions">
+ <Button asChild variant="ghost" size="sm">
+ <Link to={`/servers/${row.server_id}/proxy`}>Manage</Link>
+ </Button>
+ </td>
+ </tr>
+ );
+ }}
+ />
+ </div>
+ )}
+ </div>
+ );
+};
+
+export default FleetProxy;
diff --git a/frontend/src/pages/ServerDetail.jsx b/frontend/src/pages/ServerDetail.jsx
index 8c00eb1b..e296dc26 100644
--- a/frontend/src/pages/ServerDetail.jsx
+++ b/frontend/src/pages/ServerDetail.jsx
@@ -33,6 +33,7 @@ import SystemStatusCard from '../components/serverdetail/SystemStatusCard';
import OnboardingWizard from '../components/server/OnboardingWizard';
import ProxyStackPanel from '../components/proxy/ProxyStackPanel';
import RemoteAccess from '../pages/RemoteAccess';
+import TagsPanel from '../components/shared/TagsPanel';
import EmptyState from '../components/EmptyState';
import { BellRing, Boxes, Container, Clock3, Cloud } from 'lucide-react';
@@ -2101,6 +2102,19 @@ const SettingsTab = ({ server, onUpdate, onRegenerateToken, onDelete }) => {
</div>
</div>
+ <div className="form-section form-section--accent shared-resources-section">
+ <div className="form-section__header">
+ <span className="form-section__icon"><TagIcon /></span>
+ <div>
+ <h3>Tags</h3>
+ <p className="section-description">
+ Free-form labels for grouping and filtering this server across the panel.
+ </p>
+ </div>
+ </div>
+ <TagsPanel resourceType="server" resourceId={server.id} />
+ </div>
+
<DangerZone
title="Danger Zone"
description="Removing this server will disconnect the agent and delete all associated data."
diff --git a/frontend/src/services/api/proxy.js b/frontend/src/services/api/proxy.js
index 10865676..b976dddc 100644
--- a/frontend/src/services/api/proxy.js
+++ b/frontend/src/services/api/proxy.js
@@ -6,6 +6,13 @@ export async function getServerProxy(serverId) {
return this.request(`/servers/${serverId}/proxy`);
}
+// Fleet-wide proxy posture: one row per server. Returns { servers: [...] }.
+// Backed by GET /api/v1/servers/proxy/overview (a static prefix that never
+// collides with the per-server /servers/<id>/proxy route).
+export async function getFleetProxyOverview() {
+ return this.request('/servers/proxy/overview');
+}
+
export async function getServerProxyComposePreview(serverId, options = {}) {
const params = new URLSearchParams();
if (options.proxyType) params.set('proxy_type', options.proxyType);
diff --git a/frontend/src/styles/components/_onboarding-wizard.scss b/frontend/src/styles/components/_onboarding-wizard.scss
index f40cdd59..ba0e39ba 100644
--- a/frontend/src/styles/components/_onboarding-wizard.scss
+++ b/frontend/src/styles/components/_onboarding-wizard.scss
@@ -36,6 +36,19 @@
}
}
+ &__elapsed {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-1;
+ font-size: $font-size-xs;
+ color: $text-tertiary;
+ font-variant-numeric: tabular-nums;
+
+ svg {
+ opacity: 0.7;
+ }
+ }
+
&__error {
display: flex;
align-items: flex-start;
@@ -162,6 +175,64 @@
}
}
+ // Live, auto-scrolling activity log trail.
+ &__trail {
+ margin-top: $space-4;
+ border: 1px solid $border-color;
+ border-radius: $radius-md;
+ background: $bg-elevated;
+ overflow: hidden;
+ }
+
+ &__trail-head {
+ padding: $space-2 $space-3;
+ font-size: $font-size-xs;
+ font-weight: $font-weight-semibold;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+ color: $text-tertiary;
+ border-bottom: 1px solid $border-color;
+ }
+
+ &__trail-list {
+ list-style: none;
+ margin: 0;
+ padding: $space-2 0;
+ max-height: 180px;
+ overflow-y: auto;
+ scroll-behavior: smooth;
+ }
+
+ &__trail-row {
+ display: flex;
+ gap: $space-3;
+ padding: 2px $space-3;
+ font-family: $font-mono;
+ font-size: $font-size-xs;
+ line-height: 1.6;
+ color: $text-secondary;
+
+ &--succeeded {
+ color: $success;
+ }
+
+ &--failed {
+ color: $danger;
+ }
+ }
+
+ &__trail-time {
+ flex-shrink: 0;
+ color: $text-tertiary;
+ font-variant-numeric: tabular-nums;
+ }
+
+ &__trail-msg {
+ flex: 1;
+ min-width: 0;
+ word-break: break-word;
+ }
+
&__loading {
margin: $space-3 0 0;
font-size: $font-size-sm;
diff --git a/frontend/src/styles/components/_shared-resources.scss b/frontend/src/styles/components/_shared-resources.scss
index c7e4dc9f..99fe1714 100644
--- a/frontend/src/styles/components/_shared-resources.scss
+++ b/frontend/src/styles/components/_shared-resources.scss
@@ -355,3 +355,14 @@
}
}
}
+
+// ---------- Embedded section (resource detail pages) ----------
+// Spacing for the reusable panels when dropped into a settings/overview
+// form-section (e.g. ServerDetail). The panels carry their own internal
+// layout; this just gives the section a sensible top gap.
+
+.shared-resources-section {
+ .shared-tags {
+ margin-top: $space-2;
+ }
+}
diff --git a/frontend/src/styles/main.scss b/frontend/src/styles/main.scss
index ce8ed525..96507a03 100644
--- a/frontend/src/styles/main.scss
+++ b/frontend/src/styles/main.scss
@@ -83,6 +83,7 @@
@import 'pages/_auth';
@import 'pages/_dashboard';
@import 'pages/projects';
+@import 'pages/fleet-proxy';
@import 'pages/_applications';
@import 'pages/_docker';
@import 'pages/_databases';
diff --git a/frontend/src/styles/pages/_fleet-proxy.scss b/frontend/src/styles/pages/_fleet-proxy.scss
new file mode 100644
index 00000000..429ce9a3
--- /dev/null
+++ b/frontend/src/styles/pages/_fleet-proxy.scss
@@ -0,0 +1,143 @@
+// ============================================
+// FLEET PROXY (fleet-wide reverse-proxy dashboard)
+// ============================================
+//
+// Aggregates every server's managed-proxy posture into one table. Lives inside
+// the Servers tab group, so it renders within `.sk-tabgroup__inner` and uses
+// the shared design-system primitives (DataTable, Pill). Tokens only — no
+// hard-coded colors.
+
+.fleet-proxy {
+ display: flex;
+ flex-direction: column;
+ gap: $space-4;
+
+ // Intro: icon chip + title + one-line explanation.
+ &__intro {
+ display: flex;
+ align-items: flex-start;
+ gap: $space-3;
+ }
+
+ &__intro-icon {
+ display: inline-flex;
+ flex: none;
+ padding: $space-2;
+ border-radius: $radius-md;
+ background: var(--accent-bg);
+ color: var(--accent-bright);
+ }
+
+ &__intro-text {
+ h1 {
+ margin: 0 0 $space-1;
+ font-size: $font-size-lg;
+ font-weight: 600;
+ color: $text-primary;
+ }
+
+ p {
+ margin: 0;
+ max-width: 62ch;
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ }
+ }
+
+ // Summary strip: counts by proxy type.
+ &__summary {
+ display: grid;
+ grid-template-columns: repeat(4, 1fr);
+ gap: $space-3;
+
+ @media (max-width: $breakpoint-md) {
+ grid-template-columns: repeat(2, 1fr);
+ }
+ }
+
+ &__summary-tile {
+ display: flex;
+ flex-direction: column;
+ gap: $space-1;
+ padding: $space-3;
+ background: $bg-elevated;
+ border: 1px solid $border-subtle;
+ border-radius: $radius-md;
+ }
+
+ &__summary-label {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-2;
+ font-size: $font-size-sm;
+ color: $text-secondary;
+ }
+
+ &__summary-value {
+ font-size: $font-size-xl;
+ font-weight: 700;
+ color: $text-primary;
+ }
+
+ // Small color swatch standing in for a type icon in the summary labels.
+ &__swatch {
+ display: inline-block;
+ width: 10px;
+ height: 10px;
+ border-radius: 999px;
+ background: $text-secondary;
+
+ &--cyan { background: var(--cyan, #06b6d4); }
+ &--violet { background: var(--violet, #8b5cf6); }
+ &--gray { background: $text-secondary; }
+ &--green { background: $success; }
+ }
+
+ &__table {
+ background: $bg-card;
+ border: 1px solid $border-subtle;
+ border-radius: $radius-lg;
+ overflow: hidden;
+ }
+
+ &__row:hover {
+ background: $bg-elevated;
+ }
+
+ // Server name cell links through to the per-server Proxy tab.
+ &__server {
+ display: inline-flex;
+ align-items: center;
+ gap: $space-2;
+ color: $text-primary;
+ font-weight: 500;
+ text-decoration: none;
+
+ &:hover {
+ color: var(--accent-bright);
+ }
+ }
+
+ &__muted {
+ color: $text-secondary;
+ font-size: $font-size-sm;
+ }
+
+ &__col-actions {
+ text-align: right;
+ white-space: nowrap;
+ }
+
+ &__error {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ gap: $space-3;
+ padding: $space-4;
+ background: $danger-bg;
+ border: 1px solid $danger-border;
+ border-radius: $radius-md;
+ color: $danger;
+ font-size: $font-size-sm;
+ }
+}