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): appliance-tier typed L4 ports + plan-time blockers rail (plan 35 ph1)
Juan Denis06c3fcf28c88
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 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/api/apps.py b/backend/app/api/apps.pyindex 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/volumesif app.app_type == 'docker' and app.root_path:try:diff --git a/backend/app/api/manifests.py b/backend/app/api/manifests.pyindex 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 AuditServiceAuditService.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:passdiff --git a/backend/app/services/app_port_service.py b/backend/app/services/app_port_service.pynew file mode 100644index 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 resultsdiff --git a/backend/app/services/buildpack_service.py b/backend/app/services/buildpack_service.pyindex 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'# ------------------------------------------------------------------ ## Cachingdiff --git a/backend/app/services/manifest_apply_service.py b/backend/app/services/manifest_apply_service.pyindex 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}+@classmethoddef _do_upsert_backup_policy(cls, project, env, payload, user_id):from app.services.backup_policy_service import BackupPolicyServicediff --git a/backend/app/services/manifest_spec_service.py b/backend/app/services/manifest_spec_service.pyindex 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+@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/tests/test_manifest_appliance_ports.py b/backend/tests/test_manifest_appliance_ports.pynew file mode 100644index 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.mdindex 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 variablesEach entry has a `key` plus **exactly one** value source:diff --git a/docs/serverkit-yaml.schema.json b/docs/serverkit-yaml.schema.jsonindex 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"],