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): multi-container units (plan 35 ph3)

Juan Denisfdc3d4574976
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 on
first 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 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/backup_policy_service.py b/backend/app/services/backup_policy_service.py
index 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:
+ pass
if 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.py
index 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 = True
db.session.commit()
- return {'bootstrapped': True, 'output': result.get('output')}
+ return {'bootstrapped': len(bootstraps or []), 'outputs': outputs}
@classmethod
def _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.py
index 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
+
@classmethod
def _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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.md
index 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 to
keep.
+## 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 bootstrap
Some appliances generate a config/certificate tree exactly once. A compose init
diff --git a/docs/serverkit-yaml.schema.json b/docs/serverkit-yaml.schema.json
index 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"],