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): reference appliance + adoption hardening (plan 35 ph6)

Juan Denis80e1fdca4469
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 (created
idempotently), so a `fromService` host reference resolves cross-app by
container 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 explainer
strip 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). The
diff --git a/backend/app/services/manifest_apply_service.py b/backend/app/services/manifest_apply_service.py
index 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.py
index 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
+
@staticmethod
def _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.py
new file mode 100644
index 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.py
new file mode 100644
index 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']