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(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.py
index 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_server
if 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}
@classmethod
def _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
+
@staticmethod
def _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.py
new file mode 100644
index 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.py
index 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.py
index 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]('--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]('--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]('--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.py
new file mode 100644
index 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.py
new file mode 100644
index 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