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): reference appliance + adoption hardening (plan 35 ph6)
Juan Denis80e1fdca4469
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 92cfc9b1..60258529 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -63,6 +63,12 @@ awaiting a stable release:now attach to a shared external `serverkit` docker network (createdidempotently), so a `fromService` host reference resolves cross-app bycontainer name at runtime. Static egress IPs remain out of scope (documented).+- **Appliance tier — reference appliance + adoption hardening** — a runnable+ 4-container real-time-media reference manifest ships at+ `docs/examples/reference-appliance-media.yaml` and applies end-to-end.+ `serverkit.yaml` scaffolding now round-trips typed `ports`, a BYO `image`, and+ disk `size` from a live app, and drift detection tracks raw ports and image+ alongside the existing surface.- **New Service wizard clarity** — each source card now shows a short explainerstrip when selected (what it does, what to have ready, the next steps), and a"Docs" link to the matching serverkit.ai guide (hidden under White Label). Thediff --git a/backend/app/services/manifest_apply_service.py b/backend/app/services/manifest_apply_service.pyindex e1b9b036..e6dcfda3 100644--- a/backend/app/services/manifest_apply_service.py+++ b/backend/app/services/manifest_apply_service.py@@ -193,6 +193,19 @@ class ManifestApplyService:expected['healthcheck_path'] = resolved['healthcheck_path']observed['healthcheck_path'] = app.healthcheck_path+ # Appliance tier (plan 35): track raw ports + BYO image.+ declared_ports = resolved.get('ports') or []+ if declared_ports:+ from app.services.app_port_service import AppPortService+ def _pkey(p):+ return (f'{p.get("host_port")}:{p.get("container_port")}'+ f'/{p.get("protocol") or "tcp"}/{p.get("expose") or "public"}')+ expected['ports'] = sorted(_pkey(p) for p in declared_ports)+ observed['ports'] = sorted(_pkey(p) for p in AppPortService.get_ports(app))+ if resolved.get('image'):+ expected['image'] = resolved['image']+ observed['image'] = app.docker_image+declared_env = sorted(list(resolved.get('env', {}).keys())+ [r['key'] for r in resolved.get('env_refs', [])])if declared_env:diff --git a/backend/app/services/manifest_scaffold_service.py b/backend/app/services/manifest_scaffold_service.pyindex c18a7e50..c32c270d 100644--- a/backend/app/services/manifest_scaffold_service.py+++ b/backend/app/services/manifest_scaffold_service.py@@ -46,6 +46,13 @@ class ManifestScaffoldService:if app.port:service['port'] = app.port+ # Appliance tier (plan 35): round-trip a BYO image + typed L4 ports.+ if getattr(app, 'docker_image', None):+ service['image'] = app.docker_image+ ports = cls._ports(app)+ if ports:+ service['ports'] = ports+overrides = cls._json(app.buildpack_overrides)build_cmd = overrides.get('build_command') or overrides.get('buildCommand')start_cmd = overrides.get('start_command') or overrides.get('startCommand')@@ -121,6 +128,23 @@ class ManifestScaffoldService:entries.append({'key': key, 'value': row.get('value', '')})return entries+ @staticmethod+ def _ports(app: Application) -> List[Dict[str, Any]]:+ """Typed L4 publishes from the app row, in manifest (camelCase) form —+ only non-default fields are emitted to keep the scaffold clean."""+ from app.services.app_port_service import AppPortService+ out: List[Dict[str, Any]] = []+ for p in AppPortService.get_ports(app):+ entry: Dict[str, Any] = {'port': p['host_port']}+ if p.get('container_port') and p['container_port'] != p['host_port']:+ entry['containerPort'] = p['container_port']+ if p.get('protocol') and p['protocol'] != 'tcp':+ entry['protocol'] = p['protocol']+ if p.get('expose') and p['expose'] != 'public':+ entry['expose'] = p['expose']+ out.append(entry)+ return out+@staticmethoddef _disks(app: Application) -> List[Dict[str, Any]]:disks = []diff --git a/backend/tests/test_manifest_appliance_hardening.py b/backend/tests/test_manifest_appliance_hardening.pynew file mode 100644index 00000000..5989fa68--- /dev/null+++ b/backend/tests/test_manifest_appliance_hardening.py@@ -0,0 +1,131 @@+"""Phase 6 (#18): hardening — scaffold round-trips appliance fields, drift+tracks raw ports + image, and the docs schema copy stays in structural parity+with the embedded one."""++import json+from pathlib import Path++import pytest++import app.models.application_manifest # noqa: F401+from app.services.manifest_spec_service import ManifestSpecService, MANIFEST_SCHEMA+from app.services.manifest_apply_service import ManifestApplyService+from app.services.manifest_scaffold_service import ManifestScaffoldService+from app.services.app_port_service import AppPortService+++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')+ if hasattr(user, 'set_password'):+ user.set_password('admin')+ db.session.add(user)+ db.session.commit()+ return user+++def appliance_app(app, owner):+ from app import db+ from app.models import Application, Project, Environment+ from app.models.app_volume import AppVolume+ from app.services.workspace_service import WorkspaceService+ ws = WorkspaceService.ensure_default_workspace()+ proj = Project(workspace_id=ws.id, name='Hard', slug='hard')+ db.session.add(proj)+ db.session.commit()+ env = Environment(project_id=proj.id, name='Production', slug='production', is_default=True)+ db.session.add(env)+ db.session.commit()+ row = Application(name='edge', app_type='docker', user_id=owner.id,+ project_id=proj.id, environment_id=env.id, status='running',+ docker_image='ghcr.io/acme/edge:2')+ AppPortService.set_ports(row, [+ {'host_port': 10000, 'container_port': 10000, 'protocol': 'udp', 'expose': 'public'},+ {'host_port': 8443, 'container_port': 443, 'protocol': 'tcp', 'expose': 'local'},+ ])+ db.session.add(row)+ db.session.commit()+ db.session.add(AppVolume(application_id=row.id, name='data',+ docker_volume_name='serverkit-app-%d-data' % row.id,+ mount_path='/data', declared_size='5GB'))+ db.session.commit()+ return proj, row+++# -- scaffold round-trip ----------------------------------------------------++def test_scaffold_emits_appliance_fields(appliance_app):+ _proj, row = appliance_app+ manifest = ManifestScaffoldService.scaffold_for_app(row)+ svc = manifest['services'][0]+ assert svc['image'] == 'ghcr.io/acme/edge:2'+ # ports round-trip with non-default fields only+ ports = {p['port']: p for p in svc['ports']}+ assert ports[10000]['protocol'] == 'udp'+ assert ports[8443]['containerPort'] == 443 and ports[8443]['expose'] == 'local'+ assert 'protocol' not in ports[8443] # tcp default omitted+ # disk size round-trips+ assert svc['disks'][0]['size'] == '5GB'+ # and the scaffold is itself a valid v1 manifest+ n = ManifestSpecService.normalize(manifest)+ assert len(n['services'][0]['ports']) == 2+ assert n['services'][0]['image'] == 'ghcr.io/acme/edge:2'+++# -- drift ------------------------------------------------------------------++def test_drift_tracks_ports_and_image(appliance_app):+ from app import db+ from app.services.manifest_persistence_service import ManifestPersistenceService+ proj, row = appliance_app+ manifest = {+ 'version': 1,+ 'services': [{+ 'name': 'edge', 'type': 'docker', 'image': 'ghcr.io/acme/edge:2',+ 'ports': [{'port': 10000, 'protocol': 'udp'},+ {'port': 8443, 'containerPort': 443, 'expose': 'local'}],+ }],+ }+ n = ManifestSpecService.normalize(manifest)+ ManifestPersistenceService.store_manifest(project_id=proj.id, normalized=n,+ raw_text=None, status='applied')++ resolved = ManifestApplyService.resolved_for_app(row)+ expected, observed = ManifestApplyService.drift_pair(row, resolved)+ # in sync+ assert expected['ports'] == observed['ports']+ assert expected['image'] == observed['image'] == 'ghcr.io/acme/edge:2'++ # mutate the live image -> drift surfaces+ row.docker_image = 'ghcr.io/acme/edge:3'+ db.session.commit()+ expected, observed = ManifestApplyService.drift_pair(row, resolved)+ assert expected['image'] != observed['image']+++# -- schema copy parity -----------------------------------------------------++def test_docs_schema_copy_structural_parity():+ docs_path = Path(__file__).resolve().parents[2] / 'docs' / 'serverkit-yaml.schema.json'+ docs = json.loads(docs_path.read_text(encoding='utf-8'))++ # every embedded definition exists in the docs copy+ for name in MANIFEST_SCHEMA['definitions']:+ assert name in docs['definitions'], f'docs schema missing definition `{name}`'++ # every service property exists in the docs copy+ emb_props = MANIFEST_SCHEMA['definitions']['service']['properties']+ docs_props = docs['definitions']['service']['properties']+ for prop in emb_props:+ assert prop in docs_props, f'docs schema missing service property `{prop}`'++ # every envVar source exists in the docs copy+ emb_env = MANIFEST_SCHEMA['definitions']['envVar']['properties']+ docs_env = docs['definitions']['envVar']['properties']+ for prop in emb_env:+ assert prop in docs_env, f'docs schema missing envVar property `{prop}`'diff --git a/backend/tests/test_manifest_reference_appliance.py b/backend/tests/test_manifest_reference_appliance.pynew file mode 100644index 00000000..278ab559--- /dev/null+++ b/backend/tests/test_manifest_reference_appliance.py@@ -0,0 +1,134 @@+"""Phase 6 (#17): the reference appliance applies end-to-end.++Exercises every appliance-tier feature at once — a 4-container media unit with a+public UDP port, a config-generating bootstrap, shared disks (one backed up), a+health-gated dependsOn chain, and a fromServer public IP — against stubbed+compose/firewall/DNS."""++import json+from pathlib import Path++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+from app.services.app_port_service import AppPortService+from app.services.bootstrap_service import BootstrapService++REFERENCE = (Path(__file__).resolve().parents[2]+ / 'docs' / 'examples' / 'reference-appliance-media.yaml')+++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='Media', slug='media-ref')+ db.session.add(proj)+ db.session.commit()+ env = Environment(project_id=proj.id, name='Production', slug='production', is_default=True)+ db.session.add(env)+ db.session.commit()+ return proj+++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')+ if hasattr(user, 'set_password'):+ user.set_password('admin')+ db.session.add(user)+ db.session.commit()+ return user+++def runner_calls():+ calls = []++ def run(app, service, command, timeout):+ calls.append({'service': service, 'command': command})+ return {'success': True, 'output': 'ok'}++ BootstrapService.set_runner(run)+ yield calls+ BootstrapService.set_runner(None)++[email protected](autouse=True)+def _stub(monkeypatch):+ from app.services.docker_service import DockerService+ from app.services.domain_attach_service import DomainAttachService+ from app.services.site_domain_service import SiteDomainService+ monkeypatch.setattr(DockerService, 'create_volume',+ classmethod(lambda cls, name, driver='local': {'success': True}))+ monkeypatch.setattr(ManifestApplyService, '_port_bound', lambda port: False)+ monkeypatch.setattr(ManifestApplyService, '_firewall_state', lambda: 'active')+ monkeypatch.setattr(AppPortService, 'open_firewall', classmethod(lambda cls, ports: []))+ monkeypatch.setattr(SiteDomainService, 'server_ip', classmethod(lambda cls: '203.0.113.77'))++ def _attach(cls, app, host, ssl='auto', email=None, make_primary=False):+ from app import db as _db+ from app.models.domain import Domain+ if not any(d.name == host for d in (app.domains or [])):+ _db.session.add(Domain(name=host, application_id=app.id, is_primary=False))+ _db.session.commit()+ return {'success': True, 'domain': host, 'created': True, 'warnings': []}+ monkeypatch.setattr(DomainAttachService, 'attach', classmethod(_attach))+++def test_reference_appliance_applies_end_to_end(project, owner, runner_calls):+ from app.models import Application+ from app.models.backup_policy import BackupPolicy+ from app.services.env_service import EnvService+ from app.services.manifest_persistence_service import ManifestPersistenceService++ raw = REFERENCE.read_text(encoding='utf-8')+ n = ManifestSpecService.normalize_text(raw)+ ManifestPersistenceService.store_manifest(project_id=project.id, normalized=n,+ raw_text=raw, status='pending')++ result = ManifestApplyService.apply(project, n, user_id=owner.id)+ assert result['success'] is True, result++ # ONE Application for the whole unit+ apps = Application.query.filter_by(project_id=project.id).all()+ assert [a.name for a in apps] == ['meet']+ meet = apps[0]++ # the public UDP media port + the loopback web port are recorded+ stored = {p['host_port']: p for p in json.loads(meet.ports)}+ assert stored[10000]['protocol'] == 'udp' and stored[10000]['expose'] == 'public'+ assert stored[8443]['expose'] == 'local'+ assert AppPortService.compose_ports(json.loads(meet.ports)).count('0.0.0.0:10000:10000/udp') == 1++ # the prosody bootstrap ran exactly once, under the single flag+ assert meet.bootstrap_done is True+ assert len(runner_calls) == 1 and runner_calls[0]['service'] == 'prosody'++ # the media bridge's advertised IP is bound from the host+ env = EnvService.get_effective_env(meet.id)+ assert env.get('JVB_ADVERTISE_IP') == '203.0.113.77'+ assert env.get('PUBLIC_URL') == 'https://meet.example.com'++ # the backed-up web-config disk got a policy routed at its synthetic volume+ policy = BackupPolicy.query.filter_by(target_type='files', target_id=meet.id).first()+ assert policy is not None+ assert policy.get_target_meta().get('docker_volume') == 'meet-web-web-config'++ # the generated compose reproduces the 4-service shape+ compose = ManifestApplyService.unit_compose(meet)+ assert set(compose['services']) == {'web', 'prosody', 'jicofo', 'jvb'}+ assert compose['services']['jvb']['ports'] == ['0.0.0.0:10000:10000/udp']+ assert compose['services']['web']['depends_on'] == {'prosody': {'condition': 'service_healthy'}}++ # a second apply is a no-op+ plan2 = ManifestApplyService.plan(project, n)+ assert plan2['step_count'] == 0, plan2['summary']