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): multi-container units (plan 35 ph3)
Juan Denisfdc3d4574976
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5d1697fb..6bbda9fc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -38,6 +38,16 @@ awaiting a stable release:--rm`) after volumes exist — for appliances that generate a config tree onfirst boot — and stamps the app so it never re-runs; re-arm it with`POST /manifests/bootstrap/reset` (type the app name to confirm).+- **Appliance tier — multi-container units** — a service can now declare a+ `containers:` map and become one Application rendered as one compose project+ with a private network and health-gated `dependsOn`. Each container takes the+ full vocabulary (`image`, `ports`, `disks`, `envVars`, `bootstrap`,+ `hostRequirements`, `healthCheck`, `dependsOn`); `healthCheck.cmd` becomes a+ `CMD-SHELL` probe and `healthCheck.httpPath` a `wget` probe; dependsOn is+ validated against sibling containers and rejected on cycles. Per-container+ named volumes (`{unit}-{container}-{disk}`) let two containers mount the same+ path without colliding. `dependsOn` cycles and buildpack-key mixing are+ plan-time errors.- **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/backup_policy_service.py b/backend/app/services/backup_policy_service.pyindex 55ed3b51..d0f41b3d 100644--- a/backend/app/services/backup_policy_service.py+++ b/backend/app/services/backup_policy_service.py@@ -267,6 +267,17 @@ class BackupPolicyService:file_paths = [host_path]except Exception:pass+ # Unit disks live in a synthetic per-container docker volume (plan 35);+ # resolve its live mountpoint directly by name.+ docker_volume = meta.get('docker_volume')+ if docker_volume:+ try:+ from app.services.docker_service import DockerService+ live = DockerService.inspect_volume(docker_volume)+ if live.get('present') and live.get('mountpoint'):+ file_paths = [live['mountpoint']]+ except Exception:+ passif not file_paths:raise BackupPolicyError('Files target has no paths configured')return {diff --git a/backend/app/services/manifest_apply_service.py b/backend/app/services/manifest_apply_service.pyindex d86c097d..3d97c313 100644--- a/backend/app/services/manifest_apply_service.py+++ b/backend/app/services/manifest_apply_service.py@@ -65,6 +65,43 @@ class ManifestApplyService:literal_env[var['key']] = var['value']else:env_refs.append(var)++ containers = svc.get('containers') or []+ ports = list(svc.get('ports') or [])+ disks = list(svc.get('disks') or [])+ bootstraps: List[Dict[str, Any]] = []+ if svc.get('bootstrap'):+ bootstraps.append({'service': svc['name'], **svc['bootstrap']})+ host_requirements = list(+ [svc['host_requirements']] if svc.get('host_requirements') else [])+ # unit resources (#8 `_effective_resources`): a unit is ONE Application,+ # so per-container publishes/bootstraps/host-requirements flatten up to+ # the unit. Container DISKS stay inside the generated compose (synthetic+ # per-container named volumes) to avoid mount-path collisions — so unit+ # disks are NOT folded into `disks` here; their backups route via the+ # docker volume name instead.+ unit_backups: List[Dict[str, Any]] = []+ for c in containers:+ ports.extend(c.get('ports') or [])+ if c.get('bootstrap'):+ bootstraps.append({'service': c['name'], **c['bootstrap']})+ if c.get('host_requirements'):+ host_requirements.append(c['host_requirements'])+ for var in c.get('env_vars') or []:+ if var['source'] == 'value':+ literal_env.setdefault(var['key'], var['value'])+ else:+ env_refs.append(var)+ for disk in c.get('disks') or []:+ if disk.get('backup') and disk.get('mount_path'):+ unit_backups.append({+ 'container': c['name'],+ 'mount_path': disk['mount_path'],+ 'docker_volume': f'{svc["name"]}-{c["name"]}-'+ f'{disk.get("name") or cls._slug(disk["mount_path"])}',+ 'backup': disk['backup'],+ })+return {'name': svc['name'],'kind': svc['kind'],@@ -73,8 +110,14 @@ class ManifestApplyService:'engine_version': svc.get('engine_version'),'runtime': svc.get('runtime'),'port': svc.get('port'),- 'ports': svc.get('ports', []),+ 'ports': ports,'bootstrap': svc.get('bootstrap'),+ 'bootstraps': bootstraps,+ 'image': svc.get('image'),+ 'registry': svc.get('registry'),+ 'host_requirements': host_requirements,+ 'containers': containers,+ 'unit_backups': unit_backups,'healthcheck_path': svc.get('healthcheck_path'),'build_command': svc.get('build_command'),'start_command': svc.get('start_command'),@@ -83,10 +126,30 @@ class ManifestApplyService:'auto_deploy': svc.get('auto_deploy', False),'env': literal_env,'env_refs': env_refs,- 'disks': svc.get('disks', []),+ 'disks': disks,'server': svc.get('server'),}+ # -- multi-container unit seams (#9) ------------------------------------++ @classmethod+ def unit_compose(cls, app) -> Optional[Dict[str, Any]]:+ """The generated compose project for a manifest-managed UNIT app, or None+ when the app is not a unit. Lets a deploy/UI render the unit verbatim."""+ resolved = cls.resolved_for_app(app)+ if not resolved or not resolved.get('containers'):+ return None+ from app.services.unit_compose_service import UnitComposeService+ return UnitComposeService.render(app.name, resolved['containers'])++ @classmethod+ def unit_container_names(cls, app) -> List[str]:+ """Container names of a unit app (``{app}-{container}``), or []."""+ resolved = cls.resolved_for_app(app)+ if not resolved or not resolved.get('containers'):+ return []+ return [f'{app.name}-{c["name"]}' for c in resolved['containers']]+# -- drift comparison (#18) --------------------------------------------@classmethod@@ -329,15 +392,21 @@ class ManifestApplyService:'files', app.id if app else None, backup):steps.append(cls._files_backup_step(name, app, mount, backup))- # first-boot bootstrap (appliance tier, plan 35) — once per app- bootstrap = resolved.get('bootstrap')- if bootstrap and (app is None or not getattr(app, 'bootstrap_done', False)):+ # unit disk backups (plan 35) — the bytes live in a synthetic per-container+ # docker volume, so the backup routes at that volume name.+ for ub in resolved.get('unit_backups') or []:+ if not cls._backup_policy_current('files', app.id if app else None, ub['backup']):+ steps.append(cls._unit_backup_step(name, app, ub))++ # first-boot bootstrap (appliance tier, plan 35) — once per app; a unit+ # runs each of its containers' bootstraps under the one bootstrap_done flag+ bootstraps = resolved.get('bootstraps') or []+ if bootstraps and (app is None or not getattr(app, 'bootstrap_done', False)):+ suffix = f' ({len(bootstraps)} container(s))' if len(bootstraps) > 1 else ''steps.append({'type': 'bootstrap', 'service': name,- 'description': f'Run first-boot bootstrap on `{name}`',- 'payload': {'app_id': app.id if app else None,- 'command': bootstrap['command'],- 'timeout_seconds': bootstrap.get('timeout_seconds')},+ 'description': f'Run first-boot bootstrap on `{name}`{suffix}',+ 'payload': {'app_id': app.id if app else None, 'bootstraps': bootstraps},})return steps@@ -380,6 +449,19 @@ class ManifestApplyService:'schedule': backup['schedule'], 'retain': backup['retain']},}+ @classmethod+ def _unit_backup_step(cls, name, app, ub):+ backup = ub['backup']+ return {+ 'type': 'upsert_backup_policy', 'service': name,+ 'description': f'Backup policy for unit disk `{ub["mount_path"]}` on '+ f'`{name}` ({backup["schedule"]})',+ 'payload': {'target': 'files', 'app_id': app.id if app else None,+ 'mount_path': ub['mount_path'],+ 'docker_volume': ub['docker_volume'],+ 'schedule': backup['schedule'], 'retain': backup['retain']},+ }+# -- blockers engine (appliance tier, plan 35) --------------------------# An appliance FEATURE is anything the manifest can now express that a@@ -391,7 +473,7 @@ class ManifestApplyService:feats.append('raw port publishes')if resolved.get('host_requirements'):feats.append('host requirements')- if resolved.get('bootstrap'):+ if resolved.get('bootstraps'):feats.append('a first-boot bootstrap')if resolved.get('containers'):feats.append('a multi-container unit')@@ -724,13 +806,22 @@ class ManifestApplyService:raise RuntimeError('app not found')if getattr(app, 'bootstrap_done', False):return {'skipped': 'already bootstrapped'}- result = BootstrapService.run_once(- app, payload['command'], timeout_seconds=payload.get('timeout_seconds'))- if not result.get('success'):- raise RuntimeError(result.get('error') or 'bootstrap failed')+ bootstraps = payload.get('bootstraps')+ if bootstraps is None and payload.get('command'):+ bootstraps = [{'service': app.name, 'command': payload['command'],+ 'timeout_seconds': payload.get('timeout_seconds')}]+ outputs = []+ for b in bootstraps or []:+ result = BootstrapService.run_once(+ app, b['command'], timeout_seconds=b.get('timeout_seconds'),+ service=b.get('service'))+ if not result.get('success'):+ raise RuntimeError(result.get('error')+ or f'bootstrap failed for {b.get("service")}')+ outputs.append(result.get('output'))app.bootstrap_done = Truedb.session.commit()- return {'bootstrapped': True, 'output': result.get('output')}+ return {'bootstrapped': len(bootstraps or []), 'outputs': outputs}@classmethoddef _do_open_port(cls, project, env, payload, user_id):@@ -766,6 +857,8 @@ class ManifestApplyService:if payload.get('volume_mount'):meta['volume_mount'] = payload['volume_mount']meta['app_id'] = app_id+ if payload.get('docker_volume'):+ meta['docker_volume'] = payload['docker_volume']policy = BackupPolicyService.get_or_create_policy(target_type='files', target_id=app_id, target_subtype='pathlist',target_meta=meta)diff --git a/backend/app/services/manifest_spec_service.py b/backend/app/services/manifest_spec_service.pyindex d1be7595..1625b6fe 100644--- a/backend/app/services/manifest_spec_service.py+++ b/backend/app/services/manifest_spec_service.py@@ -108,6 +108,11 @@ MANIFEST_SCHEMA: Dict[str, Any] = {"port": {"type": "integer", "minimum": 1, "maximum": 65535},"ports": {"type": "array", "items": {"$ref": "#/definitions/portDecl"}},"bootstrap": {"$ref": "#/definitions/bootstrap"},+ "containers": {+ "type": "object",+ "minProperties": 1,+ "additionalProperties": {"$ref": "#/definitions/container"},+ },"healthCheckPath": {"type": "string"},"autoDeploy": {"type": "boolean"},"version": {"type": ["string", "number"]},@@ -134,6 +139,52 @@ MANIFEST_SCHEMA: Dict[str, Any] = {"timeoutSeconds": {"type": "integer", "minimum": 1},},},+ "container": {+ "type": "object",+ "additionalProperties": True,+ "properties": {+ "image": {"type": "string"},+ "registry": {"type": "string"},+ "ports": {"type": "array", "items": {"$ref": "#/definitions/portDecl"}},+ "disks": {"type": "array", "items": {"$ref": "#/definitions/disk"}},+ "envVars": {"type": "array", "items": {"$ref": "#/definitions/envVar"}},+ "bootstrap": {"$ref": "#/definitions/bootstrap"},+ "hostRequirements": {"$ref": "#/definitions/hostRequirements"},+ "healthCheck": {"$ref": "#/definitions/healthCheck"},+ "dependsOn": {"type": "array", "items": {"$ref": "#/definitions/dependsOn"}},+ },+ },+ "healthCheck": {+ "type": "object",+ "additionalProperties": True,+ "properties": {+ "cmd": {"type": "string"},+ "httpPath": {"type": "string"},+ "interval": {"type": "string"},+ "timeout": {"type": "string"},+ "retries": {"type": "integer", "minimum": 1},+ },+ },+ "dependsOn": {+ "type": "object",+ "required": ["service"],+ "additionalProperties": True,+ "properties": {+ "service": {"type": "string"},+ "condition": {"enum": ["healthy", "started"]},+ },+ },+ "hostRequirements": {+ "type": "object",+ "additionalProperties": True,+ "properties": {+ "privileged": {"type": "boolean"},+ "capAdd": {"type": "array", "items": {"type": "string"}},+ "sysctls": {"type": "object"},+ "devices": {"type": "array", "items": {"type": "string"}},+ "kernelModules": {"type": "array", "items": {"type": "string"}},+ },+ },"portDecl": {"type": "object","required": ["port"],@@ -393,6 +444,11 @@ class ManifestSpecService:ports = cls._normalize_ports(svc.get('ports'), prefix, errors)bootstrap = cls._normalize_bootstrap(svc.get('bootstrap'))+ image = svc.get('image')+ registry = svc.get('registry')+ host_requirements = cls._normalize_host_requirements(svc.get('hostRequirements')+ or svc.get('host_requirements'))+ containers = cls._normalize_containers(svc, prefix, errors)return {'name': name,@@ -406,6 +462,10 @@ class ManifestSpecService:'port': svc.get('port'),'ports': ports,'bootstrap': bootstrap,+ 'image': image,+ 'registry': registry,+ 'host_requirements': host_requirements,+ 'containers': containers,'healthcheck_path': cls._alias(svc, 'healthCheckPath', 'healthcheck_path'),'auto_deploy': bool(cls._alias(svc, 'autoDeploy', 'auto_deploy', default=False)),'engine_version': cls._stringify(svc.get('version')),@@ -465,6 +525,142 @@ class ManifestSpecService:'timeout_seconds': int(timeout) if timeout else None,}+ @classmethod+ def _normalize_host_requirements(cls, raw: Any) -> Optional[Dict[str, Any]]:+ """hostRequirements (plan 35): privileged/capAdd/sysctls/devices/kernelModules."""+ if not isinstance(raw, dict):+ return None+ hr = {+ 'privileged': bool(raw.get('privileged')),+ 'cap_add': list(cls._alias(raw, 'capAdd', 'cap_add') or []),+ 'sysctls': dict(raw.get('sysctls') or {}),+ 'devices': list(raw.get('devices') or []),+ 'kernel_modules': list(cls._alias(raw, 'kernelModules', 'kernel_modules') or []),+ }+ # collapse to None when nothing is actually requested+ if (not hr['privileged'] and not hr['cap_add'] and not hr['sysctls']+ and not hr['devices'] and not hr['kernel_modules']):+ return None+ return hr++ @classmethod+ def _normalize_healthcheck(cls, raw: Any) -> Optional[Dict[str, Any]]:+ if not isinstance(raw, dict):+ return None+ cmd = raw.get('cmd')+ http_path = cls._alias(raw, 'httpPath', 'http_path')+ if not cmd and not http_path:+ return None+ return {+ 'cmd': cmd,+ 'http_path': http_path,+ 'interval': raw.get('interval'),+ 'timeout': raw.get('timeout'),+ 'retries': raw.get('retries'),+ }++ @classmethod+ def _normalize_depends_on(cls, raw: Any) -> List[Dict[str, Any]]:+ out: List[Dict[str, Any]] = []+ if not isinstance(raw, list):+ return out+ for entry in raw:+ if not isinstance(entry, dict) or not entry.get('service'):+ continue+ out.append({'service': entry['service'],+ 'condition': entry.get('condition') or 'started'})+ return out++ @classmethod+ def _normalize_containers(cls, svc: Dict[str, Any], prefix: str,+ errors: List[str]) -> List[Dict[str, Any]]:+ """A multi-container unit (plan 35, Decision 6). ``containers`` is a+ mapping of name -> container spec, rendered as ONE compose project.++ Mutually exclusive with the buildpack keys; dependsOn must reference a+ sibling container and must be acyclic.+ """+ raw = svc.get('containers')+ if not isinstance(raw, dict) or not raw:+ return []++ # mutual exclusion with the single-image build path+ for key in ('buildCommand', 'build_command', 'startCommand', 'start_command',+ 'runtime'):+ if svc.get(key):+ errors.append(f'{prefix}: `containers` cannot be combined with `{key}` '+ f'— a unit declares its own container images')+ break++ containers: List[Dict[str, Any]] = []+ names = list(raw.keys())+ for cname in names:+ spec = raw[cname] or {}+ cprefix = f'{prefix}/containers/{cname}'+ containers.append({+ 'name': cname,+ 'image': spec.get('image'),+ 'registry': spec.get('registry'),+ 'ports': cls._normalize_ports(spec.get('ports'), cprefix, errors),+ 'disks': [cls._normalize_disk(d) for d in (spec.get('disks') or [])],+ 'env_vars': [cls._normalize_env_var(v, f'{cprefix}/env[{i}]', errors)+ for i, v in enumerate(spec.get('envVars')+ or spec.get('env_vars') or [])],+ 'bootstrap': cls._normalize_bootstrap(spec.get('bootstrap')),+ 'host_requirements': cls._normalize_host_requirements(+ spec.get('hostRequirements') or spec.get('host_requirements')),+ 'health_check': cls._normalize_healthcheck(+ spec.get('healthCheck') or spec.get('health_check')),+ 'depends_on': cls._normalize_depends_on(+ spec.get('dependsOn') or spec.get('depends_on')),+ })++ name_set = set(names)+ graph: Dict[str, List[str]] = {}+ for c in containers:+ deps = []+ for d in c['depends_on']:+ if d['service'] not in name_set:+ errors.append(f'{prefix}/containers/{c["name"]}: dependsOn unknown '+ f'container `{d["service"]}`')+ else:+ deps.append(d['service'])+ graph[c['name']] = deps++ cycle = cls._first_cycle(graph)+ if cycle:+ errors.append(f'{prefix}: dependsOn cycle detected ({" -> ".join(cycle)})')++ return containers++ @staticmethod+ def _first_cycle(graph: Dict[str, List[str]]) -> Optional[List[str]]:+ """DFS back-edge detection; returns a representative cycle path or None."""+ WHITE, GREY, BLACK = 0, 1, 2+ color = {n: WHITE for n in graph}+ stack: List[str] = []++ def visit(node: str) -> Optional[List[str]]:+ color[node] = GREY+ stack.append(node)+ for nxt in graph.get(node, []):+ if color.get(nxt) == GREY:+ return stack[stack.index(nxt):] + [nxt]+ if color.get(nxt) == WHITE:+ found = visit(nxt)+ if found:+ return found+ stack.pop()+ color[node] = BLACK+ return None++ for n in graph:+ if color[n] == WHITE:+ found = visit(n)+ if found:+ return found+ return None+@classmethoddef _normalize_env_var(cls, var: Dict[str, Any], where: str, errors: List[str]) -> Dict[str, Any]:key = var.get('key')diff --git a/backend/app/services/unit_compose_service.py b/backend/app/services/unit_compose_service.pynew file mode 100644index 00000000..fb98f0be--- /dev/null+++ b/backend/app/services/unit_compose_service.py@@ -0,0 +1,141 @@+"""Render a multi-container UNIT as one docker-compose project (plan 35, #8).++A unit is ONE manifest service with a ``containers:`` map. It becomes ONE+Application and ONE compose file: the project's implicit default network is the+unit's private network, `depends_on.condition` gates start order on health, and+each container gets its own named volumes (``{app}-{container}-{disk}``) so two+containers can both mount ``/config`` without colliding on a shared AppVolume.++Pure: no DB, no filesystem. Given the normalized container list it returns a+compose dict (and a YAML string) the deploy path can write verbatim.+"""++import re+from typing import Any, Dict, List, Optional++import yaml++from app.services.app_port_service import AppPortService+++class UnitComposeService:++ @classmethod+ def render(cls, app_name: str, containers: List[Dict[str, Any]],+ networks: Optional[List[str]] = None) -> Dict[str, Any]:+ """Return a compose dict for the unit."""+ services: Dict[str, Any] = {}+ top_volumes: Dict[str, Any] = {}++ for c in containers:+ cname = c['name']+ svc: Dict[str, Any] = {+ 'container_name': f'{app_name}-{cname}',+ 'restart': 'unless-stopped',+ }+ if c.get('image'):+ svc['image'] = c['image']++ ports = AppPortService.compose_ports(c.get('ports') or [])+ if ports:+ svc['ports'] = ports++ env = cls._literal_env(c.get('env_vars') or [])+ if env:+ svc['environment'] = env++ vols = []+ for disk in (c.get('disks') or []):+ mount = disk.get('mount_path')+ if not mount:+ continue+ vname = f'{app_name}-{cname}-{disk.get("name") or cls._slug(mount)}'+ vols.append(f'{vname}:{mount}')+ top_volumes[vname] = {}+ if vols:+ svc['volumes'] = vols++ hc = cls._healthcheck(c.get('health_check'))+ if hc:+ svc['healthcheck'] = hc++ deps = c.get('depends_on') or []+ if deps:+ svc['depends_on'] = {+ d['service']: {'condition': cls._condition(d.get('condition'))}+ for d in deps+ }++ cls._apply_host_requirements(svc, c.get('host_requirements'))++ if networks:+ svc['networks'] = list(networks)++ services[cname] = svc++ compose: Dict[str, Any] = {'version': '3.8', 'services': services}+ if top_volumes:+ compose['volumes'] = top_volumes+ if networks:+ compose['networks'] = {n: {'external': True} for n in networks}+ return compose++ @classmethod+ def render_yaml(cls, app_name: str, containers: List[Dict[str, Any]],+ networks: Optional[List[str]] = None) -> str:+ return yaml.safe_dump(cls.render(app_name, containers, networks=networks),+ sort_keys=False, default_flow_style=False)++ # -- helpers ------------------------------------------------------------++ @staticmethod+ def _literal_env(env_vars: List[Dict[str, Any]]) -> Dict[str, Any]:+ """Only literal values are emitted inline; secret/service/server refs are+ resolved by the env layer (unit env folds into the one app env, v1)."""+ out: Dict[str, Any] = {}+ for var in env_vars:+ if var.get('source') == 'value' and var.get('key'):+ out[var['key']] = var.get('value')+ return out++ @staticmethod+ def _condition(condition: Optional[str]) -> str:+ return 'service_healthy' if condition == 'healthy' else 'service_started'++ @staticmethod+ def _healthcheck(hc: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:+ if not hc:+ return None+ block: Dict[str, Any] = {}+ if hc.get('cmd'):+ block['test'] = ['CMD-SHELL', hc['cmd']]+ elif hc.get('http_path'):+ path = hc['http_path']+ block['test'] = ['CMD-SHELL',+ f'wget -qO- http://localhost{path} || exit 1']+ else:+ return None+ if hc.get('interval'):+ block['interval'] = hc['interval']+ if hc.get('timeout'):+ block['timeout'] = hc['timeout']+ if hc.get('retries'):+ block['retries'] = hc['retries']+ return block++ @staticmethod+ def _apply_host_requirements(svc: Dict[str, Any], hr: Optional[Dict[str, Any]]) -> None:+ if not hr:+ return+ if hr.get('privileged'):+ svc['privileged'] = True+ if hr.get('cap_add'):+ svc['cap_add'] = list(hr['cap_add'])+ if hr.get('sysctls'):+ svc['sysctls'] = dict(hr['sysctls'])+ if hr.get('devices'):+ svc['devices'] = list(hr['devices'])++ @staticmethod+ def _slug(text: str) -> str:+ return re.sub(r'[^a-z0-9]+', '-', (text or '').lower()).strip('-') or 'vol'diff --git a/backend/tests/test_manifest_unit.py b/backend/tests/test_manifest_unit.pynew file mode 100644index 00000000..cf7768d0--- /dev/null+++ b/backend/tests/test_manifest_unit.py@@ -0,0 +1,211 @@+"""Proving tests for Phase 3 of the Appliance tier (plan 35):+the multi-container UNIT — schema, dependsOn validation/cycles, the+UnitComposeService generator, and unit-scoped apply."""++import json++import pytest++import app.models.application_manifest # noqa: F401+from app.services.manifest_spec_service import ManifestSpecService, ManifestError+from app.services.manifest_apply_service import ManifestApplyService+from app.services.unit_compose_service import UnitComposeService+from app.services.app_port_service import AppPortService+from app.services.bootstrap_service import BootstrapService+++UNIT_MANIFEST = {+ 'version': 1,+ 'services': [{+ 'name': 'meet', 'type': 'docker',+ 'containers': {+ 'web': {+ 'image': 'jitsi/web:stable',+ 'ports': [{'port': 8443, 'containerPort': 443, 'expose': 'local'}],+ 'dependsOn': [{'service': 'prosody', 'condition': 'healthy'}],+ 'healthCheck': {'httpPath': '/', 'interval': '30s', 'retries': 5},+ 'disks': [{'name': 'web-config', 'mountPath': '/config', 'size': '1GB',+ 'backup': {'schedule': 'daily', 'retain': 7}}],+ },+ 'prosody': {+ 'image': 'jitsi/prosody:stable',+ 'bootstrap': {'command': '/opt/gen.sh', 'timeoutSeconds': 120},+ 'healthCheck': {'cmd': 'prosodyctl status', 'interval': '15s', 'retries': 5},+ },+ 'jvb': {+ 'image': 'jitsi/jvb:stable',+ 'ports': [{'port': 10000, 'protocol': 'udp', 'expose': 'public'}],+ 'dependsOn': [{'service': 'prosody', 'condition': 'healthy'}],+ },+ },+ }],+}+++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='Meet', slug='meet')+ 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++[email protected](autouse=True)+def _stub(monkeypatch):+ from app.services.docker_service import DockerService+ 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: []))+++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)+++# -- schema / normalizer ----------------------------------------------------++def test_unit_normalizes():+ n = ManifestSpecService.normalize(UNIT_MANIFEST)+ containers = n['services'][0]['containers']+ assert [c['name'] for c in containers] == ['web', 'prosody', 'jvb']+ web = containers[0]+ assert web['image'] == 'jitsi/web:stable'+ assert web['ports'][0]['host_port'] == 8443+ assert web['depends_on'] == [{'service': 'prosody', 'condition': 'healthy'}]+ assert web['health_check']['http_path'] == '/'+ prosody = containers[1]+ assert prosody['bootstrap']['command'] == '/opt/gen.sh'+ assert prosody['health_check']['cmd'] == 'prosodyctl status'+++def test_unit_mutually_exclusive_with_buildpack_keys():+ with pytest.raises(ManifestError) as exc:+ ManifestSpecService.normalize({+ 'version': 1,+ 'services': [{'name': 'x', 'type': 'docker', 'buildCommand': 'make',+ 'containers': {'a': {'image': 'busybox'}}}],+ })+ assert any('containers' in e for e in exc.value.errors)+++def test_depends_on_unknown_container_rejected():+ with pytest.raises(ManifestError) as exc:+ ManifestSpecService.normalize({+ 'version': 1,+ 'services': [{'name': 'x', 'type': 'docker', 'containers': {+ 'a': {'image': 'busybox', 'dependsOn': [{'service': 'ghost'}]}}}],+ })+ assert any('ghost' in e for e in exc.value.errors)+++def test_depends_on_cycle_rejected():+ with pytest.raises(ManifestError) as exc:+ ManifestSpecService.normalize({+ 'version': 1,+ 'services': [{'name': 'x', 'type': 'docker', 'containers': {+ 'a': {'image': 'busybox', 'dependsOn': [{'service': 'b'}]},+ 'b': {'image': 'busybox', 'dependsOn': [{'service': 'a'}]}}}],+ })+ assert any('cycle' in e for e in exc.value.errors)+++# -- generator --------------------------------------------------------------++def test_unit_compose_render():+ n = ManifestSpecService.normalize(UNIT_MANIFEST)+ containers = n['services'][0]['containers']+ compose = UnitComposeService.render('meet', containers)+ services = compose['services']+ assert set(services) == {'web', 'prosody', 'jvb'}+ assert services['web']['container_name'] == 'meet-web'++ # healthchecks: httpPath -> wget probe, cmd -> CMD-SHELL+ assert services['web']['healthcheck']['test'][0] == 'CMD-SHELL'+ assert 'wget' in services['web']['healthcheck']['test'][1]+ assert services['prosody']['healthcheck']['test'] == ['CMD-SHELL', 'prosodyctl status']++ # dependsOn condition mapping+ assert services['web']['depends_on'] == {'prosody': {'condition': 'service_healthy'}}++ # raw L4 publishes+ assert services['jvb']['ports'] == ['0.0.0.0:10000:10000/udp']+ assert services['web']['ports'] == ['127.0.0.1:8443:443']++ # synthetic per-container named volume (no cross-container /config collision)+ assert 'meet-web-web-config:/config' in services['web']['volumes']+ assert 'meet-web-web-config' in compose['volumes']+++# -- apply ------------------------------------------------------------------++def test_unit_applies_as_one_app(project, owner, runner_calls):+ from app.models import Application+ from app.models.backup_policy import BackupPolicy+ from app.services.manifest_persistence_service import ManifestPersistenceService++ n = ManifestSpecService.normalize(UNIT_MANIFEST)+ ManifestPersistenceService.store_manifest(project_id=project.id, normalized=n,+ raw_text=None, status='pending')+ result = ManifestApplyService.apply(project, n, user_id=owner.id)+ assert result['success'] is True, result++ apps = Application.query.filter_by(project_id=project.id).all()+ assert len(apps) == 1 # ONE Application for the whole unit+ meet = apps[0]+ assert meet.name == 'meet'++ # aggregated ports persisted on the one app+ stored = json.loads(meet.ports)+ assert {p['host_port'] for p in stored} == {10000, 8443}++ # the prosody container's bootstrap ran exactly once, under the one flag+ assert meet.bootstrap_done is True+ assert len(runner_calls) == 1+ assert runner_calls[0]['service'] == 'prosody'++ # the backed-up unit 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'++ # idempotent+ plan2 = ManifestApplyService.plan(project, n)+ assert plan2['step_count'] == 0, plan2['summary']++ # seams expose the unit's containers + regenerated compose+ assert ManifestApplyService.unit_container_names(meet) == \+ ['meet-web', 'meet-prosody', 'meet-jvb']+ compose = ManifestApplyService.unit_compose(meet)+ assert set(compose['services']) == {'web', 'prosody', 'jvb'}diff --git a/docs/SERVERKIT_YAML.md b/docs/SERVERKIT_YAML.mdindex 214999ce..e447f676 100644--- a/docs/SERVERKIT_YAML.md+++ b/docs/SERVERKIT_YAML.md@@ -186,6 +186,44 @@ not the empty in-container path. `schedule` is one of`hourly` / `daily` / `weekly` / `monthly`; `retain` is the number of backups tokeep.+## Multi-container units++Some services are not one image — a web frontend, a signaling process, a media+bridge. A `containers:` map makes ONE service a **unit**: one Application, one+compose project, one private network (the compose default), with health-gated+start order. It is mutually exclusive with the buildpack keys (`runtime`,+`buildCommand`, `startCommand`).++```yaml+services:+ - name: meet+ type: docker+ containers:+ web:+ image: jitsi/web:stable+ ports:+ - { port: 8443, containerPort: 443, expose: local }+ dependsOn:+ - { service: prosody, condition: healthy }+ healthCheck: { httpPath: /, interval: 30s, retries: 5 }+ disks:+ - { name: web-config, mountPath: /config, size: 1GB, backup: { schedule: daily, retain: 7 } }+ prosody:+ image: jitsi/prosody:stable+ bootstrap: { command: "/opt/gen-config.sh", timeoutSeconds: 120 }+ healthCheck: { cmd: "prosodyctl status" }+```++Each container takes the same vocabulary as a service:+`image` / `registry` / `ports` / `disks` / `envVars` / `bootstrap` /+`hostRequirements` / `healthCheck` (`cmd` → `CMD-SHELL`, `httpPath` → a `wget`+probe) / `dependsOn` (`{ service, condition: healthy|started }`, validated+against sibling containers and checked for cycles). Container names resolve on+the unit's private network; `container_name` is `{unit}-{container}`. A+container's disks become **per-container** named volumes+(`{unit}-{container}-{disk}`), so two containers can both mount `/config`+without colliding.+## First-boot bootstrapSome appliances generate a config/certificate tree exactly once. A compose initdiff --git a/docs/serverkit-yaml.schema.json b/docs/serverkit-yaml.schema.jsonindex dd9112a3..27cb4496 100644--- a/docs/serverkit-yaml.schema.json+++ b/docs/serverkit-yaml.schema.json@@ -82,6 +82,12 @@"description": "First-boot bootstrap (appliance tier). Runs once via `docker compose run --rm` after volumes exist and before the first up — for appliances that generate a config tree once.","$ref": "#/definitions/bootstrap"},+ "containers": {+ "description": "A multi-container UNIT (appliance tier): one service rendered as one compose project with a private network and health-gated dependsOn. Mutually exclusive with the buildpack keys. Keyed by container name.",+ "type": "object",+ "minProperties": 1,+ "additionalProperties": { "$ref": "#/definitions/container" }+ },"healthCheckPath": {"description": "HTTP path used for health checks and the zero-downtime restart gate.","type": "string"@@ -147,6 +153,52 @@}}},+ "container": {+ "type": "object",+ "additionalProperties": true,+ "properties": {+ "image": { "description": "Container image reference.", "type": "string" },+ "registry": { "description": "Named private registry to authenticate against before pulling.", "type": "string" },+ "ports": { "type": "array", "items": { "$ref": "#/definitions/portDecl" } },+ "disks": { "type": "array", "items": { "$ref": "#/definitions/disk" } },+ "envVars": { "type": "array", "items": { "$ref": "#/definitions/envVar" } },+ "bootstrap": { "$ref": "#/definitions/bootstrap" },+ "hostRequirements": { "$ref": "#/definitions/hostRequirements" },+ "healthCheck": { "$ref": "#/definitions/healthCheck" },+ "dependsOn": { "type": "array", "items": { "$ref": "#/definitions/dependsOn" } }+ }+ },+ "healthCheck": {+ "type": "object",+ "additionalProperties": true,+ "properties": {+ "cmd": { "description": "Shell command probe (rendered as CMD-SHELL).", "type": "string" },+ "httpPath": { "description": "HTTP path probed with wget on localhost.", "type": "string" },+ "interval": { "description": "e.g. 30s.", "type": "string" },+ "timeout": { "description": "e.g. 5s.", "type": "string" },+ "retries": { "type": "integer", "minimum": 1 }+ }+ },+ "dependsOn": {+ "type": "object",+ "required": ["service"],+ "additionalProperties": true,+ "properties": {+ "service": { "description": "Sibling container name in the same unit.", "type": "string" },+ "condition": { "description": "healthy waits for the dependency's healthcheck; started only waits for it to start.", "enum": ["healthy", "started"] }+ }+ },+ "hostRequirements": {+ "type": "object",+ "additionalProperties": true,+ "properties": {+ "privileged": { "description": "Run privileged (big hammer — always shown in the plan, never silent).", "type": "boolean" },+ "capAdd": { "description": "Linux capabilities to add.", "type": "array", "items": { "type": "string" } },+ "sysctls": { "description": "sysctl key/value pairs.", "type": "object" },+ "devices": { "description": "Host devices to expose.", "type": "array", "items": { "type": "string" } },+ "kernelModules": { "description": "Kernel modules the workload needs (advisory /proc/modules check only).", "type": "array", "items": { "type": "string" } }+ }+ },"portDecl": {"type": "object","required": ["port"],