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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(manifest): fleet targeting, manifest-powered previews, CLI verbs (Phase 5 backend)
Juan Denise1f9d5bb7a30
diff --git a/backend/app/services/manifest_apply_service.py b/backend/app/services/manifest_apply_service.pyindex 75ada408..5e69e7c9 100644--- a/backend/app/services/manifest_apply_service.py+++ b/backend/app/services/manifest_apply_service.py@@ -156,12 +156,14 @@ class ManifestApplyService:environment: Optional[Environment] = None) -> Dict[str, Any]:"""Diff desired manifest vs live state -> ordered action plan."""env = environment or cls._default_environment(project)+ default_server = normalized.get('server')steps: List[Dict[str, Any]] = []issues: List[Dict[str, Any]] = []services = normalized.get('services', [])for svc in services:resolved = cls.resolve_service(svc)+ resolved['server'] = resolved.get('server') or default_serverif resolved['kind'] == 'database':steps.extend(cls._plan_db(resolved))else:@@ -221,9 +223,19 @@ class ManifestApplyService:('app_type', 'port', 'healthcheck_path', 'runtime','build_command', 'start_command', 'cpu', 'memory')}payload['name'] = name+ # fleet targeting (#21): route the app to a server when declared+ server_ref = resolved.get('server')+ if server_ref:+ server_id = cls._resolve_server_id(server_ref)+ if server_id:+ payload['server_id'] = server_id+ else:+ issues.append({'service': name, 'kind': 'unknown_server',+ 'server': server_ref})+ target = ' @ ' + server_ref if server_ref else ''steps.append({'type': 'create_app', 'service': name,- 'description': f'Create app `{name}` ({resolved["app_type"]})',+ 'description': f'Create app `{name}` ({resolved["app_type"]}){target}','payload': payload,})else:@@ -445,10 +457,11 @@ class ManifestApplyService:user_id=user_id,project_id=project.id,environment_id=env.id if env else None,+ server_id=payload.get('server_id'),)db.session.add(app)db.session.commit()- return {'app_id': app.id}+ return {'app_id': app.id, 'server_id': app.server_id}@classmethoddef _do_update_app(cls, project, env, payload, user_id):@@ -696,6 +709,19 @@ class ManifestApplyService:db.session.flush()return secret+ @staticmethod+ def _resolve_server_id(server_ref: str) -> Optional[str]:+ """Resolve a fleet target name/id to a Server.id (#21). None if unknown."""+ if not server_ref:+ return None+ try:+ from app.models.server import Server+ except Exception:+ return None+ server = Server.query.filter_by(id=server_ref).first() \+ or Server.query.filter_by(name=server_ref).first()+ return server.id if server else None+@staticmethoddef _find_app(project: Project, name: Optional[str]) -> Optional[Application]:if not name:diff --git a/backend/app/services/manifest_preview_service.py b/backend/app/services/manifest_preview_service.pynew file mode 100644index 00000000..563b4dfa--- /dev/null+++ b/backend/app/services/manifest_preview_service.py@@ -0,0 +1,68 @@+"""Manifest-powered previews (plan 17, Phase 5, #20).++A PR preview for a manifest-managed app is an apply with a namespace prefix and+a TTL: it clones the manifest-resolved config (env + the existing+pr-{pr}.{app_domain} domain) with per-preview overrides. This service produces+that resolved config; the preview provisioner consumes it. Real container+spin-up for generic apps stays best-effort (Docker-dependent) — the resolved+config is the portable unit this adds on top of the WordPress-only path.+"""++import logging+from typing import Any, Dict, Optional++logger = logging.getLogger(__name__)+++class ManifestPreviewService:++ @classmethod+ def build_preview_config(cls, app, preview) -> Optional[Dict[str, Any]]:+ """Resolved config for a manifest-managed app's preview, or None."""+ from app.services.manifest_apply_service import ManifestApplyService++ resolved = ManifestApplyService.resolved_for_app(app)+ if not resolved:+ return None++ # base env = the app's effective env (manifest literals + resolved refs)+ from app.services.env_service import EnvService+ try:+ env = dict(EnvService.get_effective_env(app.id))+ except Exception:+ env = {}++ # per-preview overrides+ env['SERVERKIT_PREVIEW'] = 'true'+ env['SERVERKIT_PR_NUMBER'] = str(getattr(preview, 'pr_number', '') or '')+ if getattr(preview, 'branch', None):+ env['SERVERKIT_PREVIEW_BRANCH'] = preview.branch++ return {+ 'env': env,+ 'domain': getattr(preview, 'domain', None),+ 'port': resolved.get('port'),+ 'target_server_id': cls._preview_server_id(app, resolved),+ 'service': resolved.get('name'),+ }++ @staticmethod+ def _preview_server_id(app, resolved) -> Optional[str]:+ """Where the preview should run: preview settings win, then manifest server,+ then the app's own server. (ApplicationPreviewSettings.target_server_id was+ plumbed but unused — this makes it live.)"""+ try:+ from app.models.application_preview import ApplicationPreviewSettings+ settings = ApplicationPreviewSettings.query.filter_by(+ application_id=app.id).first()+ if settings and settings.target_server_id:+ return settings.target_server_id+ except Exception:+ pass+ server_ref = resolved.get('server')+ if server_ref:+ from app.services.manifest_apply_service import ManifestApplyService+ resolved_id = ManifestApplyService._resolve_server_id(server_ref)+ if resolved_id:+ return resolved_id+ return getattr(app, 'server_id', None)diff --git a/backend/app/services/preview_service.py b/backend/app/services/preview_service.pyindex b4f6f4dd..6a4cb57a 100644--- a/backend/app/services/preview_service.py+++ b/backend/app/services/preview_service.py@@ -329,9 +329,18 @@ class PreviewService:except Exception as exc:logger.info('WP preview provisioning unavailable: %s', exc)return {'ok': False, 'container_ids': []}- # Non-WP: the row + rendered domain is the unit of work that always- # succeeds; Docker clone is best-effort future work.- return {'ok': True, 'container_ids': []}+ # Non-WP: clone the manifest-resolved config (env + per-preview+ # overrides + domain) when the app is manifest-managed (#20). The+ # resolved config is the portable unit; a full Docker clone for+ # generic apps remains best-effort future work.+ manifest_preview = None+ try:+ from app.services.manifest_preview_service import ManifestPreviewService+ manifest_preview = ManifestPreviewService.build_preview_config(app, preview)+ except Exception as exc:+ logger.info('manifest preview config unavailable: %s', exc)+ return {'ok': True, 'container_ids': [],+ 'manifest_preview': manifest_preview}except Exception as exc:logger.info('preview provisioning unavailable: %s', exc)return {'ok': False, 'container_ids': []}diff --git a/backend/cli.py b/backend/cli.pyindex 885433e3..6d34e0bf 100644--- a/backend/cli.py+++ b/backend/cli.py@@ -1000,6 +1000,133 @@ def repair(drift_type, drift_id):click.echo(click.style(result.get('message', 'Repair triggered.'), fg='green'))+# ── manifest (serverkit.yaml) ────────────────────────────────────────────────++def _manifest_body(project_id, file_path):+ """Build the request body for the manifest endpoints."""+ body = {'project_id': project_id}+ if file_path:+ body['content'] = Path(file_path).read_text(encoding='utf-8')+ return body+++def _echo_plan_steps(steps):+ for step in steps:+ click.echo(+ f" {step.get('type', '-')} {step.get('service', '-')} "+ f"{step.get('description', '')}".rstrip()+ )+++def _echo_plan_issues(issues):+ for issue in issues or []:+ text = issue if isinstance(issue, str) else (+ issue.get('message') or issue.get('detail') or str(issue)+ )+ click.secho(f' ! {text}', fg='yellow')+++def manifest():+ """Work with a project's declarative serverkit.yaml manifest."""++[email protected]('plan')[email protected]('--project', 'project_id', type=int, required=True, help='Project id')[email protected]('--file', 'file_path', type=click.Path(exists=True), default=None,+ help='Manifest file to plan (defaults to the stored manifest)')+def manifest_plan(project_id, file_path):+ """Compute the change plan for a project's manifest (dry run)."""+ from app.services.cli_api_client import CliApiError++ try:+ data = _api_client().post('/manifests/plan', _manifest_body(project_id, file_path))+ except CliApiError as exc:+ _fail(str(exc))++ plan = data.get('plan') or {}+ steps = plan.get('steps') or []+ _echo_plan_steps(steps)+ _echo_plan_issues(plan.get('issues'))+ summary = plan.get('summary') or 'Plan computed.'+ click.echo(f"{summary} ({plan.get('step_count', len(steps))} steps)")++[email protected]('diff')[email protected]('--project', 'project_id', type=int, required=True, help='Project id')[email protected]('--file', 'file_path', type=click.Path(exists=True), default=None,+ help='Manifest file to diff (defaults to the stored manifest)')+def manifest_diff(project_id, file_path):+ """Show the human-readable diff between the manifest and live state."""+ from app.services.cli_api_client import CliApiError++ try:+ data = _api_client().post('/manifests/plan', _manifest_body(project_id, file_path))+ except CliApiError as exc:+ _fail(str(exc))++ plan = data.get('plan') or {}+ steps = plan.get('steps') or []+ if plan.get('step_count', len(steps)) == 0:+ click.echo('No changes — live state matches the manifest.')+ return+ click.echo('Planned changes:')+ _echo_plan_steps(steps)+ _echo_plan_issues(plan.get('issues'))++[email protected]('apply')[email protected]('--project', 'project_id', type=int, required=True, help='Project id')[email protected]('--file', 'file_path', type=click.Path(exists=True), default=None,+ help='Manifest file to apply (defaults to the stored manifest)')[email protected]('--yes', is_flag=True, help='Skip the confirmation prompt')+def manifest_apply(project_id, file_path, yes):+ """Apply a project's manifest to live state."""+ from app.services.cli_api_client import CliApiError++ body = _manifest_body(project_id, file_path)+ client = _api_client()++ if not yes:+ try:+ data = client.post('/manifests/plan', body)+ except CliApiError as exc:+ _fail(str(exc))+ plan = data.get('plan') or {}+ steps = plan.get('steps') or []+ if plan.get('step_count', len(steps)) == 0:+ click.echo('No changes — live state matches the manifest.')+ return+ click.echo('Planned changes:')+ _echo_plan_steps(steps)+ _echo_plan_issues(plan.get('issues'))+ if not click.confirm('Apply these changes?', default=False):+ click.echo('Aborted.')+ return++ try:+ result = client.post('/manifests/apply', body)+ except CliApiError as exc:+ _fail(str(exc))++ results = result.get('results') or []+ for r in results:+ ok = str(r.get('status', '')).lower() in ('ok', 'skipped', 'success', 'applied', 'done')+ mark = click.style('OK', fg='green') if ok else click.style('FAIL', fg='red')+ detail = r.get('error') or ''+ click.echo(f" [{mark}] {r.get('type', '-')} {r.get('service', '-')} {detail}".rstrip())++ _echo_plan_issues(result.get('issues'))++ click.echo(f"Applied {result.get('applied', len(results))} change(s).")++ if not result.get('success'):+ failed = next((r for r in results if r.get('error')), None)+ if failed:+ _fail(f"Apply failed on {failed.get('service', '?')}: {failed.get('error')}")+ _fail('Apply did not complete successfully.')++@cli.command()@click.option('--yes', is_flag=True, help='Skip the confirmation prompt')def update(yes):diff --git a/backend/tests/test_cli_manifest.py b/backend/tests/test_cli_manifest.pynew file mode 100644index 00000000..9649dbc9--- /dev/null+++ b/backend/tests/test_cli_manifest.py@@ -0,0 +1,185 @@+"""Tests for the `serverkit manifest` CLI verbs (#22): plan/apply/diff against a+stubbed API client, mirroring the monkeypatch pattern in test_cli_api.py."""+import pytest+from click.testing import CliRunner++import cli as serverkit_cli+++def _all_output(result):+ out = result.output+ try:+ out += result.stderr+ except (ValueError, AttributeError):+ pass+ return out+++class FakeClient:+ def __init__(self, responses):+ self.responses = responses+ self.calls = []++ def get(self, path):+ self.calls.append(('GET', path, None))+ return self.responses[path]++ def post(self, path, json_body=None):+ self.calls.append(('POST', path, json_body))+ resp = self.responses[path]+ if isinstance(resp, Exception):+ raise resp+ return resp+++def fake_api(monkeypatch):+ def _install(responses):+ fake = FakeClient(responses)+ monkeypatch.setattr(serverkit_cli, '_api_client', lambda with_token=True: fake)+ return fake+ return _install+++def _plan(steps, summary='Plan computed', issues=None):+ return {'plan': {+ 'steps': steps,+ 'step_count': len(steps),+ 'summary': summary,+ 'issues': issues or [],+ }}+++def test_plan_prints_steps_and_summary(fake_api):+ fake = fake_api({+ '/manifests/plan': _plan(+ [+ {'type': 'create', 'service': 'web', 'description': 'create app web'},+ {'type': 'update', 'service': 'api', 'description': 'update env'},+ ],+ summary='2 changes planned',+ ),+ })+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'plan', '--project', '7'])+ assert result.exit_code == 0, _all_output(result)+ assert ('POST', '/manifests/plan', {'project_id': 7}) in fake.calls+ assert 'create web create app web' in result.output+ assert 'update api update env' in result.output+ assert '2 changes planned' in result.output+ assert '(2 steps)' in result.output+++def test_plan_prints_issues_as_warnings(fake_api):+ fake_api({+ '/manifests/plan': _plan(+ [{'type': 'create', 'service': 'web', 'description': 'create'}],+ issues=[{'message': 'Missing secret DB_PASSWORD'}],+ ),+ })+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'plan', '--project', '1'])+ assert result.exit_code == 0, _all_output(result)+ assert 'Missing secret DB_PASSWORD' in result.output+++def test_diff_empty_plan_prints_no_changes(fake_api):+ fake_api({'/manifests/plan': _plan([])})+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'diff', '--project', '3'])+ assert result.exit_code == 0, _all_output(result)+ assert 'No changes — live state matches the manifest.' in result.output+++def test_diff_shows_planned_changes(fake_api):+ fake_api({+ '/manifests/plan': _plan(+ [{'type': 'delete', 'service': 'old', 'description': 'remove old app'}]),+ })+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'diff', '--project', '3'])+ assert result.exit_code == 0, _all_output(result)+ assert 'Planned changes:' in result.output+ assert 'delete old remove old app' in result.output+++def test_apply_yes_posts_and_reports_success(fake_api):+ fake = fake_api({+ '/manifests/apply': {+ 'success': True,+ 'applied': 2,+ 'issues': [],+ 'results': [+ {'type': 'create', 'service': 'web', 'status': 'ok'},+ {'type': 'update', 'service': 'api', 'status': 'applied'},+ ],+ 'job_id': 42,+ },+ })+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'apply', '--project', '9', '--yes'])+ assert result.exit_code == 0, _all_output(result)+ # --yes skips the plan call; only apply is posted.+ assert fake.calls == [('POST', '/manifests/apply', {'project_id': 9})]+ assert 'Applied 2 change(s).' in result.output+ assert 'web' in result.output and 'api' in result.output+++def test_apply_reports_failure_and_exits_nonzero(fake_api):+ fake_api({+ '/manifests/apply': {+ 'success': False,+ 'applied': 1,+ 'issues': [],+ 'results': [+ {'type': 'create', 'service': 'web', 'status': 'ok'},+ {'type': 'update', 'service': 'api', 'status': 'error',+ 'error': 'port in use'},+ ],+ 'job_id': 43,+ },+ })+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'apply', '--project', '9', '--yes'])+ assert result.exit_code == 1+ assert 'port in use' in _all_output(result)+++def test_apply_shows_plan_and_confirms(fake_api):+ fake = fake_api({+ '/manifests/plan': _plan(+ [{'type': 'create', 'service': 'web', 'description': 'create app web'}]),+ '/manifests/apply': {+ 'success': True, 'applied': 1, 'issues': [],+ 'results': [{'type': 'create', 'service': 'web', 'status': 'ok'}],+ 'job_id': 1,+ },+ })+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'apply', '--project', '5'], input='y\n')+ assert result.exit_code == 0, _all_output(result)+ assert 'create app web' in result.output+ posted = [c[1] for c in fake.calls]+ assert '/manifests/plan' in posted and '/manifests/apply' in posted+++def test_apply_abort_when_declined(fake_api):+ fake = fake_api({+ '/manifests/plan': _plan(+ [{'type': 'create', 'service': 'web', 'description': 'create app web'}]),+ '/manifests/apply': {'success': True, 'applied': 0, 'results': []},+ })+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'apply', '--project', '5'], input='n\n')+ assert result.exit_code == 0, _all_output(result)+ assert 'Aborted.' in result.output+ assert not any(c[1] == '/manifests/apply' for c in fake.calls)+++def test_cli_api_error_surfaces_via_fail(fake_api):+ from app.services.cli_api_client import CliApiError+ fake_api({'/manifests/plan': CliApiError('Admin access required')})+ result = CliRunner().invoke(+ serverkit_cli.cli, ['manifest', 'plan', '--project', '2'])+ assert result.exit_code == 1+ assert 'Admin access required' in _all_output(result)diff --git a/backend/tests/test_manifest_reach.py b/backend/tests/test_manifest_reach.pynew file mode 100644index 00000000..606c9356--- /dev/null+++ b/backend/tests/test_manifest_reach.py@@ -0,0 +1,121 @@+"""Proving tests for Phase 5 backend — fleet targeting + previews (plan 17)."""++import pytest++import app.models.application_manifest # noqa: F401+from app.services.manifest_spec_service import ManifestSpecService+from app.services.manifest_apply_service import ManifestApplyService+++def owner(app):+ from app import db+ from app.models import User+ user = User.query.filter_by(username='testadmin').first()+ if not user:+ user = User(username='testadmin', email='[email protected]', role='admin')+ db.session.add(user)+ db.session.commit()+ return user+++def project(app):+ from app import db+ from app.models import Project, Environment+ from app.services.workspace_service import WorkspaceService+ ws = WorkspaceService.ensure_default_workspace()+ proj = Project(workspace_id=ws.id, name='Reach', slug='reach')+ db.session.add(proj)+ db.session.commit()+ env = Environment(project_id=proj.id, name='Prod', slug='prod', is_default=True)+ db.session.add(env)+ db.session.commit()+ return proj+++def _server(name='edge'):+ from app import db+ from app.models.server import Server+ s = Server(id=f'srv-{name}', name=name)+ db.session.add(s)+ db.session.commit()+ return s+++def test_manifest_server_sets_app_server_id(project, owner):+ srv = _server('frankfurt')+ manifest = {'version': 1, 'server': 'frankfurt',+ 'services': [{'name': 'api', 'type': 'web', 'port': 8000}]}+ n = ManifestSpecService.normalize(manifest)+ plan = ManifestApplyService.plan(project, n)+ create = next(s for s in plan['steps'] if s['type'] == 'create_app')+ assert create['payload']['server_id'] == srv.id++ result = ManifestApplyService.apply(project, n, user_id=owner.id)+ assert result['success'] is True+ from app.models import Application+ api = Application.query.filter_by(project_id=project.id, name='api').first()+ assert api.server_id == srv.id+++def test_per_service_server_override(project, owner):+ _server('edge')+ home = _server('home')+ manifest = {'version': 1, 'server': 'edge',+ 'services': [{'name': 'api', 'type': 'web', 'server': 'home'}]}+ n = ManifestSpecService.normalize(manifest)+ result = ManifestApplyService.apply(project, n, user_id=owner.id)+ from app.models import Application+ api = Application.query.filter_by(project_id=project.id, name='api').first()+ assert api.server_id == home.id+++def test_unknown_server_is_plan_issue(project, owner):+ manifest = {'version': 1, 'server': 'ghost',+ 'services': [{'name': 'api', 'type': 'web'}]}+ n = ManifestSpecService.normalize(manifest)+ plan = ManifestApplyService.plan(project, n)+ assert any(i['kind'] == 'unknown_server' and i['server'] == 'ghost'+ for i in plan['issues'])+++def test_manifest_preview_config(project, owner):+ from app import db+ from app.models import Application+ from app.models.application_manifest import ApplicationManifest+ from app.services.manifest_persistence_service import ManifestPersistenceService+ from app.services.manifest_preview_service import ManifestPreviewService+ from types import SimpleNamespace++ # a manifest-managed app with declared env+ manifest = {'version': 1, 'services': [{+ 'name': 'api', 'type': 'web', 'port': 8000,+ 'envVars': [{'key': 'LOG_LEVEL', 'value': 'info'}]}]}+ n = ManifestSpecService.normalize(manifest)+ ManifestApplyService.apply(project, n, user_id=owner.id)+ ManifestPersistenceService.store_manifest(project.id, n)+ db.session.commit()++ api = Application.query.filter_by(project_id=project.id, name='api').first()+ preview = SimpleNamespace(pr_number=42, branch='feature/x',+ domain='pr-42.api.example.com')+ config = ManifestPreviewService.build_preview_config(api, preview)+ assert config is not None+ assert config['env']['LOG_LEVEL'] == 'info' # cloned manifest env+ assert config['env']['SERVERKIT_PREVIEW'] == 'true' # per-preview override+ assert config['env']['SERVERKIT_PR_NUMBER'] == '42'+ assert config['domain'] == 'pr-42.api.example.com'+++def test_preview_config_none_for_unmanaged_app(project, owner):+ from app import db+ from app.models import Application+ from app.services.manifest_preview_service import ManifestPreviewService+ from types import SimpleNamespace+ a = Application(name='plain', app_type='docker', user_id=owner.id,+ project_id=project.id, status='running')+ db.session.add(a)+ db.session.commit()+ preview = SimpleNamespace(pr_number=1, branch='b', domain='d')+ assert ManifestPreviewService.build_preview_config(a, preview) is None