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): appliance-tier typed L4 ports + plan-time blockers rail (plan 35 ph1)

Juan Denis06c3fcf28c88
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d04bcd70..5f2f00c7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,16 @@ awaiting a stable release:
### Added
+- **Appliance tier for `serverkit.yaml` — typed L4 ports + a plan-time blockers
+ rail** — a service can now declare raw `ports[]` (`{port, containerPort,
+ protocol: tcp|udp, expose: public|local}`) as an escape hatch for
+ infrastructure that speaks more than HTTP (media/UDP, VoIP, brokers). `public`
+ ports render a `0.0.0.0` publish and open a firewall rule (recorded so an app
+ delete closes it); `local` ports bind `127.0.0.1`. The scalar `port` keeps its
+ HTTP/nginx behavior untouched. Apply grows **blockers** distinct from advisory
+ issues — it refuses (nothing executed, no force flag) on a port conflict, a
+ remote/observed target, or an undetectable firewall, with a message that says
+ what the target can't provide and how to fix it.
- **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/api/apps.py b/backend/app/api/apps.py
index f928edc1..fef64d20 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -1322,6 +1322,16 @@ def delete_app(app_id):
'nginx': None
}
+ # Appliance tier (plan 35): close any public firewall ports this app opened
+ # so a delete leaves no orphaned holes in the firewall.
+ try:
+ from app.services.app_port_service import AppPortService
+ declared_ports = AppPortService.get_ports(app)
+ if declared_ports:
+ cleanup_results['firewall'] = AppPortService.close_firewall(declared_ports)
+ except Exception as e:
+ cleanup_results['firewall'] = {'error': str(e)}
+
# For Docker apps, stop and remove containers/volumes
if app.app_type == 'docker' and app.root_path:
try:
diff --git a/backend/app/api/manifests.py b/backend/app/api/manifests.py
index 79af5d7c..860dbc0f 100644
--- a/backend/app/api/manifests.py
+++ b/backend/app/api/manifests.py
@@ -161,12 +161,16 @@ def apply_manifest():
result = ManifestApplyService.apply(project, normalized, user_id=user.id,
manifest_row=row)
+ # Appliance-tier blockers (plan 35): apply refused, nothing executed.
+ if result.get('refused'):
+ return jsonify(result), 400
+
try:
from app.services.audit_service import AuditService
AuditService.log('manifest.apply', user_id=user.id, target_type='project',
target_id=project.id,
- details={'success': result['success'], 'applied': result['applied'],
- 'job_id': result['job_id']})
+ details={'success': result['success'], 'applied': result.get('applied'),
+ 'job_id': result.get('job_id')})
except Exception:
pass
diff --git a/backend/app/services/app_port_service.py b/backend/app/services/app_port_service.py
new file mode 100644
index 00000000..17654721
--- /dev/null
+++ b/backend/app/services/app_port_service.py
@@ -0,0 +1,103 @@
+"""Appliance-tier typed L4 port publishes (plan 35).
+
+Ports declared in a serverkit.yaml ``ports:`` list are persisted as a JSON list
+on ``Application.ports`` and rendered as raw docker publishes at deploy time.
+Public ports also open a firewall rule on the panel host; deleting the app (or
+clearing its ports) closes them. A NULL ``Application.ports`` means "no raw
+ports declared" — legacy apps keep the scalar ``port`` column + the nginx vhost.
+
+Backed by the JSON column added in migration 070 (not a separate table).
+"""
+
+import json
+from typing import Any, Dict, List
+
+from app.models.application import Application # noqa: F401 (kept for callers/tests)
+
+
+class AppPortService:
+ """Read/write + render the typed port publishes for an application."""
+
+ # -- persistence --------------------------------------------------------
+
+ @staticmethod
+ def get_ports(app) -> List[Dict[str, Any]]:
+ """The persisted, normalized port list for ``app`` ([] when none)."""
+ raw = getattr(app, 'ports', None)
+ if not raw:
+ return []
+ try:
+ data = json.loads(raw) if isinstance(raw, str) else raw
+ except Exception:
+ return []
+ return data if isinstance(data, list) else []
+
+ @classmethod
+ def set_ports(cls, app, ports: List[Dict[str, Any]]) -> None:
+ """Persist the port list onto the app row (NULL when empty)."""
+ cleaned = [cls._clean(p) for p in (ports or []) if p]
+ app.ports = json.dumps(cleaned) if cleaned else None
+
+ @staticmethod
+ def _clean(p: Dict[str, Any]) -> Dict[str, Any]:
+ host = p.get('host_port') if p.get('host_port') is not None else p.get('port')
+ container = (p.get('container_port') if p.get('container_port') is not None
+ else p.get('containerPort'))
+ if container is None:
+ container = host
+ return {
+ 'host_port': host,
+ 'container_port': container,
+ 'protocol': (p.get('protocol') or 'tcp').lower(),
+ 'expose': (p.get('expose') or 'public').lower(),
+ }
+
+ @classmethod
+ def public_ports(cls, ports: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+ return [c for c in (cls._clean(p) for p in (ports or [])) if c['expose'] == 'public']
+
+ # -- compose emission ---------------------------------------------------
+
+ @classmethod
+ def compose_ports(cls, ports: List[Dict[str, Any]]) -> List[str]:
+ """Docker-compose short-syntax publish strings for the raw L4 ports.
+
+ ``public`` binds 0.0.0.0 (the shipped-builtin precedent); ``local``
+ binds 127.0.0.1 (the WP-multidev precedent); ``/udp`` suffix for udp.
+ """
+ out: List[str] = []
+ for p in ports or []:
+ c = cls._clean(p)
+ if c['host_port'] is None:
+ continue
+ bind = '0.0.0.0' if c['expose'] == 'public' else '127.0.0.1'
+ spec = f"{bind}:{c['host_port']}:{c['container_port']}"
+ if c['protocol'] == 'udp':
+ spec += '/udp'
+ out.append(spec)
+ return out
+
+ # -- firewall -----------------------------------------------------------
+
+ @classmethod
+ def open_firewall(cls, ports: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+ """Open a firewall rule for each PUBLIC port on the panel host."""
+ return cls._firewall('add_rule', ports)
+
+ @classmethod
+ def close_firewall(cls, ports: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+ """Close the firewall rule for each PUBLIC port on the panel host."""
+ return cls._firewall('remove_rule', ports)
+
+ @classmethod
+ def _firewall(cls, verb: str, ports: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+ from app.services.firewall_service import FirewallService
+ results: List[Dict[str, Any]] = []
+ for p in cls.public_ports(ports):
+ try:
+ res = getattr(FirewallService, verb)(
+ 'port', port=p['host_port'], protocol=p['protocol'])
+ except Exception as exc: # firewall is best-effort, never fatal here
+ res = {'success': False, 'error': str(exc)}
+ results.append({'port': p['host_port'], 'protocol': p['protocol'], 'result': res})
+ return results
diff --git a/backend/app/services/buildpack_service.py b/backend/app/services/buildpack_service.py
index ccaa9b06..c4650c3f 100644
--- a/backend/app/services/buildpack_service.py
+++ b/backend/app/services/buildpack_service.py
@@ -660,12 +660,20 @@ class BuildpackService:
return json.dumps(['sh', '-c', command])
@classmethod
- def generate_compose(cls, plan: Dict, app_name: str) -> str:
- """Return a docker-compose snippet wrapping the generated image."""
+ def generate_compose(cls, plan: Dict, app_name: str, extra_ports: Optional[list] = None,
+ volumes: Optional[list] = None,
+ named_volumes: Optional[list] = None) -> str:
+ """Return a docker-compose snippet wrapping the generated image.
+
+ Appliance tier (plan 35): ``extra_ports`` are raw compose publish
+ strings (typed L4 ports) appended to the app's own HTTP port;
+ ``volumes`` are service mount specs and ``named_volumes`` declare the
+ top-level named volumes they reference.
+ """
plan = plan or {}
safe_name = re.sub(r'[^a-z0-9_-]', '-', (app_name or 'app').lower()).strip('-') or 'app'
port = cls._port(plan)
- return '\n'.join([
+ lines = [
'services:',
f' {safe_name}:',
' build:',
@@ -675,7 +683,18 @@ class BuildpackService:
' restart: unless-stopped',
' ports:',
f' - "{port}:{port}"',
- ]) + '\n'
+ ]
+ for spec in (extra_ports or []):
+ lines.append(f' - "{spec}"')
+ if volumes:
+ lines.append(' volumes:')
+ for spec in volumes:
+ lines.append(f' - "{spec}"')
+ if named_volumes:
+ lines.append('volumes:')
+ for name in named_volumes:
+ lines.append(f' {name}: {{}}')
+ return '\n'.join(lines) + '\n'
# ------------------------------------------------------------------ #
# Caching
diff --git a/backend/app/services/manifest_apply_service.py b/backend/app/services/manifest_apply_service.py
index 5e69e7c9..0773b494 100644
--- a/backend/app/services/manifest_apply_service.py
+++ b/backend/app/services/manifest_apply_service.py
@@ -41,11 +41,13 @@ _STEP_ORDER = {
'warn': 1,
'create_app': 2,
'update_app': 3,
- 'set_env': 4,
- 'set_env_ref': 4,
- 'ensure_volume': 5,
- 'upsert_backup_policy': 6,
- 'attach_domain': 7,
+ 'open_port': 4,
+ 'set_env': 5,
+ 'set_env_ref': 5,
+ 'ensure_volume': 6,
+ 'bootstrap': 7,
+ 'upsert_backup_policy': 8,
+ 'attach_domain': 9,
}
@@ -71,6 +73,7 @@ class ManifestApplyService:
'engine_version': svc.get('engine_version'),
'runtime': svc.get('runtime'),
'port': svc.get('port'),
+ 'ports': svc.get('ports', []),
'healthcheck_path': svc.get('healthcheck_path'),
'build_command': svc.get('build_command'),
'start_command': svc.get('start_command'),
@@ -161,9 +164,11 @@ class ManifestApplyService:
issues: List[Dict[str, Any]] = []
services = normalized.get('services', [])
+ resolved_all: List[Dict[str, Any]] = []
for svc in services:
resolved = cls.resolve_service(svc)
resolved['server'] = resolved.get('server') or default_server
+ resolved_all.append(resolved)
if resolved['kind'] == 'database':
steps.extend(cls._plan_db(resolved))
else:
@@ -171,6 +176,11 @@ class ManifestApplyService:
steps.extend(cls._plan_domains(project, normalized.get('domains', [])))
+ # Appliance-tier blockers (plan 35): plan-time refusals distinct from
+ # advisory `issues`. Apply refuses (nothing executed) while any exist.
+ blockers, appliance_issues = cls._appliance_blockers(project, resolved_all)
+ issues.extend(appliance_issues)
+
steps.sort(key=lambda s: (_STEP_ORDER.get(s['type'], 99), s.get('service') or ''))
return {
'project_id': project.id,
@@ -178,6 +188,7 @@ class ManifestApplyService:
'steps': steps,
'step_count': len(steps),
'issues': issues,
+ 'blockers': blockers,
'summary': cls._summarize_plan(steps),
}
@@ -247,6 +258,18 @@ class ManifestApplyService:
'payload': {'app_id': app.id, 'changes': changes},
})
+ # typed L4 port publishes (appliance tier, plan 35)
+ ports = resolved.get('ports') or []
+ if ports:
+ from app.services.app_port_service import AppPortService
+ current = AppPortService.get_ports(app) if app else []
+ if app is None or cls._ports_differ(current, ports):
+ steps.append({
+ 'type': 'open_port', 'service': name,
+ 'description': f'Publish {len(ports)} port(s) on `{name}`',
+ 'payload': {'app_id': app.id if app else None, 'ports': ports},
+ })
+
# env (literal values only; references bind in Phase 3)
desired_env = resolved['env']
if desired_env:
@@ -345,6 +368,140 @@ class ManifestApplyService:
'retain': backup['retain']},
}
+ # -- blockers engine (appliance tier, plan 35) --------------------------
+
+ # An appliance FEATURE is anything the manifest can now express that a
+ # target may be unable to provide. Later phases extend `_service_features`.
+ @classmethod
+ def _service_features(cls, resolved: Dict[str, Any]) -> List[str]:
+ feats: List[str] = []
+ if resolved.get('ports'):
+ feats.append('raw port publishes')
+ if resolved.get('host_requirements'):
+ feats.append('host requirements')
+ if resolved.get('bootstrap'):
+ feats.append('a first-boot bootstrap')
+ if resolved.get('containers'):
+ feats.append('a multi-container unit')
+ return feats
+
+ @classmethod
+ def _appliance_blockers(cls, project, resolved_all: List[Dict[str, Any]]):
+ """Return (blockers, issues). Blockers refuse apply; issues are advisory.
+
+ Message contract: "service X needs Y; target Z can't provide it — <fix>".
+ """
+ blockers: List[Dict[str, Any]] = []
+ issues: List[Dict[str, Any]] = []
+ fw_state = None # resolved lazily, once
+ for resolved in resolved_all:
+ if resolved.get('kind') != 'app':
+ continue
+ name = resolved['name']
+ feats = cls._service_features(resolved)
+ if not feats:
+ continue
+ need = ' and '.join(feats)
+ server_ref = resolved.get('server')
+
+ # Remote target: appliance apply runs on the panel host only (plan 17's
+ # remote-dispatch deferral). Say so instead of half-deploying.
+ if server_ref:
+ srv = cls._resolve_server_obj(server_ref)
+ if srv is not None and getattr(srv, 'management_mode', None) == 'observed':
+ blockers.append({
+ 'kind': 'observed_server', 'service': name, 'server': server_ref,
+ 'message': f'service {name} needs {need}; target {server_ref} is an '
+ f'observed (read-only) server — ServerKit will not mutate it. '
+ f'Switch it to managed, or apply on the panel host.'})
+ continue
+ blockers.append({
+ 'kind': 'remote_target', 'service': name, 'server': server_ref,
+ 'message': f'service {name} needs {need}; target {server_ref} is a remote '
+ f'server — remote appliance apply is not supported yet. Apply on '
+ f'the panel host, or provision {server_ref} manually.'})
+ continue
+
+ # Local panel host: port conflicts + firewall detection.
+ public = [p for p in (resolved.get('ports') or [])
+ if (p.get('expose') or 'public') == 'public']
+ for p in public:
+ hp = p.get('host_port')
+ if hp is not None and cls._port_bound(int(hp)):
+ blockers.append({
+ 'kind': 'port_conflict', 'service': name, 'port': hp,
+ 'message': f'service {name} needs public port {hp}/{p.get("protocol","tcp")}; '
+ f'the panel host already has it bound — free the port or choose '
+ f'another in the manifest.'})
+ if public:
+ if fw_state is None:
+ fw_state = cls._firewall_state()
+ if fw_state == 'undetected':
+ blockers.append({
+ 'kind': 'firewall_undetected', 'service': name,
+ 'message': f'service {name} publishes public ports but the panel host '
+ f'firewall state could not be determined — verify ufw/firewalld '
+ f'is reachable, then re-apply.'})
+ elif fw_state == 'none':
+ issues.append({
+ 'service': name, 'kind': 'firewall_none',
+ 'message': f'no manageable firewall detected — public ports for {name} '
+ f'will be published but not firewall-managed.'})
+ return blockers, issues
+
+ # -- blocker seams (patched in tests) -----------------------------------
+
+ @staticmethod
+ def _port_bound(port: int) -> bool:
+ """True when ``port`` is already bound on the panel host (0.0.0.0)."""
+ import socket
+ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ try:
+ sock.bind(('0.0.0.0', int(port)))
+ return False
+ except OSError:
+ return True
+ except Exception:
+ return False
+ finally:
+ sock.close()
+
+ @staticmethod
+ def _firewall_state() -> str:
+ """'active' (a manageable firewall exists) | 'none' | 'undetected'."""
+ try:
+ from app.services.firewall_service import FirewallService
+ status = FirewallService.get_status()
+ except Exception:
+ return 'undetected'
+ if not isinstance(status, dict):
+ return 'undetected'
+ if status.get('active_firewall'):
+ return 'active'
+ fwd = status.get('firewalld') or {}
+ ufw = status.get('ufw') or {}
+ if fwd.get('installed') or ufw.get('installed'):
+ return 'active'
+ return 'none'
+
+ @staticmethod
+ def _resolve_server_obj(server_ref: Optional[str]):
+ if not server_ref:
+ return None
+ try:
+ from app.models.server import Server
+ except Exception:
+ return None
+ return (Server.query.filter_by(id=server_ref).first()
+ or Server.query.filter_by(name=server_ref).first())
+
+ @staticmethod
+ def _ports_differ(current: List[Dict[str, Any]], desired: List[Dict[str, Any]]) -> bool:
+ def key(p):
+ return (p.get('host_port'), p.get('container_port'),
+ (p.get('protocol') or 'tcp'), (p.get('expose') or 'public'))
+ return sorted(map(key, current)) != sorted(map(key, desired))
+
# -- apply (#9) ---------------------------------------------------------
@classmethod
@@ -355,6 +512,20 @@ class ManifestApplyService:
"""Execute the plan inside a DeploymentJob with before/after snapshots."""
env = environment or cls._default_environment(project)
plan = cls.plan(project, normalized, env)
+
+ # Appliance-tier blockers (plan 35): refuse before executing anything.
+ # No force flag — the operator must clear the cause and re-apply.
+ if plan.get('blockers'):
+ if manifest_row is not None:
+ manifest_row.status = STATUS_ERROR
+ manifest_row.last_error = plan['blockers'][0]['message']
+ db.session.commit()
+ return {
+ 'success': False, 'refused': True,
+ 'blockers': plan['blockers'], 'issues': plan.get('issues', []),
+ 'applied': 0, 'results': [], 'plan': plan,
+ }
+
job = cls._create_job(project, user_id, plan)
cls._snapshot_existing(project, normalized, tag='before')
@@ -527,6 +698,18 @@ class ManifestApplyService:
vol = VolumeService.create(app, payload['name'], payload['mount_path'])
return {'volume_id': getattr(vol, 'id', None)}
+ @classmethod
+ def _do_open_port(cls, project, env, payload, user_id):
+ from app.services.app_port_service import AppPortService
+ app = Application.query.get(payload.get('app_id') or cls._resolve_app_id(project, payload))
+ if not app:
+ raise RuntimeError('app not found')
+ ports = payload['ports']
+ AppPortService.set_ports(app, ports)
+ db.session.commit()
+ firewall = AppPortService.open_firewall(ports)
+ return {'ports': len(ports), 'firewall': firewall}
+
@classmethod
def _do_upsert_backup_policy(cls, project, env, payload, user_id):
from app.services.backup_policy_service import BackupPolicyService
diff --git a/backend/app/services/manifest_spec_service.py b/backend/app/services/manifest_spec_service.py
index b2c9ec79..39f5587c 100644
--- a/backend/app/services/manifest_spec_service.py
+++ b/backend/app/services/manifest_spec_service.py
@@ -59,6 +59,10 @@ FROM_SERVICE_PROPERTIES = (
BACKUP_SCHEDULES = ('hourly', 'daily', 'weekly', 'monthly')
+# Appliance tier (plan 35): typed L4 port publishes.
+PORT_PROTOCOLS = ('tcp', 'udp')
+PORT_EXPOSURES = ('public', 'local')
+
_KEY_RE = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
_NAME_RE = re.compile(r'^[a-z0-9]([a-z0-9-]*[a-z0-9])?$')
@@ -102,6 +106,7 @@ MANIFEST_SCHEMA: Dict[str, Any] = {
"buildCommand": {"type": "string"},
"startCommand": {"type": "string"},
"port": {"type": "integer", "minimum": 1, "maximum": 65535},
+ "ports": {"type": "array", "items": {"$ref": "#/definitions/portDecl"}},
"healthCheckPath": {"type": "string"},
"autoDeploy": {"type": "boolean"},
"version": {"type": ["string", "number"]},
@@ -119,6 +124,17 @@ MANIFEST_SCHEMA: Dict[str, Any] = {
},
},
},
+ "portDecl": {
+ "type": "object",
+ "required": ["port"],
+ "additionalProperties": True,
+ "properties": {
+ "port": {"type": "integer", "minimum": 1, "maximum": 65535},
+ "containerPort": {"type": "integer", "minimum": 1, "maximum": 65535},
+ "protocol": {"enum": list(PORT_PROTOCOLS)},
+ "expose": {"enum": list(PORT_EXPOSURES)},
+ },
+ },
"envVar": {
"type": "object",
"required": ["key"],
@@ -365,6 +381,8 @@ class ManifestSpecService:
if isinstance(c, dict)
]
+ ports = cls._normalize_ports(svc.get('ports'), prefix, errors)
+
return {
'name': name,
'type': stype,
@@ -375,6 +393,7 @@ class ManifestSpecService:
'build_command': cls._alias(svc, 'buildCommand', 'build_command'),
'start_command': cls._alias(svc, 'startCommand', 'start_command'),
'port': svc.get('port'),
+ 'ports': ports,
'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')),
@@ -386,6 +405,40 @@ class ManifestSpecService:
'crons': crons,
}
+ @classmethod
+ def _normalize_ports(cls, raw: Any, prefix: str, errors: List[str]) -> List[Dict[str, Any]]:
+ """Typed L4 publishes (plan 35). Legacy scalar ``port`` is unaffected —
+ it keeps its HTTP/nginx semantics. ``ports`` are raw tcp/udp publishes
+ (the appliance escape hatch): NULL/[] means "no raw ports declared".
+ """
+ if not isinstance(raw, list):
+ return []
+ ports: List[Dict[str, Any]] = []
+ seen: set = set()
+ for i, entry in enumerate(raw):
+ if not isinstance(entry, dict):
+ errors.append(f'{prefix}/ports[{i}]: must be a mapping')
+ continue
+ host_port = entry.get('port')
+ if not isinstance(host_port, int):
+ errors.append(f'{prefix}/ports[{i}]: `port` is required')
+ continue
+ container_port = cls._alias(entry, 'containerPort', 'container_port') or host_port
+ protocol = (entry.get('protocol') or 'tcp').lower()
+ expose = (entry.get('expose') or 'public').lower()
+ key = (host_port, protocol)
+ if key in seen:
+ errors.append(f'{prefix}/ports[{i}]: duplicate publish {host_port}/{protocol}')
+ continue
+ seen.add(key)
+ ports.append({
+ 'host_port': host_port,
+ 'container_port': container_port,
+ 'protocol': protocol,
+ 'expose': expose,
+ })
+ return ports
+
@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/tests/test_manifest_appliance_ports.py b/backend/tests/test_manifest_appliance_ports.py
new file mode 100644
index 00000000..bccc5856
--- /dev/null
+++ b/backend/tests/test_manifest_appliance_ports.py
@@ -0,0 +1,186 @@
+"""Proving tests for Phase 1 of the Appliance tier (plan 35):
+typed L4 ports + the plan-time blockers rail."""
+
+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.app_port_service import AppPortService
+from app.services.buildpack_service import BuildpackService
+
+
+PORTS_MANIFEST = {
+ 'version': 1,
+ 'services': [{
+ 'name': 'media', 'type': 'docker',
+ 'ports': [
+ {'port': 10000, 'protocol': 'udp', 'expose': 'public'},
+ {'port': 8443, 'containerPort': 443, 'expose': 'local'},
+ ],
+ }],
+}
+
+
+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')
+ 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_appliance(monkeypatch):
+ """Keep the panel host clear + firewall out of the loop by default; each
+ blocker test overrides the specific seam it exercises."""
+ 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(AppPortService, 'close_firewall',
+ classmethod(lambda cls, ports: []))
+
+
+# -- normalizer -------------------------------------------------------------
+
+def test_ports_normalize_with_defaults():
+ n = ManifestSpecService.normalize(PORTS_MANIFEST)
+ ports = n['services'][0]['ports']
+ assert len(ports) == 2
+ udp = ports[0]
+ assert udp == {'host_port': 10000, 'container_port': 10000,
+ 'protocol': 'udp', 'expose': 'public'}
+ local = ports[1]
+ assert local == {'host_port': 8443, 'container_port': 443,
+ 'protocol': 'tcp', 'expose': 'local'}
+ # legacy scalar port is untouched / independent
+ assert n['services'][0]['port'] is None
+
+
+def test_duplicate_port_rejected():
+ with pytest.raises(ManifestError) as exc:
+ ManifestSpecService.normalize({
+ 'version': 1,
+ 'services': [{'name': 'x', 'type': 'docker',
+ 'ports': [{'port': 53, 'protocol': 'udp'},
+ {'port': 53, 'protocol': 'udp'}]}],
+ })
+ assert any('duplicate' in e for e in exc.value.errors)
+
+
+def test_bad_protocol_rejected():
+ with pytest.raises(ManifestError):
+ ManifestSpecService.normalize({
+ 'version': 1,
+ 'services': [{'name': 'x', 'type': 'docker',
+ 'ports': [{'port': 53, 'protocol': 'sctp'}]}],
+ })
+
+
+# -- compose emission -------------------------------------------------------
+
+def test_compose_ports_emission():
+ n = ManifestSpecService.normalize(PORTS_MANIFEST)
+ specs = AppPortService.compose_ports(n['services'][0]['ports'])
+ assert specs == ['0.0.0.0:10000:10000/udp', '127.0.0.1:8443:443']
+
+
+def test_buildpack_extra_ports_emitted():
+ compose = BuildpackService.generate_compose(
+ {'port': 3000}, 'app', extra_ports=['0.0.0.0:10000:10000/udp'])
+ assert '"3000:3000"' in compose # the app's own HTTP port
+ assert '"0.0.0.0:10000:10000/udp"' in compose # the raw L4 publish
+
+
+# -- plan / apply -----------------------------------------------------------
+
+def test_plan_emits_open_port_without_blockers(project):
+ n = ManifestSpecService.normalize(PORTS_MANIFEST)
+ plan = ManifestApplyService.plan(project, n)
+ assert 'open_port' in [s['type'] for s in plan['steps']]
+ assert plan['blockers'] == []
+
+
+def test_apply_persists_ports_and_is_idempotent(project, owner):
+ from app.models import Application
+ n = ManifestSpecService.normalize(PORTS_MANIFEST)
+ result = ManifestApplyService.apply(project, n, user_id=owner.id)
+ assert result['success'] is True, result
+
+ media = Application.query.filter_by(project_id=project.id, name='media').first()
+ assert media is not None
+ stored = json.loads(media.ports)
+ assert len(stored) == 2
+ assert {p['host_port'] for p in stored} == {10000, 8443}
+
+ # second plan is empty (idempotent)
+ plan2 = ManifestApplyService.plan(project, n)
+ assert plan2['step_count'] == 0, plan2['summary']
+
+
+# -- blockers ---------------------------------------------------------------
+
+def test_port_conflict_blocks_apply(project, owner, monkeypatch):
+ monkeypatch.setattr(ManifestApplyService, '_port_bound',
+ lambda port: port == 10000)
+ n = ManifestSpecService.normalize(PORTS_MANIFEST)
+ plan = ManifestApplyService.plan(project, n)
+ kinds = {b['kind'] for b in plan['blockers']}
+ assert 'port_conflict' in kinds
+ # apply refuses, nothing executed
+ result = ManifestApplyService.apply(project, n, user_id=owner.id)
+ assert result['success'] is False
+ assert result['refused'] is True
+ assert result['applied'] == 0
+ from app.models import Application
+ assert Application.query.filter_by(project_id=project.id, name='media').first() is None
+
+
+def test_remote_target_blocks(project):
+ manifest = json.loads(json.dumps(PORTS_MANIFEST))
+ manifest['services'][0]['server'] = 'frankfurt-box'
+ n = ManifestSpecService.normalize(manifest)
+ plan = ManifestApplyService.plan(project, n)
+ kinds = {b['kind'] for b in plan['blockers']}
+ assert 'remote_target' in kinds
+ msg = next(b['message'] for b in plan['blockers'] if b['kind'] == 'remote_target')
+ assert 'frankfurt-box' in msg
+
+
+def test_firewall_undetected_blocks(project, monkeypatch):
+ monkeypatch.setattr(ManifestApplyService, '_firewall_state', lambda: 'undetected')
+ n = ManifestSpecService.normalize(PORTS_MANIFEST)
+ plan = ManifestApplyService.plan(project, n)
+ assert 'firewall_undetected' in {b['kind'] for b in plan['blockers']}
+
+
+def test_firewall_none_is_advisory_not_blocking(project, monkeypatch):
+ monkeypatch.setattr(ManifestApplyService, '_firewall_state', lambda: 'none')
+ n = ManifestSpecService.normalize(PORTS_MANIFEST)
+ plan = ManifestApplyService.plan(project, n)
+ assert plan['blockers'] == []
+ assert 'firewall_none' in {i.get('kind') for i in plan['issues']}
diff --git a/docs/SERVERKIT_YAML.md b/docs/SERVERKIT_YAML.md
index d01fcb5e..a09e5166 100644
--- a/docs/SERVERKIT_YAML.md
+++ b/docs/SERVERKIT_YAML.md
@@ -102,7 +102,8 @@ environment.
| `type` | all | `web` / `worker` / `static` / `docker` → Application; `postgres` / `mysql` / `mariadb` / `redis` → ManagedDatabase. |
| `runtime` | app | Build runtime hint (`python`, `node`, `static`, `docker`). |
| `buildCommand` / `startCommand` | app | Buildpack command overrides. |
-| `port` | app | Container listen port (1–65535). |
+| `port` | app | Container listen port (1–65535). Keeps its HTTP/nginx semantics. |
+| `ports[]` | app | Typed L4 publishes (appliance tier) — see [Ports](#ports-appliance-tier). |
| `healthCheckPath` | app | Used for health checks and the zero-downtime restart gate. |
| `autoDeploy` | app | `true` auto-applies on a changing push; otherwise the manifest flips to `pending`. |
| `cpu` / `memory` | app | Resource limits (best-effort). |
@@ -113,6 +114,49 @@ environment.
| `disk` | db | Single primary disk for a db service. |
| `cron` | app | One object or a list — scheduled jobs. |
+## Ports (appliance tier)
+
+The scalar `port` is the HTTP door: it stays behind nginx, on a loopback bind,
+with a vhost — unchanged. Real infrastructure speaks more than HTTP, so
+`ports[]` is the **raw L4 escape hatch**: media/UDP, VoIP, brokers, DNS.
+
+```yaml
+services:
+ - name: media
+ type: docker
+ ports:
+ - { port: 10000, protocol: udp, expose: public } # 0.0.0.0:10000:10000/udp + firewall
+ - { port: 8443, containerPort: 443, expose: local } # 127.0.0.1:8443:443 (behind nginx)
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `port` | — | Host port to publish (required). |
+| `containerPort` | = `port` | Container port to publish to. |
+| `protocol` | `tcp` | `tcp` or `udp`. |
+| `expose` | `public` | `public` binds `0.0.0.0` **and opens the firewall**; `local` binds `127.0.0.1` only. |
+
+A `public` port renders a direct `0.0.0.0` docker publish and opens a firewall
+rule on the panel host, recorded so deleting the app closes it again. `ports[]`
+persist as JSON on the app row; a plain HTTP app declares none and keeps using
+`port`.
+
+### The honesty rule — plan-time blockers
+
+The plan tells you what the target **can't** provide, and `apply` refuses rather
+than deploying something that silently won't route. Blockers are distinct from
+advisory `issues`; there is no force flag — clear the cause and re-apply.
+
+| Blocker | Fires when |
+|---|---|
+| `port_conflict` | A `public` host port is already bound on the panel host. |
+| `remote_target` | A service with appliance features targets a remote `server:` — remote appliance apply is deferred; run it on the panel host. |
+| `observed_server` | The target server is observed (read-only); ServerKit won't mutate it. |
+| `firewall_undetected` | Public ports are declared but the host firewall state couldn't be determined. |
+
+A *manageable-firewall-simply-absent* case is a warning, not a blocker: the port
+is still published, just not firewall-managed.
+
## Environment variables
Each entry has a `key` plus **exactly one** value source:
diff --git a/docs/serverkit-yaml.schema.json b/docs/serverkit-yaml.schema.json
index 4a19bb7d..a60d0485 100644
--- a/docs/serverkit-yaml.schema.json
+++ b/docs/serverkit-yaml.schema.json
@@ -73,6 +73,11 @@
"minimum": 1,
"maximum": 65535
},
+ "ports": {
+ "description": "Typed L4 port publishes (appliance tier). Each entry is a raw tcp/udp publish — the escape hatch for services that speak more than HTTP (media/UDP, VoIP, brokers). The legacy scalar `port` keeps its HTTP/nginx behavior and is separate.",
+ "type": "array",
+ "items": { "$ref": "#/definitions/portDecl" }
+ },
"healthCheckPath": {
"description": "HTTP path used for health checks and the zero-downtime restart gate.",
"type": "string"
@@ -121,6 +126,33 @@
}
}
},
+ "portDecl": {
+ "type": "object",
+ "required": ["port"],
+ "additionalProperties": true,
+ "properties": {
+ "port": {
+ "description": "Host port to publish.",
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 65535
+ },
+ "containerPort": {
+ "description": "Container port to publish to. Defaults to the host port.",
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 65535
+ },
+ "protocol": {
+ "description": "L4 protocol. Defaults to tcp.",
+ "enum": ["tcp", "udp"]
+ },
+ "expose": {
+ "description": "public = bind 0.0.0.0 and open the firewall; local = bind 127.0.0.1 only. Defaults to public.",
+ "enum": ["public", "local"]
+ }
+ }
+ },
"envVar": {
"type": "object",
"required": ["key"],