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(deploy): prove a deploy can work before stopping the live one

Juan Denis6b042b099862
diff --git a/backend/app/services/deploy_preflight_service.py b/backend/app/services/deploy_preflight_service.py
new file mode 100644
index 00000000..77ed4ab4
--- /dev/null
+++ b/backend/app/services/deploy_preflight_service.py
@@ -0,0 +1,467 @@
+"""Deploy preflight — prove a deploy can work BEFORE anything live is stopped.
+
+Plan 72 B.1. Every redeploy path used to reach its point of no return (a
+``compose down`` / ``docker stop``) *before* anything had validated the new
+configuration. An invalid compose file, an image that no longer pulls, or a
+port somebody else took took the live site down and left it down: nginx 502s
+until a human intervened.
+
+The fix is not blue/green (that is B.2/B.3) — it is ordering. Everything that
+can be checked while the old containers keep serving is checked here, and every
+caller aborts on a blocking finding, at which point the live deployment is
+byte-for-byte untouched. Nothing in this module stops, removes, recreates or
+rewrites anything; the only side effects are image pulls/builds, which are
+additive by construction.
+
+The checks, in the order they run (a broken compose makes the rest meaningless):
+
+1. **Compose validity** — wires the long-existing
+ :meth:`DockerService.validate_compose_file` (``docker compose config
+ --quiet``), whose only caller until now was a manual API endpoint.
+2. **Image resolution** — build (when the project declares ``build:``) or pull,
+ to completion. A resolution failure is downgraded to advisory when every
+ referenced image is already present locally, so a locally-tagged image that
+ was never pushed to a registry keeps deploying exactly as it did before.
+3. **Host port conflicts** — reuses ``ManifestApplyService._port_bound`` (the
+ same probe behind the manifest-apply ``kind: 'port_conflict'`` blocker) and
+ only for ports the *new* configuration wants that the *currently running*
+ project does not already publish. Probing a port the deploy's own live
+ container holds would fail every ordinary redeploy, so owned ports are
+ excluded; when ownership cannot be determined the check is skipped (a false
+ abort is worse than a missed warning).
+"""
+
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Set
+
+from app.services.docker_service import DockerService
+
+logger = logging.getLogger(__name__)
+
+BLOCKING = 'error'
+ADVISORY = 'warning'
+
+# Finding kinds. ``port_conflict`` deliberately matches the manifest-apply
+# blocker kind so the two surfaces speak the same vocabulary.
+KIND_COMPOSE_INVALID = 'compose_invalid'
+KIND_IMAGE_UNRESOLVED = 'image_unresolved'
+KIND_BUILD_FAILED = 'build_failed'
+KIND_PORT_CONFLICT = 'port_conflict'
+
+LogFn = Optional[Callable[[str], None]]
+
+#: Appended to every blocking log line. This is the user-visible payoff: the
+#: deploy failed and the site is still up.
+UNTOUCHED = 'The running deployment was left untouched.'
+
+
+@dataclass(frozen=True)
+class PreflightFinding:
+ """One thing the preflight noticed. ``severity`` decides whether it aborts."""
+
+ kind: str
+ message: str
+ severity: str = BLOCKING
+ detail: str = ''
+
+ def to_dict(self) -> Dict[str, str]:
+ return {'kind': self.kind, 'message': self.message,
+ 'severity': self.severity, 'detail': self.detail}
+
+
+@dataclass
+class PreflightResult:
+ """Structured pass/fail plus the findings behind it."""
+
+ findings: List[PreflightFinding] = field(default_factory=list)
+ checks: List[str] = field(default_factory=list)
+ skipped: List[str] = field(default_factory=list)
+
+ @property
+ def blockers(self) -> List[PreflightFinding]:
+ return [f for f in self.findings if f.severity == BLOCKING]
+
+ @property
+ def ok(self) -> bool:
+ """True when nothing blocking was found — i.e. it is safe to switch over."""
+ return not self.blockers
+
+ @property
+ def error(self) -> Optional[str]:
+ blockers = self.blockers
+ return blockers[0].message if blockers else None
+
+ def to_dict(self) -> Dict[str, Any]:
+ return {
+ 'ok': self.ok,
+ 'checks': list(self.checks),
+ 'skipped': list(self.skipped),
+ 'findings': [f.to_dict() for f in self.findings],
+ }
+
+ def add(self, finding: PreflightFinding, log: LogFn = None) -> 'PreflightResult':
+ self.findings.append(finding)
+ prefix = 'Preflight failed' if finding.severity == BLOCKING else 'Preflight warning'
+ suffix = f' {UNTOUCHED}' if finding.severity == BLOCKING else ''
+ _emit(log, f'{prefix}: {finding.message}{suffix}')
+ return self
+
+
+def _emit(log: LogFn, message: str) -> None:
+ """Push one human-readable line at the caller's log sink. Never raises.
+
+ Deploy jobs pass the run-log callback here, so preflight lines land in the
+ Deploy Console next to the compose transcript.
+ """
+ logger.info(message)
+ if log is None:
+ return
+ try:
+ log(message)
+ except Exception: # pragma: no cover - a broken sink must not fail a deploy
+ pass
+
+
+def _first_line(text: Any, limit: int = 400) -> str:
+ """Condense a subprocess error blob into one readable line."""
+ if not text:
+ return ''
+ lines = [ln.strip() for ln in str(text).splitlines() if ln.strip()]
+ if not lines:
+ return ''
+ joined = lines[0] if len(lines) == 1 else ' | '.join(lines[:3])
+ return joined[:limit]
+
+
+# ---------------------------------------------------------------------------
+# compose preflight
+# ---------------------------------------------------------------------------
+
+def preflight_compose_project(project_path: str, compose_file: str = None, *,
+ resolve_images: bool = True,
+ check_ports: bool = True,
+ log: LogFn = None,
+ label: str = None) -> PreflightResult:
+ """Validate a compose project before its live containers are stopped.
+
+ ``compose_file`` may name a candidate file that is not yet the project's
+ real compose (that is how a template update validates the *next* compose
+ while the current one keeps running).
+
+ Returns a :class:`PreflightResult`; callers must abort on ``not ok`` and
+ must not have stopped anything before calling.
+ """
+ result = PreflightResult()
+ what = label or (compose_file or 'docker-compose.yml')
+ _emit(log, f'Preflight: validating {what} before stopping the running containers')
+
+ # 1. compose validity -----------------------------------------------------
+ try:
+ validation = DockerService.validate_compose_file(project_path, compose_file)
+ except Exception as exc: # pragma: no cover - defensive
+ validation = {'valid': False, 'error': str(exc)}
+ if not validation.get('valid'):
+ return result.add(PreflightFinding(
+ kind=KIND_COMPOSE_INVALID,
+ message=(f'{what} is not a valid compose file — '
+ f'{_first_line(validation.get("error")) or "docker compose config rejected it"}'),
+ detail=str(validation.get('error') or ''),
+ ), log)
+ result.checks.append('compose_config')
+
+ # The parsed config drives both remaining checks; one `docker compose
+ # config` for both rather than one each.
+ config = _compose_config(project_path, compose_file)
+
+ # 2. image resolution -----------------------------------------------------
+ if resolve_images:
+ if config is None:
+ result.skipped.append('image_resolution')
+ else:
+ _resolve_images(project_path, compose_file, config, result, log)
+ if not result.ok:
+ return result
+
+ # 3. port conflicts -------------------------------------------------------
+ if check_ports:
+ if config is None:
+ result.skipped.append('port_conflicts')
+ else:
+ _check_ports(project_path, config, result, log)
+ if not result.ok:
+ return result
+
+ _emit(log, 'Preflight passed — safe to switch over')
+ return result
+
+
+def _compose_config(project_path: str, compose_file: str = None) -> Optional[Dict[str, Any]]:
+ """Parsed ``docker compose config``, or None when it cannot be read.
+
+ None means "unknown", and every caller of this treats unknown as
+ fail-open: an inability to introspect must never abort a deploy that the
+ old code would have run.
+ """
+ try:
+ parsed = DockerService.get_compose_config(project_path, compose_file)
+ except Exception as exc: # pragma: no cover - defensive
+ logger.debug('compose config read failed for %s: %s', project_path, exc)
+ return None
+ if not parsed.get('success'):
+ return None
+ config = parsed.get('config')
+ return config if isinstance(config, dict) else None
+
+
+def _resolve_images(project_path: str, compose_file: str, config: Dict[str, Any],
+ result: PreflightResult, log: LogFn) -> None:
+ """Build and pull every image the project needs, to completion.
+
+ Services with a ``build:`` section are built (the failure mode git deploys
+ actually hit); the rest are pulled. Doing both before the stop is the whole
+ point — ``compose up`` would otherwise discover the failure with nothing
+ left serving. In a mixed project the pull is issued per service, because a
+ whole-project ``compose pull`` also tries to pull the buildable ones and
+ fails on images that only exist once built.
+ """
+ services = config.get('services') or {}
+ buildable = [name for name, svc in services.items()
+ if isinstance(svc, dict) and svc.get('build')]
+ pullable = {name: svc['image'] for name, svc in services.items()
+ if isinstance(svc, dict) and svc.get('image') and not svc.get('build')}
+
+ if buildable:
+ _emit(log, f'Preflight: building {len(buildable)} image(s) before the switchover')
+ try:
+ build = DockerService.compose_build(project_path, compose_file=compose_file)
+ except Exception as exc: # pragma: no cover - defensive
+ build = {'success': False, 'error': str(exc)}
+ if not build.get('success'):
+ result.add(PreflightFinding(
+ kind=KIND_BUILD_FAILED,
+ message=(f'image build failed — '
+ f'{_first_line(build.get("error")) or "docker compose build returned a non-zero exit"}'),
+ detail=str(build.get('error') or ''),
+ ), log)
+ return
+ result.checks.append('image_build')
+
+ images = sorted(set(pullable.values()))
+ if not images:
+ if not buildable:
+ result.skipped.append('image_resolution')
+ return
+
+ _emit(log, f'Preflight: pulling {len(images)} image(s) before the switchover')
+ pull = _pull_images(project_path, compose_file,
+ list(pullable) if buildable else None)
+ if pull.get('success'):
+ result.checks.append('image_pull')
+ return
+
+ # A pull failure is only fatal when the image genuinely isn't available.
+ # Locally-built/tagged images that were never pushed cannot be pulled and
+ # deployed fine before this check existed — do not start failing them.
+ missing = [ref for ref in images if not _image_present(ref)]
+ if not missing:
+ result.add(PreflightFinding(
+ kind=KIND_IMAGE_UNRESOLVED,
+ severity=ADVISORY,
+ message=('could not pull images, but every one is already present '
+ f'locally — continuing ({_first_line(pull.get("error"))})'),
+ detail=str(pull.get('error') or ''),
+ ), log)
+ result.checks.append('image_pull')
+ return
+
+ result.add(PreflightFinding(
+ kind=KIND_IMAGE_UNRESOLVED,
+ message=(f'image {missing[0]} could not be resolved — '
+ f'{_first_line(pull.get("error")) or "docker compose pull failed"}'),
+ detail=str(pull.get('error') or ''),
+ ), log)
+
+
+def _pull_images(project_path: str, compose_file: str,
+ services: Optional[List[str]]) -> Dict[str, Any]:
+ """``compose pull`` for the whole project, or service by service."""
+ targets = services if services is not None else [None]
+ for service in targets:
+ try:
+ pull = DockerService.compose_pull(project_path, service=service,
+ compose_file=compose_file)
+ except Exception as exc: # pragma: no cover - defensive
+ pull = {'success': False, 'error': str(exc)}
+ if not pull.get('success'):
+ return pull
+ return {'success': True}
+
+
+def _image_present(image_ref: str) -> bool:
+ """True when ``image_ref`` already exists in the local image store."""
+ try:
+ return bool(DockerService.image_exists(image_ref))
+ except Exception: # pragma: no cover - defensive
+ return False
+
+
+def _check_ports(project_path: str, config: Dict[str, Any],
+ result: PreflightResult, log: LogFn) -> None:
+ """Flag host ports the new config wants that somebody else already holds."""
+ desired = _desired_host_ports(config)
+ if not desired:
+ result.skipped.append('port_conflicts')
+ return
+
+ owned = published_host_ports(project_path)
+ if owned is None:
+ # Cannot tell which ports are ours; probing would flag our own live
+ # containers and abort a perfectly good redeploy.
+ result.skipped.append('port_conflicts')
+ return
+
+ for port in sorted(desired - owned):
+ if _port_bound(port):
+ result.add(PreflightFinding(
+ kind=KIND_PORT_CONFLICT,
+ message=(f'host port {port} is already in use by something else — '
+ f'free the port or publish this service on another one'),
+ detail=f'port {port} is bound on 0.0.0.0 and is not published by this project',
+ ), log)
+ if result.ok:
+ result.checks.append('port_conflicts')
+
+
+def _port_bound(port: int) -> bool:
+ """Reuse of the manifest-apply port probe (its ``port_conflict`` blocker).
+
+ Called through the class so the existing test seam
+ (``ManifestApplyService._port_bound``) keeps working for both surfaces.
+ """
+ try:
+ from app.services.manifest_apply_service import ManifestApplyService
+ return bool(ManifestApplyService._port_bound(int(port)))
+ except Exception: # pragma: no cover - defensive; unknown means "not a conflict"
+ return False
+
+
+# ---------------------------------------------------------------------------
+# port bookkeeping
+# ---------------------------------------------------------------------------
+
+_PORTS_RE = re.compile(r'(?:(?:\d{1,3}(?:\.\d{1,3}){3}|\[[^\]]+\]|::):)?(\d+)(?:-\d+)?->')
+
+
+def _desired_host_ports(config: Dict[str, Any]) -> Set[int]:
+ """Host ports published by the compose config (long and short syntax)."""
+ ports: Set[int] = set()
+ for svc in (config.get('services') or {}).values():
+ if not isinstance(svc, dict):
+ continue
+ for entry in svc.get('ports') or []:
+ port = (_published_from_mapping(entry) if isinstance(entry, dict)
+ else _published_from_short(str(entry)))
+ if port is not None:
+ ports.add(port)
+ return ports
+
+
+def _published_from_mapping(entry: Dict[str, Any]) -> Optional[int]:
+ published = entry.get('published')
+ if published in (None, ''):
+ return None
+ try:
+ return int(str(published).split('-')[0])
+ except (TypeError, ValueError):
+ return None
+
+
+def _published_from_short(spec: str) -> Optional[int]:
+ """`8080:80`, `127.0.0.1:8080:80`, `8080:80/tcp` -> 8080. `80` -> None."""
+ spec = spec.strip().split('/')[0]
+ parts = spec.split(':')
+ if len(parts) < 2:
+ return None # container-only port: docker picks the host port
+ candidate = parts[-2]
+ if '-' in candidate:
+ return None # a range; fail open rather than guess
+ try:
+ return int(candidate)
+ except ValueError:
+ return None
+
+
+def published_host_ports(project_path: str, compose_file: str = None) -> Optional[Set[int]]:
+ """Host ports the project's *currently running* containers publish.
+
+ Returns None when it cannot be determined — callers must then skip the
+ port check rather than assume the ports are free.
+ """
+ try:
+ containers = DockerService.compose_ps(project_path, compose_file)
+ except Exception as exc: # pragma: no cover - defensive
+ logger.debug('compose ps failed for %s: %s', project_path, exc)
+ return None
+ if containers is None:
+ return None
+
+ ports: Set[int] = set()
+ for container in containers:
+ if not isinstance(container, dict):
+ continue
+ for publisher in container.get('Publishers') or []:
+ if not isinstance(publisher, dict):
+ continue
+ try:
+ published = int(publisher.get('PublishedPort') or 0)
+ except (TypeError, ValueError):
+ continue
+ if published:
+ ports.add(published)
+ raw = container.get('Ports')
+ if isinstance(raw, str):
+ ports.update(int(m) for m in _PORTS_RE.findall(raw))
+ return ports
+
+
+# ---------------------------------------------------------------------------
+# single-container preflight
+# ---------------------------------------------------------------------------
+
+def preflight_image(image_ref: str, *, pull: Callable[[], Dict[str, Any]] = None,
+ log: LogFn = None) -> PreflightResult:
+ """Resolve a single container image before its predecessor is stopped.
+
+ The ``docker run`` deploy path has no compose file to validate; its one
+ pre-traffic requirement is that the image exists by the time the old
+ container is gone. ``pull`` is supplied by the caller (it owns registry
+ authentication); without it the image came from the build step that already
+ ran, and only local presence is asserted.
+ """
+ result = PreflightResult()
+ if not image_ref:
+ return result.add(PreflightFinding(
+ kind=KIND_IMAGE_UNRESOLVED,
+ message='no image was produced for this deployment'), log)
+
+ if pull is not None:
+ _emit(log, f'Preflight: pulling {image_ref} before the switchover')
+ try:
+ pulled = pull()
+ except Exception as exc: # pragma: no cover - defensive
+ pulled = {'success': False, 'error': str(exc)}
+ if not pulled.get('success'):
+ return result.add(PreflightFinding(
+ kind=KIND_IMAGE_UNRESOLVED,
+ message=(f'image {image_ref} could not be pulled — '
+ f'{_first_line(pulled.get("error")) or "registry pull failed"}'),
+ detail=str(pulled.get('error') or ''),
+ ), log)
+ result.checks.append('image_pull')
+ else:
+ result.checks.append('image_from_build')
+
+ _emit(log, f'Preflight passed — {image_ref} is resolved, safe to switch over')
+ return result
diff --git a/backend/app/services/deployment_service.py b/backend/app/services/deployment_service.py
index 03453fd6..73b13f1d 100644
--- a/backend/app/services/deployment_service.py
+++ b/backend/app/services/deployment_service.py
@@ -254,14 +254,6 @@ class DeploymentService:
if log_callback:
log_callback(f"Deploying Docker image: {image_tag}")
- # Stop and remove existing container
- existing = DockerService.get_container(container_name)
- if existing:
- if log_callback:
- log_callback("Stopping existing container...")
- DockerService.stop_container(container_name)
- DockerService.remove_container(container_name)
-
# Configure container
ports = []
if app.port:
@@ -273,18 +265,40 @@ class DeploymentService:
from app.services.env_service import EnvService
env = EnvService.get_effective_env(app.id)
- # Authenticate + pre-pull from a private registry when this app is bound
- # to one, so the run below uses the locally-present image. Gated on
- # registry_id: apps built from source never set it, so their locally-built
- # image_tag is untouched (an authenticated pull of it would fail).
+ # ---- preflight (plan 72 B.1) -------------------------------------
+ # Everything that can fail while the old container keeps serving runs
+ # HERE, above the stop. The image is the only pre-traffic requirement
+ # this path has: a build already ran to completion in deploy() step 1,
+ # and a registry-bound app pulls now instead of after the stop — that
+ # pull used to sit below the stop/remove, so a registry hiccup left the
+ # app with no container at all. Gated on registry_id: apps built from
+ # source never set it, so their locally-built image_tag is untouched
+ # (an authenticated pull of it would fail).
from app.services.container_registry_service import ContainerRegistryService
+ from app.services import deploy_preflight_service as preflight
registry = ContainerRegistryService.for_app(app)
+
+ def _registry_pull():
+ return DockerService.pull_image(image_tag, tag=None, registry=registry)
+
+ pull_fn = None
if registry is not None:
if log_callback:
log_callback(f"Authenticating with registry {registry.name}...")
- pull = DockerService.pull_image(image_tag, tag=None, registry=registry)
- if not pull.get('success'):
- return {'success': False, 'error': pull.get('error', 'Registry pull failed')}
+ pull_fn = _registry_pull
+
+ checks = preflight.preflight_image(image_tag, pull=pull_fn, log=log_callback)
+ if not checks.ok:
+ return {'success': False, 'error': checks.error,
+ 'preflight': checks.to_dict()}
+
+ # ---- switchover: past this line the live container is gone ---------
+ existing = DockerService.get_container(container_name)
+ if existing:
+ if log_callback:
+ log_callback("Stopping existing container...")
+ DockerService.stop_container(container_name)
+ DockerService.remove_container(container_name)
# Attach any managed volumes so app data persists across redeploys
# (each returns a `name:/mount[:ro]` spec for `docker run -v`).
diff --git a/backend/app/services/docker_service.py b/backend/app/services/docker_service.py
index 1d7047e8..8da5cfc0 100644
--- a/backend/app/services/docker_service.py
+++ b/backend/app/services/docker_service.py
@@ -1299,6 +1299,43 @@ class DockerService:
except Exception as e:
return {'success': False, 'error': str(e)}
+ @classmethod
+ def compose_build(cls, project_path, service=None, compose_file=None, no_cache=False):
+ """Build the project's images without starting anything.
+
+ The deploy preflight (plan 72 B.1) runs this *before* the live
+ containers are stopped, so a build failure can no longer take a site
+ down: the subsequent ``up --build`` re-uses the layer cache.
+ """
+ try:
+ cmd = cls._compose_base_cmd(compose_file) + ['build']
+ if no_cache:
+ cmd.append('--no-cache')
+ if service:
+ cmd.append(service)
+
+ result = subprocess.run(
+ cmd, cwd=project_path,
+ capture_output=True, text=True
+ )
+ if result.returncode == 0:
+ return {'success': True, 'output': result.stdout}
+ return {'success': False, 'error': result.stderr, 'output': result.stdout}
+ except Exception as e:
+ return {'success': False, 'error': str(e)}
+
+ @staticmethod
+ def image_exists(image_ref):
+ """True when the image is already in the local image store."""
+ try:
+ result = subprocess.run(
+ ['docker', 'image', 'inspect', image_ref],
+ capture_output=True, text=True
+ )
+ return result.returncode == 0
+ except Exception:
+ return False
+
@classmethod
def validate_compose_file(cls, project_path, compose_file=None):
"""Validate a Docker Compose file."""
diff --git a/backend/app/services/git_deploy_service.py b/backend/app/services/git_deploy_service.py
index 087e8279..43991146 100644
--- a/backend/app/services/git_deploy_service.py
+++ b/backend/app/services/git_deploy_service.py
@@ -388,17 +388,44 @@ class GitDeployService:
return {'success': False, 'error': str(e)}
@classmethod
- def _standard_restart(cls, app) -> Dict:
- """Standard restart - stop then start."""
+ def _standard_restart(cls, app, log_callback=None) -> Dict:
+ """Standard restart - validate, build, then stop and start.
+
+ The default webhook path. It used to go straight to ``compose down``,
+ so a commit that broke the compose file or the build took the site down
+ and left it down (plan 72 B.1). The preflight now validates the compose
+ and builds the images to completion while the old containers are still
+ serving; only then is anything stopped.
+ """
from app.services.docker_service import DockerService
+ from app.services import deploy_preflight_service as preflight
output = []
- # Stop
+ def _log(line: str) -> None:
+ output.append(line)
+ if log_callback:
+ try:
+ log_callback(line)
+ except Exception:
+ pass
+
+ checks = preflight.preflight_compose_project(app.root_path, log=_log)
+ if not checks.ok:
+ # Nothing was stopped — the previous release is still serving.
+ return {
+ 'success': False,
+ 'output': '\n'.join(output),
+ 'error': checks.error,
+ 'preflight': checks.to_dict(),
+ }
+
+ # ---- switchover: past this line the live stack is down -------------
stop_result = DockerService.compose_down(app.root_path)
output.append(f"Stop: {stop_result.get('message', stop_result.get('error', 'Unknown'))}")
- # Build and start
+ # Build and start (the build is a cache hit — the preflight already
+ # built these images before anything was stopped)
up_result = DockerService.compose_up(app.root_path, detach=True, build=True)
output.append(f"Start: {up_result.get('message', up_result.get('error', 'Unknown'))}")
diff --git a/backend/app/services/template_service.py b/backend/app/services/template_service.py
index e2e64873..57e399c7 100644
--- a/backend/app/services/template_service.py
+++ b/backend/app/services/template_service.py
@@ -23,7 +23,7 @@ import hashlib
import threading
import subprocess
from datetime import datetime
-from typing import Dict, List, Optional, Any
+from typing import Callable, Dict, List, Optional, Any
from pathlib import Path
import requests
@@ -2230,11 +2230,19 @@ class TemplateService:
}
@classmethod
- def update_app(cls, app_id: int, user_id: int = None) -> Dict:
- """Update an installed app to the latest template version."""
+ def update_app(cls, app_id: int, user_id: int = None,
+ log_callback: Callable[[str], None] = None) -> Dict:
+ """Update an installed app to the latest template version.
+
+ The new compose is rendered, validated and its images resolved *before*
+ the running containers are stopped (plan 72 B.1) — a template whose new
+ version does not render, does not validate or cannot pull now fails
+ with the old stack still serving.
+ """
from app import db
from app.models import Application
from app.services.docker_service import DockerService
+ from app.services import deploy_preflight_service as preflight
config = cls.get_config()
installed = config.get('installed', {}).get(str(app_id))
@@ -2256,8 +2264,13 @@ class TemplateService:
template = result['template']
- # Load existing variables
+ # Load existing variables. install_info is written back further down, so
+ # it must exist even when the marker file is missing or corrupt —
+ # otherwise the update raised NameError *after* compose_down and left
+ # the app stopped, which is exactly the outage this path is supposed to
+ # avoid.
info_path = os.path.join(app_path, '.serverkit-template.json')
+ install_info = {}
try:
with open(info_path, 'r') as f:
install_info = json.load(f)
@@ -2293,11 +2306,36 @@ class TemplateService:
if not script_result.get('success'):
return script_result
- # Stop current containers
+ # Generate the new compose FIRST and validate it while the current
+ # stack is still running. It is written to a sibling candidate file
+ # (a dotfile, so nothing globbing docker-compose* picks it up) —
+ # same directory, so relative bind mounts and .env resolve exactly
+ # as they will after the switchover.
+ compose_content = cls.generate_compose(template, variables)
+ candidate_name = '.serverkit-preflight-compose.yml'
+ candidate_path = os.path.join(app_path, candidate_name)
+ try:
+ with open(candidate_path, 'w') as f:
+ f.write(compose_content)
+ checks = preflight.preflight_compose_project(
+ app_path, compose_file=candidate_name,
+ log=log_callback,
+ label=f'the new {template.get("name", template_id)} compose',
+ )
+ finally:
+ if os.path.exists(candidate_path):
+ os.remove(candidate_path)
+
+ if not checks.ok:
+ # Nothing has been stopped and nothing on disk has changed —
+ # the app is still serving the version it was serving.
+ return {'success': False, 'error': checks.error,
+ 'preflight': checks.to_dict()}
+
+ # ---- switchover: past this line the live stack is down ---------
DockerService.compose_down(app_path)
- # Generate new docker-compose.yml
- compose_content = cls.generate_compose(template, variables)
+ # Write the compose that was just validated
with open(compose_path, 'w') as f:
f.write(compose_content)
@@ -2322,7 +2360,10 @@ class TemplateService:
with open(info_path, 'w') as f:
json.dump(install_info, f, indent=2)
- # Pull new images and start
+ # Pull new images and start. The preflight above already pulled
+ # everything the validated compose referenced, so this is a cached
+ # no-op for those; it stays as the safety net for images that
+ # _process_template_files introduced after validation.
DockerService.compose_pull(app_path)
compose_result = DockerService.compose_up(app_path, detach=True, build=True)
diff --git a/backend/tests/test_deploy_preflight.py b/backend/tests/test_deploy_preflight.py
new file mode 100644
index 00000000..a3e9825b
--- /dev/null
+++ b/backend/tests/test_deploy_preflight.py
@@ -0,0 +1,399 @@
+"""Deploy preflight — plan 72 B.1.
+
+The property under test is ORDERING, not cleverness: every redeploy path must
+finish validating the new configuration *before* it stops anything. So most of
+these tests make the preflight fail and then prove the destructive call was
+never reached and the live configuration is byte-for-byte unchanged.
+
+Covered:
+- the compose preflight itself (validity, image resolution, port conflicts)
+- port-conflict reuse of the manifest-apply probe, including the redeploy case
+ where the port is held by the deploy's OWN containers (must not fire)
+- GitDeployService._standard_restart : compose_down not called on failure
+- TemplateService.update_app : compose_down not called, compose
+ file on disk unchanged
+- DeploymentService._deploy_docker : stop/remove not called when the
+ registry pull fails
+- and, for each, that a valid deploy still deploys
+"""
+import os
+import types
+
+import pytest
+
+from app import db
+from app.models import Application, User
+from app.services import deploy_preflight_service as preflight
+from app.services.docker_service import DockerService
+from app.services.manifest_apply_service import ManifestApplyService
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+def _owner(username='pfowner'):
+ user = User(email=f'{username}@test.local', username=username,
+ password_hash='x', role=User.ROLE_ADMIN, is_active=True)
+ db.session.add(user)
+ db.session.commit()
+ return user
+
+
+def _app_row(root_path, name='pf-app', port=None):
+ application = Application(name=name, app_type='docker', status='running',
+ root_path=str(root_path), port=port,
+ user_id=_owner(f'{name}-owner').id)
+ db.session.add(application)
+ db.session.commit()
+ return application
+
+
+def _stub_compose(monkeypatch, *, valid=True, config=None, build=True,
+ pull=True, ps=None, error='services.web.ports: invalid'):
+ """Stub every docker seam the compose preflight touches; return a call log."""
+ calls = []
+
+ monkeypatch.setattr(DockerService, 'validate_compose_file', classmethod(
+ lambda cls, path, compose_file=None: (
+ calls.append('validate') or
+ ({'valid': True} if valid else {'valid': False, 'error': error}))))
+ monkeypatch.setattr(DockerService, 'get_compose_config', classmethod(
+ lambda cls, path, compose_file=None: (
+ calls.append('config') or
+ {'success': True, 'config': config if config is not None
+ else {'services': {'web': {'image': 'nginx:1.25'}}}})))
+ monkeypatch.setattr(DockerService, 'compose_build', classmethod(
+ lambda cls, path, service=None, compose_file=None, no_cache=False: (
+ calls.append('build') or
+ ({'success': True} if build else {'success': False, 'error': 'build blew up'}))))
+ monkeypatch.setattr(DockerService, 'compose_pull', classmethod(
+ lambda cls, path, service=None, compose_file=None: (
+ calls.append('pull') or
+ ({'success': True} if pull else {'success': False, 'error': 'manifest unknown'}))))
+ monkeypatch.setattr(DockerService, 'compose_ps', classmethod(
+ lambda cls, path, compose_file=None: (calls.append('ps') or (ps if ps is not None else []))))
+ monkeypatch.setattr(DockerService, 'compose_down', classmethod(
+ lambda cls, path, **kw: calls.append('DOWN') or {'success': True}))
+ monkeypatch.setattr(DockerService, 'compose_up', classmethod(
+ lambda cls, path, **kw: calls.append('UP') or {'success': True}))
+ monkeypatch.setattr(ManifestApplyService, '_port_bound', staticmethod(lambda port: False))
+ return calls
+
+
+# ── the preflight unit ───────────────────────────────────────────────────────
+
+def test_invalid_compose_is_blocking_and_stops_the_preflight(app, monkeypatch):
+ calls = _stub_compose(monkeypatch, valid=False)
+ lines = []
+
+ result = preflight.preflight_compose_project('/srv/x', log=lines.append)
+
+ assert result.ok is False
+ assert [f.kind for f in result.blockers] == ['compose_invalid']
+ assert 'services.web.ports: invalid' in result.error
+ # Nothing past validation ran — no pull, no build, no probing.
+ assert calls == ['validate']
+ # The user-visible payoff line.
+ assert any('left untouched' in line for line in lines)
+
+
+def test_valid_compose_pulls_images_and_passes(app, monkeypatch):
+ calls = _stub_compose(monkeypatch)
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert result.ok is True
+ assert 'compose_config' in result.checks and 'image_pull' in result.checks
+ assert 'pull' in calls and 'build' not in calls
+
+
+def test_project_with_a_build_section_builds_before_anything_stops(app, monkeypatch):
+ calls = _stub_compose(monkeypatch,
+ config={'services': {'api': {'build': {'context': '.'}}}})
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert result.ok is True
+ assert 'image_build' in result.checks
+ assert 'build' in calls and 'pull' not in calls
+
+
+def test_mixed_project_builds_and_pulls_only_the_image_only_services(app, monkeypatch):
+ """A whole-project `compose pull` also tries to pull the buildable service
+ and fails on an image that only exists once built — so pull by name."""
+ calls = _stub_compose(monkeypatch, config={'services': {
+ 'api': {'build': '.', 'image': 'local/api:dev'},
+ 'cache': {'image': 'redis:7'},
+ }})
+ pulled = []
+ monkeypatch.setattr(DockerService, 'compose_pull', classmethod(
+ lambda cls, path, service=None, compose_file=None: (
+ pulled.append(service) or {'success': True})))
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert result.ok is True
+ assert pulled == ['cache']
+ assert 'build' in calls
+ assert result.checks == ['compose_config', 'image_build', 'image_pull']
+
+
+def test_build_failure_blocks(app, monkeypatch):
+ _stub_compose(monkeypatch, build=False,
+ config={'services': {'api': {'build': '.'}}})
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert result.ok is False
+ assert result.blockers[0].kind == 'build_failed'
+ assert 'build blew up' in result.error
+
+
+def test_unpullable_image_blocks_when_it_is_not_present_locally(app, monkeypatch):
+ _stub_compose(monkeypatch, pull=False)
+ monkeypatch.setattr(DockerService, 'image_exists', staticmethod(lambda ref: False))
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert result.ok is False
+ assert result.blockers[0].kind == 'image_unresolved'
+ assert 'nginx:1.25' in result.error
+
+
+def test_unpullable_image_is_advisory_when_already_present_locally(app, monkeypatch):
+ """A locally-tagged image that was never pushed cannot be pulled and
+ deployed fine before B.1 existed — it must keep deploying."""
+ _stub_compose(monkeypatch, pull=False)
+ monkeypatch.setattr(DockerService, 'image_exists', staticmethod(lambda ref: True))
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert result.ok is True
+ assert [f.severity for f in result.findings] == ['warning']
+
+
+def test_port_conflict_is_reported_via_the_manifest_apply_probe(app, monkeypatch):
+ _stub_compose(monkeypatch,
+ config={'services': {'web': {'image': 'nginx',
+ 'ports': ['8080:80']}}},
+ ps=[])
+ probed = []
+ monkeypatch.setattr(ManifestApplyService, '_port_bound',
+ staticmethod(lambda port: probed.append(port) or True))
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert probed == [8080]
+ assert result.ok is False
+ assert result.blockers[0].kind == 'port_conflict'
+ assert '8080' in result.error
+
+
+def test_a_port_the_project_already_publishes_is_not_a_conflict(app, monkeypatch):
+ """The redeploy case. Probing a port our own live container holds would
+ abort every ordinary redeploy, so owned ports are excluded."""
+ _stub_compose(monkeypatch,
+ config={'services': {'web': {'image': 'nginx',
+ 'ports': ['8080:80']}}},
+ ps=[{'Publishers': [{'PublishedPort': 8080, 'TargetPort': 80}]}])
+ probed = []
+ monkeypatch.setattr(ManifestApplyService, '_port_bound',
+ staticmethod(lambda port: probed.append(port) or True))
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert probed == [] # never even asked
+ assert result.ok is True
+
+
+def test_unknown_port_ownership_skips_the_check_rather_than_aborting(app, monkeypatch):
+ _stub_compose(monkeypatch,
+ config={'services': {'web': {'image': 'nginx', 'ports': ['8080:80']}}})
+ monkeypatch.setattr(DockerService, 'compose_ps', classmethod(
+ lambda cls, path, compose_file=None: (_ for _ in ()).throw(RuntimeError('no docker'))))
+ monkeypatch.setattr(ManifestApplyService, '_port_bound',
+ staticmethod(lambda port: True))
+
+ result = preflight.preflight_compose_project('/srv/x')
+
+ assert result.ok is True
+ assert 'port_conflicts' in result.skipped
+
+
[email protected]('spec,expected', [
+ ('8080:80', 8080),
+ ('127.0.0.1:8080:80', 8080),
+ ('8080:80/tcp', 8080),
+ ('80', None),
+ ('8080-8090:80', None),
+])
+def test_short_port_syntax_parsing(spec, expected):
+ assert preflight._published_from_short(spec) == expected
+
+
+def test_legacy_ports_string_is_understood(app, monkeypatch):
+ """Older compose ps output carries `Ports` as a string, not `Publishers`."""
+ monkeypatch.setattr(DockerService, 'compose_ps', classmethod(
+ lambda cls, path, compose_file=None: [
+ {'Ports': '0.0.0.0:8080->80/tcp, :::8080->80/tcp'},
+ {'Ports': '127.0.0.1:5432->5432/tcp'},
+ ]))
+ assert preflight.published_host_ports('/srv/x') == {8080, 5432}
+
+
+# ── path 3: GitDeployService._standard_restart (webhook default) ─────────────
+
+def test_standard_restart_never_stops_when_the_preflight_fails(app, monkeypatch, tmp_path):
+ from app.services.git_deploy_service import GitDeployService
+
+ calls = _stub_compose(monkeypatch, valid=False)
+ application = _app_row(tmp_path, name='git-app')
+
+ result = GitDeployService._standard_restart(application)
+
+ assert result['success'] is False
+ assert 'DOWN' not in calls, 'compose_down ran despite a failed preflight'
+ assert 'UP' not in calls
+ assert result['preflight']['findings'][0]['kind'] == 'compose_invalid'
+
+
+def test_standard_restart_builds_before_it_stops_then_deploys(app, monkeypatch, tmp_path):
+ from app.services.git_deploy_service import GitDeployService
+
+ calls = _stub_compose(monkeypatch,
+ config={'services': {'api': {'build': '.'}}})
+ application = _app_row(tmp_path, name='git-app-ok')
+
+ result = GitDeployService._standard_restart(application)
+
+ assert result['success'] is True
+ assert calls.index('build') < calls.index('DOWN') < calls.index('UP')
+
+
+# ── path 2: TemplateService.update_app ───────────────────────────────────────
+
+def _install_template_app(monkeypatch, tmp_path, *, compose_body='services: {web: {image: old}}'):
+ from app.services.template_service import TemplateService
+
+ application = _app_row(tmp_path, name='tmpl-app')
+ compose_path = tmp_path / 'docker-compose.yml'
+ compose_path.write_text(compose_body)
+ (tmp_path / '.serverkit-template.json').write_text(
+ '{"template_id": "ghost", "template_version": "1.0", "variables": {}}')
+
+ monkeypatch.setattr(TemplateService, 'get_config', classmethod(
+ lambda cls: {'installed': {str(application.id): {'template_id': 'ghost'}}}))
+ monkeypatch.setattr(TemplateService, 'save_config', classmethod(lambda cls, cfg: None))
+ monkeypatch.setattr(TemplateService, 'get_template', classmethod(
+ lambda cls, tid: {'success': True,
+ 'template': {'name': 'ghost', 'version': '2.0', 'variables': {}}}))
+ monkeypatch.setattr(TemplateService, 'generate_compose', classmethod(
+ lambda cls, template, variables: 'services: {web: {image: new}}'))
+ return application, compose_path
+
+
+def test_template_update_leaves_the_live_stack_untouched_when_validation_fails(
+ app, monkeypatch, tmp_path):
+ from app.services.template_service import TemplateService
+
+ calls = _stub_compose(monkeypatch, valid=False)
+ application, compose_path = _install_template_app(monkeypatch, tmp_path)
+ before = compose_path.read_bytes()
+
+ result = TemplateService.update_app(application.id)
+
+ assert result['success'] is False
+ assert 'DOWN' not in calls, 'compose_down ran before the new compose was validated'
+ assert compose_path.read_bytes() == before, 'the live compose file was rewritten'
+ assert result['preflight']['findings'][0]['kind'] == 'compose_invalid'
+ # The candidate file the preflight validated is cleaned up either way.
+ assert not os.path.exists(tmp_path / '.serverkit-preflight-compose.yml')
+
+
+def test_template_update_validates_the_new_compose_before_stopping(app, monkeypatch, tmp_path):
+ from app.services.template_service import TemplateService
+
+ calls = _stub_compose(monkeypatch)
+ seen = {}
+
+ real_validate = DockerService.validate_compose_file
+
+ def spy_validate(cls, path, compose_file=None):
+ # The candidate must exist on disk at validation time and hold the NEW
+ # compose, while docker-compose.yml still holds the old one.
+ seen['candidate'] = (open(os.path.join(path, compose_file)).read()
+ if compose_file else None)
+ seen['live'] = open(os.path.join(path, 'docker-compose.yml')).read()
+ return real_validate(path, compose_file)
+
+ monkeypatch.setattr(DockerService, 'validate_compose_file', classmethod(spy_validate))
+ application, compose_path = _install_template_app(monkeypatch, tmp_path)
+
+ result = TemplateService.update_app(application.id)
+
+ assert result['success'] is True, result
+ assert seen['candidate'] == 'services: {web: {image: new}}'
+ assert seen['live'] == 'services: {web: {image: old}}'
+ assert calls.index('validate') < calls.index('DOWN') < calls.index('UP')
+ assert compose_path.read_text() == 'services: {web: {image: new}}'
+ assert not os.path.exists(tmp_path / '.serverkit-preflight-compose.yml')
+
+
+# ── path 1: DeploymentService._deploy_docker ─────────────────────────────────
+
+def _stub_container_deploy(monkeypatch, *, pull_ok=True):
+ from app.services.container_registry_service import ContainerRegistryService
+ from app.services.env_service import EnvService
+
+ calls = []
+ registry = types.SimpleNamespace(id=1, name='ghcr')
+
+ monkeypatch.setattr(ContainerRegistryService, 'for_app',
+ staticmethod(lambda application: registry))
+ monkeypatch.setattr(EnvService, 'get_effective_env', staticmethod(lambda *a, **k: {}))
+ monkeypatch.setattr(DockerService, 'pull_image', staticmethod(
+ lambda image, tag=None, registry=None: (
+ calls.append('pull') or
+ ({'success': True} if pull_ok
+ else {'success': False, 'error': 'registry unreachable'}))))
+ monkeypatch.setattr(DockerService, 'get_container',
+ staticmethod(lambda name: {'Id': 'old'}))
+ monkeypatch.setattr(DockerService, 'stop_container', staticmethod(
+ lambda name, timeout=10: calls.append('STOP') or {'success': True}))
+ monkeypatch.setattr(DockerService, 'remove_container', staticmethod(
+ lambda name, force=False, volumes=False: calls.append('REMOVE') or {'success': True}))
+ monkeypatch.setattr(DockerService, 'run_container', staticmethod(
+ lambda **kw: calls.append('RUN') or {'success': True, 'container_id': 'new'}))
+ return calls
+
+
+def test_deploy_docker_keeps_the_old_container_when_the_image_cannot_be_pulled(
+ app, monkeypatch, tmp_path):
+ """The pull used to sit BELOW stop+remove: a registry hiccup left the app
+ with no container at all."""
+ from app.services.deployment_service import DeploymentService
+
+ calls = _stub_container_deploy(monkeypatch, pull_ok=False)
+ application = _app_row(tmp_path, name='reg-app', port=9123)
+ deployment = types.SimpleNamespace(image_tag='ghcr.io/acme/app:v2')
+
+ result = DeploymentService._deploy_docker(application, deployment)
+
+ assert result['success'] is False
+ assert 'registry unreachable' in result['error']
+ assert 'STOP' not in calls and 'REMOVE' not in calls, \
+ 'the live container was destroyed before the image was resolved'
+ assert 'RUN' not in calls
+ assert result['preflight']['findings'][0]['kind'] == 'image_unresolved'
+
+
+def test_deploy_docker_pulls_before_it_stops(app, monkeypatch, tmp_path):
+ from app.services.deployment_service import DeploymentService
+
+ calls = _stub_container_deploy(monkeypatch, pull_ok=True)
+ application = _app_row(tmp_path, name='reg-app-ok', port=9124)
+ deployment = types.SimpleNamespace(image_tag='ghcr.io/acme/app:v2')
+
+ result = DeploymentService._deploy_docker(application, deployment)
+
+ assert result['success'] is True
+ assert calls == ['pull', 'STOP', 'REMOVE', 'RUN']