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
refactor(docker): route docker_service through the shared doors
Juan Denis7383820085b5
diff --git a/backend/app/services/docker_service.py b/backend/app/services/docker_service.pyindex 0b110d6c..8f214a0d 100644--- a/backend/app/services/docker_service.py+++ b/backend/app/services/docker_service.py@@ -7,6 +7,8 @@ import shleximport yamlfrom datetime import datetime+from app.utils.system import run_checked+logger = logging.getLogger(__name__)# Docker-style memory limit: a number plus a one-letter unit (bytes/kilo/mega/giga).@@ -23,15 +25,19 @@ class DockerService:"""Detect whether to use 'docker compose' (v2) or 'docker-compose' (v1)."""if cls._compose_cmd is not None:return cls._compose_cmd+ # run_checked, not cls.run: this probe decides what `run_compose` will+ # invoke, so it must not depend on anything compose-shaped itself.+ #+ # Still wrapped: run_checked converts the exec failures it knows about+ # into a result, but this probe runs before anything else in the+ # compose path and must not be able to raise into its caller at all —+ # dropping the guard here made a broken Popen surface as+ # `compose up` exit_code -1 instead of falling back to v1.try:- result = subprocess.run(- ['docker', 'compose', 'version'],- capture_output=True, text=True- )- if result.returncode == 0:+ if run_checked(['docker', 'compose', 'version'], timeout=None)['success']:cls._compose_cmd = ['docker', 'compose']return cls._compose_cmd- except Exception as e:+ except Exception as e: # noqa: BLE001logger.error(f"Failed to detect docker compose v2: {e}")# Fallback to docker-compose (v1)cls._compose_cmd = ['docker-compose']@@ -48,8 +54,11 @@ class DockerService:"""return cls._get_compose_cmd() == ['docker', 'compose']+ # Long docker operations (pull, build, compose up) are unbounded today.+ # `None` is passed explicitly at those call sites so the 60s default here+ # cannot silently cap a build; see COMPOSE/LONG notes below.@staticmethod- def run(args, timeout=60):+ def run(args, timeout=60, **kwargs):"""Run ``docker <args>``; one result shape for every caller (§G3).Three services kept private ``_docker()`` wrappers around this exact@@ -60,28 +69,15 @@ class DockerService:``result['success']`` against the third silently got a ``KeyError``rather than an answer.- Returns ``{'success': bool, 'output': str, 'error': str|None}``.- ``error`` distinguishes the three things that are not "the command said- no": docker absent, docker too slow, and everything else. A caller that+ Sits on ``run_checked`` (§G1) rather than re-implementing it, so the+ result shape and the error handling have exactly one definition:+ ``{'success', 'output', 'stderr', 'error', 'returncode'}``. ``error``+ distinguishes the three things that are not "the command said no":+ docker absent, docker too slow, and everything else. A caller thatcannot tell those apart is the caller that reports "not installed"because a probe timed out (§A)."""- try:- result = subprocess.run(['docker', *args], capture_output=True,- text=True, timeout=timeout)- except FileNotFoundError:- return {'success': False, 'output': '', 'error': 'Docker not found'}- except subprocess.TimeoutExpired:- return {'success': False, 'output': '',- 'error': f'Docker command timed out after {timeout}s'}- except Exception as e: # noqa: BLE001- return {'success': False, 'output': '', 'error': str(e)}- return {- 'success': result.returncode == 0,- 'output': result.stdout or '',- 'error': ((result.stderr or '').strip() or 'docker command failed')- if result.returncode != 0 else None,- }+ return run_checked(['docker', *args], timeout=timeout, **kwargs)@classmethoddef available(cls):@@ -100,31 +96,24 @@ class DockerService:@staticmethoddef is_docker_installed():"""Check if Docker is installed and running."""+ result = DockerService.run(['version', '--format', 'json'], timeout=None)+ if not result['success']:+ return {'installed': False, 'error': result['error']}try:- result = subprocess.run(- ['docker', 'version', '--format', 'json'],- capture_output=True, text=True- )- if result.returncode == 0:- return {'installed': True, 'info': json.loads(result.stdout)}- return {'installed': False, 'error': result.stderr}- except FileNotFoundError:- return {'installed': False, 'error': 'Docker not found'}- except Exception as e:- return {'installed': False, 'error': str(e)}+ return {'installed': True, 'info': json.loads(result['output'])}+ except ValueError as e:+ return {'installed': False, 'error': f'unreadable docker version output: {e}'}@staticmethoddef get_docker_info():"""Get Docker system information."""- try:- result = subprocess.run(- ['docker', 'info', '--format', '{{json .}}'],- capture_output=True, text=True- )- if result.returncode == 0:- return json.loads(result.stdout)+ result = DockerService.run(['info', '--format', '{{json .}}'], timeout=None)+ if not result['success']:+ logger.error('Failed to get Docker info: %s', result['error'])return None- except Exception as e:+ try:+ return json.loads(result['output'])+ except ValueError as e:logger.error(f"Failed to get Docker info: {e}")return None@@ -165,16 +154,16 @@ class DockerService:def list_containers(all_containers=True):"""List Docker containers."""try:- cmd = ['docker', 'ps', '--format', '{{json .}}']+ args = ['ps', '--format', '{{json .}}']if all_containers:- cmd.insert(2, '-a')+ args.insert(1, '-a')- result = subprocess.run(cmd, capture_output=True, text=True)- if result.returncode != 0:+ result = DockerService.run(args, timeout=None)+ if not result['success']:return []containers = []- for line in result.stdout.strip().split('\n'):+ for line in result['output'].strip().split('\n'):if line:container = json.loads(line)name = container.get('Names')@@ -236,21 +225,17 @@ class DockerService:"""keys = [k for k, _ in cls._PS_LABEL_FIELDS]fmt = '\t'.join(tpl for _, tpl in cls._PS_LABEL_FIELDS)- cmd = ['docker', 'ps', '--no-trunc', '--format', fmt]+ args = ['ps', '--no-trunc', '--format', fmt]if all_containers:- cmd.insert(2, '-a')+ args.insert(1, '-a')- try:- result = subprocess.run(cmd, capture_output=True, text=True)- if result.returncode != 0:- logger.warning('docker ps (bulk) failed: %s', result.stderr.strip())- return []- except Exception as e:- logger.error(f"Failed to bulk-list containers: {e}")+ result = cls.run(args, timeout=None)+ if not result['success']:+ logger.warning('docker ps (bulk) failed: %s', result['error'])return []containers = []- for line in (result.stdout or '').splitlines():+ for line in result['output'].splitlines():if not line.strip():continueparts = line.split('\t')@@ -269,26 +254,22 @@ class DockerService:@staticmethoddef get_container(container_id):"""Get detailed container information."""- try:- result = subprocess.run(- ['docker', 'inspect', container_id],- capture_output=True, text=True- )- if result.returncode == 0:- data = json.loads(result.stdout)- if data:- return data[0]+ result = DockerService.run(['inspect', container_id], timeout=None)+ if not result['success']:return None- except Exception as e:+ try:+ data = json.loads(result['output'])+ except ValueError as e:logger.error(f"Failed to inspect container {container_id}: {e}")return None+ return data[0] if data else None@staticmethoddef create_container(image, name=None, ports=None, volumes=None, env=None,network=None, restart_policy='unless-stopped', command=None):"""Create a new container."""try:- cmd = ['docker', 'create']+ cmd = ['create']if name:cmd.extend(['--name', name])@@ -316,12 +297,11 @@ class DockerService:if command:cmd.extend(shlex.split(command))- result = subprocess.run(cmd, capture_output=True, text=True)-- if result.returncode == 0:- container_id = result.stdout.strip()- return {'success': True, 'container_id': container_id}- return {'success': False, 'error': result.stderr}+ # LONG: `docker create`/`run` pulls the image when it is absent.+ result = DockerService.run(cmd, timeout=None)+ if result['success']:+ return {'success': True, 'container_id': result['output'].strip()}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -330,7 +310,7 @@ class DockerService:network=None, restart_policy='unless-stopped', command=None, detach=True):"""Run a new container (create and start)."""try:- cmd = ['docker', 'run']+ cmd = ['run']if detach:cmd.append('-d')@@ -361,12 +341,11 @@ class DockerService:if command:cmd.extend(shlex.split(command))- result = subprocess.run(cmd, capture_output=True, text=True)-- if result.returncode == 0:- container_id = result.stdout.strip()- return {'success': True, 'container_id': container_id}- return {'success': False, 'error': result.stderr}+ # LONG: `docker create`/`run` pulls the image when it is absent.+ result = DockerService.run(cmd, timeout=None)+ if result['success']:+ return {'success': True, 'container_id': result['output'].strip()}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -374,13 +353,10 @@ class DockerService:def start_container(container_id):"""Start a container."""try:- result = subprocess.run(- ['docker', 'start', container_id],- capture_output=True, text=True- )- if result.returncode == 0:+ result = DockerService.run(['start', container_id], timeout=None)+ if result['success']:return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -388,17 +364,15 @@ class DockerService:def stop_container(container_id, timeout=10):"""Stop a container."""try:- result = subprocess.run(- ['docker', 'stop', '-t', str(timeout), container_id],- capture_output=True, text=True- )- if result.returncode == 0:+ result = DockerService.run(['stop', '-t', str(timeout), container_id],+ timeout=None)+ if result['success']:# The panel emits the `app.stopped` event via the audit trail# (AuditService.log('app.stop') -> EventService.emit_for_audit),# so this low-level helper no longer emits its own event -- doing# so would double-fire it for Automations triggers (plan 45 Ph4).return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -406,13 +380,11 @@ class DockerService:def restart_container(container_id, timeout=10):"""Restart a container."""try:- result = subprocess.run(- ['docker', 'restart', '-t', str(timeout), container_id],- capture_output=True, text=True- )- if result.returncode == 0:+ result = DockerService.run(['restart', '-t', str(timeout), container_id],+ timeout=None)+ if result['success']:return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -420,17 +392,17 @@ class DockerService:def remove_container(container_id, force=False, volumes=False):"""Remove a container."""try:- cmd = ['docker', 'rm']+ cmd = ['rm']if force:cmd.append('-f')if volumes:cmd.append('-v')cmd.append(container_id)- result = subprocess.run(cmd, capture_output=True, text=True)- if result.returncode == 0:+ result = DockerService.run(cmd, timeout=None)+ if result['success']:return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -438,7 +410,7 @@ class DockerService:def get_container_logs(container_id, tail=100, since=None, timestamps=True):"""Get container logs."""try:- cmd = ['docker', 'logs']+ cmd = ['logs']if tail:cmd.extend(['--tail', str(tail)])if since:@@ -447,10 +419,11 @@ class DockerService:cmd.append('-t')cmd.append(container_id)- result = subprocess.run(cmd, capture_output=True, text=True)- # Docker logs go to both stdout and stderr- logs = result.stdout + result.stderr- return {'success': True, 'logs': logs}+ # merge_stderr, not stdout + stderr: a container writes its log to+ # both streams and concatenating them loses the interleaving, so+ # the tail of a crash landed above the lines that led to it.+ result = DockerService.run(cmd, timeout=None, merge_stderr=True)+ return {'success': True, 'logs': result['output']}except Exception as e:return {'success': False, 'error': str(e)}@@ -686,12 +659,11 @@ class DockerService:def get_container_stats(container_id):"""Get container resource usage stats."""try:- result = subprocess.run(- ['docker', 'stats', '--no-stream', '--format', '{{json .}}', container_id],- capture_output=True, text=True- )- if result.returncode == 0 and result.stdout.strip():- return json.loads(result.stdout.strip())+ result = DockerService.run(+ ['stats', '--no-stream', '--format', '{{json .}}', container_id],+ timeout=None)+ if result['success'] and result['output'].strip():+ return json.loads(result['output'].strip())return Noneexcept Exception as e:logger.error(f"Failed to get stats for container {container_id}: {e}")@@ -708,16 +680,15 @@ class DockerService:if not cleaned_ids:return {}- result = subprocess.run(- ['docker', 'stats', '--no-stream', '--format', '{{json .}}', *cleaned_ids],- capture_output=True, text=True- )- if result.returncode != 0:- logger.error(f"Failed to get container stats: {result.stderr.strip()}")+ result = DockerService.run(+ ['stats', '--no-stream', '--format', '{{json .}}', *cleaned_ids],+ timeout=None)+ if not result['success']:+ logger.error(f"Failed to get container stats: {result['error']}")return {}stats_map = {}- for line in result.stdout.splitlines():+ for line in result['output'].splitlines():if not line.strip():continuestats = json.loads(line)@@ -733,7 +704,7 @@ class DockerService:def exec_command(container_id, command, interactive=False, tty=False):"""Execute a command in a running container."""try:- cmd = ['docker', 'exec']+ cmd = ['exec']if interactive:cmd.append('-i')if tty:@@ -741,15 +712,17 @@ class DockerService:cmd.append(container_id)cmd.extend(shlex.split(command))- result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)+ result = DockerService.run(cmd, timeout=60)+ if result['returncode'] is None:+ # The command never ran (no docker, timed out). Reporting a+ # return_code here would claim the container answered.+ return {'success': False, 'error': result['error']}return {- 'success': result.returncode == 0,- 'stdout': result.stdout,- 'stderr': result.stderr,- 'return_code': result.returncode+ 'success': result['success'],+ 'stdout': result['output'],+ 'stderr': result['stderr'],+ 'return_code': result['returncode'],}- except subprocess.TimeoutExpired:- return {'success': False, 'error': 'Command timed out'}except Exception as e:return {'success': False, 'error': str(e)}@@ -759,15 +732,13 @@ class DockerService:def list_images():"""List Docker images."""try:- result = subprocess.run(- ['docker', 'images', '--format', '{{json .}}'],- capture_output=True, text=True- )- if result.returncode != 0:+ result = DockerService.run(['images', '--format', '{{json .}}'],+ timeout=None)+ if not result['success']:return []images = []- for line in result.stdout.strip().split('\n'):+ for line in result['output'].strip().split('\n'):if line:image = json.loads(line)images.append({@@ -804,13 +775,12 @@ class DockerService:'error': f"Registry login failed: {login.get('error')}"}logged_in = True- result = subprocess.run(- ['docker', 'pull', full_name],- capture_output=True, text=True- )- if result.returncode == 0:- return {'success': True, 'output': result.stdout}- return {'success': False, 'error': result.stderr}+ # LONG: a pull is unbounded today and can legitimately run for+ # many minutes on a slow link.+ result = DockerService.run(['pull', full_name], timeout=None)+ if result['success']:+ return {'success': True, 'output': result['output']}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}finally:@@ -822,15 +792,15 @@ class DockerService:def remove_image(image_id, force=False):"""Remove an image."""try:- cmd = ['docker', 'rmi']+ cmd = ['rmi']if force:cmd.append('-f')cmd.append(image_id)- result = subprocess.run(cmd, capture_output=True, text=True)- if result.returncode == 0:+ result = DockerService.run(cmd, timeout=None)+ if result['success']:return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -838,17 +808,18 @@ class DockerService:def build_image(path, tag, dockerfile='Dockerfile', no_cache=False):"""Build an image from Dockerfile."""try:- cmd = ['docker', 'build', '-t', tag]+ cmd = ['build', '-t', tag]if dockerfile != 'Dockerfile':cmd.extend(['-f', dockerfile])if no_cache:cmd.append('--no-cache')cmd.append(path)- result = subprocess.run(cmd, capture_output=True, text=True)- if result.returncode == 0:- return {'success': True, 'output': result.stdout}- return {'success': False, 'error': result.stderr, 'output': result.stdout}+ # LONG: a build is unbounded today.+ result = DockerService.run(cmd, timeout=None)+ if result['success']:+ return {'success': True, 'output': result['output']}+ return {'success': False, 'error': result['error'], 'output': result['output']}except Exception as e:return {'success': False, 'error': str(e)}@@ -856,13 +827,10 @@ class DockerService:def tag_image(source, target):"""Tag an image."""try:- result = subprocess.run(- ['docker', 'tag', source, target],- capture_output=True, text=True- )- if result.returncode == 0:+ result = DockerService.run(['tag', source, target], timeout=None)+ if result['success']:return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -872,15 +840,13 @@ class DockerService:def list_networks():"""List Docker networks."""try:- result = subprocess.run(- ['docker', 'network', 'ls', '--format', '{{json .}}'],- capture_output=True, text=True- )- if result.returncode != 0:+ result = DockerService.run(['network', 'ls', '--format', '{{json .}}'],+ timeout=None)+ if not result['success']:return []networks = []- for line in result.stdout.strip().split('\n'):+ for line in result['output'].strip().split('\n'):if line:network = json.loads(line)networks.append({@@ -898,13 +864,11 @@ class DockerService:def create_network(name, driver='bridge'):"""Create a Docker network."""try:- result = subprocess.run(- ['docker', 'network', 'create', '--driver', driver, name],- capture_output=True, text=True- )- if result.returncode == 0:- return {'success': True, 'network_id': result.stdout.strip()}- return {'success': False, 'error': result.stderr}+ result = DockerService.run(['network', 'create', '--driver', driver, name],+ timeout=None)+ if result['success']:+ return {'success': True, 'network_id': result['output'].strip()}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -914,14 +878,8 @@ class DockerService:The shared external ``serverkit`` network lets manifest-generated appprojects resolve each other by container name (fromService.host)."""- try:- inspect = subprocess.run(- ['docker', 'network', 'inspect', name],- capture_output=True, text=True)- if inspect.returncode == 0:- return {'success': True, 'existed': True}- except Exception as e:- return {'success': False, 'error': str(e)}+ if DockerService.run(['network', 'inspect', name], timeout=None)['success']:+ return {'success': True, 'existed': True}created = DockerService.create_network(name, driver=driver)created['existed'] = Falsereturn created@@ -930,13 +888,10 @@ class DockerService:def remove_network(network_id):"""Remove a Docker network."""try:- result = subprocess.run(- ['docker', 'network', 'rm', network_id],- capture_output=True, text=True- )- if result.returncode == 0:+ result = DockerService.run(['network', 'rm', network_id], timeout=None)+ if result['success']:return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -946,15 +901,13 @@ class DockerService:def list_volumes():"""List Docker volumes."""try:- result = subprocess.run(- ['docker', 'volume', 'ls', '--format', '{{json .}}'],- capture_output=True, text=True- )- if result.returncode != 0:+ result = DockerService.run(['volume', 'ls', '--format', '{{json .}}'],+ timeout=None)+ if not result['success']:return []volumes = []- for line in result.stdout.strip().split('\n'):+ for line in result['output'].strip().split('\n'):if line:volume = json.loads(line)volumes.append({@@ -971,13 +924,11 @@ class DockerService:def create_volume(name, driver='local'):"""Create a Docker volume."""try:- result = subprocess.run(- ['docker', 'volume', 'create', '--driver', driver, name],- capture_output=True, text=True- )- if result.returncode == 0:- return {'success': True, 'volume_name': result.stdout.strip()}- return {'success': False, 'error': result.stderr}+ result = DockerService.run(['volume', 'create', '--driver', driver, name],+ timeout=None)+ if result['success']:+ return {'success': True, 'volume_name': result['output'].strip()}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -985,15 +936,15 @@ class DockerService:def remove_volume(volume_name, force=False):"""Remove a Docker volume."""try:- cmd = ['docker', 'volume', 'rm']+ cmd = ['volume', 'rm']if force:cmd.append('-f')cmd.append(volume_name)- result = subprocess.run(cmd, capture_output=True, text=True)- if result.returncode == 0:+ result = DockerService.run(cmd, timeout=None)+ if result['success']:return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1001,13 +952,10 @@ class DockerService:def inspect_volume(name):"""Live state of a named volume: {'present', 'mountpoint', 'driver'}."""try:- result = subprocess.run(- ['docker', 'volume', 'inspect', name],- capture_output=True, text=True- )- if result.returncode != 0:+ result = DockerService.run(['volume', 'inspect', name], timeout=None)+ if not result['success']:return {'present': False, 'mountpoint': None, 'driver': None}- data = json.loads(result.stdout or '[]')+ data = json.loads(result['output'] or '[]')info = data[0] if data else {}return {'present': True, 'mountpoint': info.get('Mountpoint'),'driver': info.get('Driver')}@@ -1019,14 +967,14 @@ class DockerService:"""Names of containers referencing a volume. ``running_only`` limits it tocurrently-running containers (the guard for a safe wipe)."""try:- cmd = ['docker', 'ps']+ cmd = ['ps']if not running_only:cmd.append('-a')cmd += ['--filter', f'volume={name}', '--format', '{{.Names}}']- result = subprocess.run(cmd, capture_output=True, text=True)- if result.returncode != 0:+ result = DockerService.run(cmd, timeout=None)+ if not result['success']:return []- return [n for n in result.stdout.strip().split('\n') if n]+ return [n for n in result['output'].strip().split('\n') if n]except Exception:return []@@ -1064,16 +1012,30 @@ class DockerService:logger.debug('compose overlay command build failed for %s: %s', project_path, e)return cls._compose_base_cmd(compose_file)+ @classmethod+ def run_compose(cls, cmd, *, cwd=None, timeout=None):+ """Run an already-built compose argv; the shared result shape (§G1).++ Separate from :meth:`run` because the argv head is whatever+ ``_get_compose_cmd()`` resolved — ``docker compose`` (v2) or+ ``docker-compose`` (v1) — not a literal ``docker``.++ ``timeout=None`` by default, unlike :meth:`run`. Every compose call in+ this file is unbounded today, and ``compose up --build`` on a small VPS+ routinely runs longer than a minute; inheriting a 60s default here+ would turn working deploys into timeouts. Bounding them is a real+ improvement and a deliberate behaviour change, not a side effect of+ this collapse.+ """+ return run_checked(cmd, cwd=cwd, timeout=timeout)+@classmethoddef compose_list(cls):"""List Docker Compose projects known to the Docker CLI."""try:- result = subprocess.run(- cls._get_compose_cmd() + ['ls', '--format', 'json'],- capture_output=True, text=True- )- if result.returncode == 0 and result.stdout.strip():- output = result.stdout.strip()+ result = cls.run_compose(cls._get_compose_cmd() + ['ls', '--format', 'json'])+ if result['success'] and result['output'].strip():+ output = result['output'].strip()try:parsed = json.loads(output)if isinstance(parsed, list):@@ -1105,15 +1067,13 @@ class DockerService:def _compose_list_from_container_labels():"""Fallback for older compose binaries without `compose ls --format json`."""try:- result = subprocess.run(- ['docker', 'ps', '-a', '--format', '{{json .}}'],- capture_output=True, text=True- )- if result.returncode != 0:+ result = DockerService.run(['ps', '-a', '--format', '{{json .}}'],+ timeout=None)+ if not result['success']:return []projects = {}- for line in result.stdout.strip().split('\n'):+ for line in result['output'].strip().split('\n'):if not line:continuecontainer = json.loads(line)@@ -1170,13 +1130,10 @@ class DockerService:if build:cmd.append('--build')- 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}+ result = cls.run_compose(cmd, cwd=project_path)+ if result['success']:+ return {'success': True, 'output': result['output']}+ return {'success': False, 'error': result['error'], 'output': result['output']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1244,13 +1201,10 @@ class DockerService:if remove_orphans:cmd.append('--remove-orphans')- 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}+ result = cls.run_compose(cmd, cwd=project_path)+ if result['success']:+ return {'success': True, 'output': result['output']}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1266,14 +1220,12 @@ class DockerService:Returns a list of container dictionaries."""try:- result = subprocess.run(+ result = cls.run_compose(cls._compose_base_cmd(compose_file) + ['ps', '--format', 'json'],- cwd=project_path,- capture_output=True, text=True- )- if result.returncode == 0 and result.stdout.strip():+ cwd=project_path)+ if result['success'] and result['output'].strip():containers = []- for line in result.stdout.strip().split('\n'):+ for line in result['output'].strip().split('\n'):line = line.strip()# Skip empty lines and warning messages (e.g., "time=..." from docker)if not line or line.startswith('time=') or line.startswith('WARN'):@@ -1304,11 +1256,9 @@ class DockerService:if service:cmd.append(service)- result = subprocess.run(- cmd, cwd=project_path,- capture_output=True, text=True- )- return {'success': True, 'logs': result.stdout + result.stderr}+ result = run_checked(cmd, cwd=project_path, timeout=None,+ merge_stderr=True)+ return {'success': True, 'logs': result['output']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1320,13 +1270,10 @@ class DockerService:if service:cmd.append(service)- result = subprocess.run(- cmd, cwd=project_path,- capture_output=True, text=True- )- if result.returncode == 0:+ result = cls.run_compose(cmd, cwd=project_path)+ if result['success']:return {'success': True}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1338,13 +1285,10 @@ class DockerService: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}+ result = cls.run_compose(cmd, cwd=project_path)+ if result['success']:+ return {'success': True, 'output': result['output']}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1363,13 +1307,10 @@ class DockerService: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}+ result = cls.run_compose(cmd, cwd=project_path)+ if result['success']:+ return {'success': True, 'output': result['output']}+ return {'success': False, 'error': result['error'], 'output': result['output']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1377,11 +1318,8 @@ class DockerService: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+ return DockerService.run(['image', 'inspect', image_ref],+ timeout=None)['success']except Exception:return False@@ -1389,14 +1327,12 @@ class DockerService:def validate_compose_file(cls, project_path, compose_file=None):"""Validate a Docker Compose file."""try:- result = subprocess.run(+ result = cls.run_compose(cls._compose_base_cmd(compose_file) + ['config', '--quiet'],- cwd=project_path,- capture_output=True, text=True- )- if result.returncode == 0:+ cwd=project_path)+ if result['success']:return {'valid': True}- return {'valid': False, 'error': result.stderr}+ return {'valid': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1404,14 +1340,12 @@ class DockerService:def get_compose_config(cls, project_path, compose_file=None):"""Get parsed Docker Compose configuration."""try:- result = subprocess.run(+ result = cls.run_compose(cls._compose_base_cmd(compose_file) + ['config'],- cwd=project_path,- capture_output=True, text=True- )- if result.returncode == 0:- return {'success': True, 'config': yaml.safe_load(result.stdout)}- return {'success': False, 'error': result.stderr}+ cwd=project_path)+ if result['success']:+ return {'success': True, 'config': yaml.safe_load(result['output'])}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1421,16 +1355,17 @@ class DockerService:def prune_system(all_unused=False, volumes=False):"""Remove unused Docker resources."""try:- cmd = ['docker', 'system', 'prune', '-f']+ cmd = ['system', 'prune', '-f']if all_unused:cmd.append('-a')if volumes:cmd.append('--volumes')- result = subprocess.run(cmd, capture_output=True, text=True)- if result.returncode == 0:- return {'success': True, 'output': result.stdout}- return {'success': False, 'error': result.stderr}+ # LONG: reclaiming a large layer cache is unbounded today.+ result = DockerService.run(cmd, timeout=None)+ if result['success']:+ return {'success': True, 'output': result['output']}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1438,15 +1373,13 @@ class DockerService:def get_disk_usage():"""Get Docker disk usage."""try:- result = subprocess.run(- ['docker', 'system', 'df', '--format', '{{json .}}'],- capture_output=True, text=True- )- if result.returncode != 0:+ result = DockerService.run(['system', 'df', '--format', '{{json .}}'],+ timeout=None)+ if not result['success']:return []usage = []- for line in result.stdout.strip().split('\n'):+ for line in result['output'].strip().split('\n'):if line:usage.append(json.loads(line))return usage@@ -1584,14 +1517,12 @@ class DockerService:Dict with 'success' boolean and 'ports' mapping"""try:- result = subprocess.run(- ['docker', 'inspect', '--format', '{{json .NetworkSettings.Ports}}', container_name],- capture_output=True, text=True- )- if result.returncode == 0:- ports = json.loads(result.stdout.strip())- return {'success': True, 'ports': ports}- return {'success': False, 'error': result.stderr}+ result = DockerService.run(+ ['inspect', '--format', '{{json .NetworkSettings.Ports}}', container_name],+ timeout=None)+ if result['success']:+ return {'success': True, 'ports': json.loads(result['output'].strip())}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}@@ -1606,12 +1537,11 @@ class DockerService:Dict with network settings including IP addresses and ports"""try:- result = subprocess.run(- ['docker', 'inspect', '--format', '{{json .NetworkSettings}}', container_name],- capture_output=True, text=True- )- if result.returncode == 0:- network_settings = json.loads(result.stdout.strip())+ result = DockerService.run(+ ['inspect', '--format', '{{json .NetworkSettings}}', container_name],+ timeout=None)+ if result['success']:+ network_settings = json.loads(result['output'].strip())return {'success': True,'ip_address': network_settings.get('IPAddress'),@@ -1619,6 +1549,6 @@ class DockerService:'networks': network_settings.get('Networks'),'gateway': network_settings.get('Gateway')}- return {'success': False, 'error': result.stderr}+ return {'success': False, 'error': result['error']}except Exception as e:return {'success': False, 'error': str(e)}diff --git a/backend/app/utils/system.py b/backend/app/utils/system.pyindex 177d5d76..9d944198 100644--- a/backend/app/utils/system.py+++ b/backend/app/utils/system.py@@ -147,7 +147,7 @@ def run_unprivileged(cmd: Union[List[str], str], *, timeout: int = 60,def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,timeout: Optional[int] = 60, input: Optional[str] = None,cwd: Optional[str] = None, env: Optional[dict] = None,- **kwargs) -> dict:+ merge_stderr: bool = False, **kwargs) -> dict:"""Run a command and get a result, not a ``CompletedProcess`` (plan 75 §G1).The result-shaped door. Around ``backend/app``'s raw ``subprocess`` calls@@ -160,7 +160,8 @@ def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,Returns::- {'success': bool, 'output': str, 'error': str|None, 'returncode': int|None}+ {'success': bool, 'output': str, 'stderr': str,+ 'error': str|None, 'returncode': int|None}``returncode`` is ``None`` when the command never ran, which is thedistinction the hand-rolled handlers keep losing: exit code 1 means the@@ -168,6 +169,19 @@ def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,A caller that renders "not installed" must check ``returncode is not None``first, and now it can.+ ``stderr`` is the raw stream; ``error`` is the verdict — a human-facing+ message, ``None`` on success. They are separate because plenty of commands+ write to stderr and still succeed (``docker exec``, ``git``), so folding+ the stream into the verdict would invent failures. Callers that show+ command output want ``stderr``; callers that report a problem want+ ``error``.++ ``merge_stderr=True`` interleaves stderr into ``output`` the way a terminal+ would (``stderr=STDOUT``). ``docker logs`` needs it — a container's stderr+ is part of its log, not an error about fetching the log — and hand-rolled+ ``result.stdout + result.stderr`` concatenation is not the same thing: it+ loses the ordering.+``privileged=True`` routes through :func:`run_privileged` — same sudo-vs-rootdecision, same argv[0] resolution, so no caller re-implements either.@@ -182,7 +196,12 @@ def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,kwargs['cwd'] = cwdif env is not None:kwargs['env'] = env- kwargs.setdefault('capture_output', True)+ if merge_stderr:+ # capture_output and an explicit stderr= are mutually exclusive.+ kwargs.setdefault('stdout', subprocess.PIPE)+ kwargs.setdefault('stderr', subprocess.STDOUT)+ else:+ kwargs.setdefault('capture_output', True)kwargs.setdefault('text', True)try:@@ -203,27 +222,34 @@ def run_checked(cmd: Union[List[str], str], *, privileged: bool = False,result = subprocess.run(resolved, timeout=timeout, **kwargs)except FileNotFoundError as exc:name = cmd[0] if isinstance(cmd, (list, tuple)) and cmd else cmd- return {'success': False, 'output': '', 'returncode': None,- 'error': f'{name} not found: {exc}'}+ return _never_ran(f'{name} not found: {exc}')except subprocess.TimeoutExpired:- return {'success': False, 'output': '', 'returncode': None,- 'error': f'timed out after {timeout}s'}+ return _never_ran(f'timed out after {timeout}s')except PermissionError as exc:- return {'success': False, 'output': '', 'returncode': None,- 'error': f'permission denied: {exc}'}+ return _never_ran(f'permission denied: {exc}')except OSError as exc:- return {'success': False, 'output': '', 'returncode': None,- 'error': str(exc)}+ return _never_ran(str(exc))+ stderr = result.stderr or ''return {'success': result.returncode == 0,'output': result.stdout or '',+ 'stderr': stderr,'returncode': result.returncode,- 'error': ((result.stderr or '').strip() or f'command failed (exit {result.returncode})')+ 'error': (stderr.strip() or f'command failed (exit {result.returncode})')if result.returncode != 0 else None,}+def _never_ran(error: str) -> dict:+ """The result shape for a command that never produced an exit code.++ ``returncode is None`` is the whole point — see :func:`run_checked`.+ """+ return {'success': False, 'output': '', 'stderr': '',+ 'returncode': None, 'error': error}++def write_privileged_file(path: str, content: str, *, append: bool = False,mode: Optional[str] = None,owner: Optional[str] = None) -> dict:diff --git a/backend/tests/BASELINE_COUNT b/backend/tests/BASELINE_COUNTindex 427dcc07..7193414d 100644--- a/backend/tests/BASELINE_COUNT+++ b/backend/tests/BASELINE_COUNT@@ -1 +1 @@-4081+4097diff --git a/backend/tests/RAW_SUBPROCESS_CEILING b/backend/tests/RAW_SUBPROCESS_CEILINGindex 8c9cf7e2..dba40afc 100644--- a/backend/tests/RAW_SUBPROCESS_CEILING+++ b/backend/tests/RAW_SUBPROCESS_CEILING@@ -1 +1 @@-258+211diff --git a/backend/tests/test_docker_protection.py b/backend/tests/test_docker_protection.pyindex 18f34942..3b67b02b 100644--- a/backend/tests/test_docker_protection.py+++ b/backend/tests/test_docker_protection.py@@ -39,23 +39,26 @@ class TestIsProtectedName:class TestListContainersAnnotation:- def _fake_ps(self, names):- lines = '\n'.join(+ @staticmethod+ def _ps_output(names):+ return '\n'.join('{"ID": "abc%d", "Names": "%s", "Image": "img", "Status": "Up", ''"State": "running", "Ports": "", "CreatedAt": "now", "Size": "0B"}'% (i, n)for i, n in enumerate(names))- class _Result:- returncode = 0- stdout = lines-- return _Result()-- def test_protected_flag_set_per_container(self):- with patch('subprocess.run', return_value=self._fake_ps(['serverkit-backend', 'nginx'])):- containers = DockerService.list_containers()+ def test_protected_flag_set_per_container(self, fake_subprocess):+ # Scripted through the shared stub kit (plan 75 §G7). The private fake+ # this replaced had only `returncode` and `stdout`; once list_containers+ # went through run_checked, reading `.stderr` off it raised+ # AttributeError, the caller's blanket except swallowed it, and the+ # test saw an empty container list instead of an error. A hand-rolled+ # CompletedProcess stand-in is only correct until something reads the+ # attribute it forgot.+ fake_subprocess.script(['docker', 'ps'],+ stdout=self._ps_output(['serverkit-backend', 'nginx']))+ containers = DockerService.list_containers()by_name = {c['name']: c for c in containers}assert by_name['serverkit-backend']['protected'] is Truediff --git a/backend/tests/test_docker_runner.py b/backend/tests/test_docker_runner.pyindex d6d02b3f..06182d3b 100644--- a/backend/tests/test_docker_runner.py+++ b/backend/tests/test_docker_runner.py@@ -21,8 +21,20 @@ from app.services.docker_service import DockerServiceclass TestResultShape:def test_success_carries_stdout(self, fake_subprocess):fake_subprocess.script(['docker', 'ps'], stdout='CONTAINER\n')- assert DockerService.run(['ps']) == {- 'success': True, 'output': 'CONTAINER\n', 'error': None}+ # DockerService.run sits on run_checked (§G1), so the shape is the+ # shared one — asserted by key here rather than by whole-dict equality,+ # which would have to be edited in every suite each time the door+ # gains a field.+ result = DockerService.run(['ps'])+ assert result['success'] is True+ assert result['output'] == 'CONTAINER\n'+ assert result['error'] is None+ assert result['returncode'] == 0++ def test_the_shape_is_run_checkeds(self, fake_subprocess):+ fake_subprocess.script(['docker', 'ps'])+ assert set(DockerService.run(['ps'])) == {+ 'success', 'output', 'stderr', 'error', 'returncode'}def test_failure_carries_stderr(self, fake_subprocess):fake_subprocess.script(['docker'], returncode=1, stderr='No such container\n')@@ -110,5 +122,98 @@ class TestTheWrappersDelegate:service = getattr(importlib.import_module(module_path), attr)fake_subprocess.script(['docker'], stdout='ok\n')result = service._docker(['ps'])- assert set(result) == {'success', 'output', 'error'}+ assert {'success', 'output', 'error'} <= set(result)assert result['success'] is True and result['output'] == 'ok\n'+++class TestLongOperationsAreNotCapped:+ """The one way this migration could have broken a real deployment.++ `run_checked` defaults to a 60s timeout. Every docker call in+ docker_service is unbounded today, and `compose up --build` on a small VPS+ routinely runs longer than a minute — inheriting the default would have+ turned working deploys into timeouts. These pin the opt-out at the sites+ where it matters.+ """++ def _timeout_for(self, fake, prefix):+ return fake.kwargs_for(prefix).get('timeout')++ def test_pull_image_is_unbounded(self, fake_subprocess):+ fake_subprocess.script(['docker', 'pull'])+ DockerService.pull_image('nginx', tag='latest')+ assert self._timeout_for(fake_subprocess, ['docker', 'pull']) is None++ def test_build_image_is_unbounded(self, fake_subprocess):+ fake_subprocess.script(['docker', 'build'])+ DockerService.build_image('/srv/app', 'app:latest')+ assert self._timeout_for(fake_subprocess, ['docker', 'build']) is None++ def test_run_container_is_unbounded(self, fake_subprocess):+ """`docker run` pulls the image when it is absent."""+ fake_subprocess.script(['docker', 'run'], stdout='cid\n')+ DockerService.run_container('nginx')+ assert self._timeout_for(fake_subprocess, ['docker', 'run']) is None++ def test_prune_is_unbounded(self, fake_subprocess):+ fake_subprocess.script(['docker', 'system'])+ DockerService.prune_system()+ assert self._timeout_for(fake_subprocess, ['docker', 'system']) is None++ def test_run_compose_defaults_to_unbounded(self, fake_subprocess):+ fake_subprocess.script(['docker-compose'])+ DockerService.run_compose(['docker-compose', 'up', '-d'], cwd='/srv/x')+ assert self._timeout_for(fake_subprocess, ['docker-compose']) is None++ def test_exec_command_keeps_its_60s_bound(self, fake_subprocess):+ """The one site that DID have a timeout keeps it."""+ fake_subprocess.script(['docker', 'exec'])+ DockerService.exec_command('c1', 'ls')+ assert self._timeout_for(fake_subprocess, ['docker', 'exec']) == 60+++class TestLogsKeepInterleaving:+ def test_container_logs_merge_stderr_rather_than_concatenating(self, fake_subprocess):+ """A container writes its log to both streams. `stdout + stderr`+ concatenation put the crash tail above the lines that led to it."""+ fake_subprocess.script(['docker', 'logs'], stdout='one\ntwo\n')+ result = DockerService.get_container_logs('c1')+ assert result['logs'] == 'one\ntwo\n'+ assert fake_subprocess.kwargs_for(['docker', 'logs'])['stderr'] is not None+++class TestExecCommandHonesty:+ def test_a_real_nonzero_exit_reports_the_code(self, fake_subprocess):+ fake_subprocess.script(['docker', 'exec'], returncode=2, stderr='nope')+ result = DockerService.exec_command('c1', 'false')+ assert result['success'] is False+ assert result['return_code'] == 2+ assert result['stderr'] == 'nope'++ def test_stderr_on_a_successful_exec_is_not_an_error(self, fake_subprocess):+ fake_subprocess.script(['docker', 'exec'], stdout='out', stderr='warn')+ result = DockerService.exec_command('c1', 'thing')+ assert result['success'] is True+ assert result['stdout'] == 'out' and result['stderr'] == 'warn'++ def test_a_command_that_never_ran_claims_no_return_code(self, fake_subprocess):+ """Reporting return_code here would say the container answered."""+ fake_subprocess.script(['docker'], raises=FileNotFoundError)+ result = DockerService.exec_command('c1', 'ls')+ assert result['success'] is False+ assert 'return_code' not in result+ assert result['error']+++class TestProbesStillFallBack:+ def test_compose_detection_never_raises_into_its_caller(self, fake_subprocess,+ monkeypatch):+ """Dropping this guard made a broken probe surface as `compose up`+ exit_code -1 instead of a v1 fallback — caught by test_deploy_console."""+ monkeypatch.setattr(DockerService, '_compose_cmd', None)++ def explode(argv, kwargs):+ raise RuntimeError('probe blew up')++ fake_subprocess.when(['docker'], explode)+ assert DockerService._get_compose_cmd() == ['docker-compose']diff --git a/backend/tests/test_utils_system.py b/backend/tests/test_utils_system.pyindex 7a07c68f..7c959937 100644--- a/backend/tests/test_utils_system.py+++ b/backend/tests/test_utils_system.py@@ -626,7 +626,48 @@ class TestRunChecked:def test_success_shape(self, mock_run):mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='hi\n', stderr='')assert run_checked(['echo', 'hi']) == {- 'success': True, 'output': 'hi\n', 'error': None, 'returncode': 0}+ 'success': True, 'output': 'hi\n', 'stderr': '',+ 'error': None, 'returncode': 0}++ @patch('app.utils.system.subprocess.run')+ def test_stderr_on_a_SUCCESSFUL_command_is_not_an_error(self, mock_run):+ """git, docker exec and friends write to stderr and still succeed.++ Folding the stream into the verdict would invent failures, so+ `stderr` (the stream) and `error` (the verdict) are separate keys.+ """+ mock_run.return_value = subprocess.CompletedProcess(+ [], 0, stdout='', stderr='Cloning into ...\n')+ result = run_checked(['git', 'clone', 'x'])+ assert result['success'] is True+ assert result['error'] is None+ assert result['stderr'] == 'Cloning into ...\n'++ @patch('app.utils.system.subprocess.run')+ def test_stderr_is_raw_while_error_is_stripped(self, mock_run):+ mock_run.return_value = subprocess.CompletedProcess([], 1, stdout='', stderr=' boom \n')+ result = run_checked(['false'])+ assert result['stderr'] == ' boom \n'+ assert result['error'] == 'boom'++ @patch('app.utils.system.subprocess.run')+ def test_merge_stderr_interleaves_into_output(self, mock_run):+ """`docker logs` needs it: a container's stderr is part of its log,+ not an error about fetching the log."""+ mock_run.return_value = subprocess.CompletedProcess([], 0, stdout='a\nb\n', stderr=None)+ result = run_checked(['docker', 'logs', 'x'], merge_stderr=True)+ assert result['output'] == 'a\nb\n'+ kwargs = mock_run.call_args[1]+ assert kwargs['stderr'] is subprocess.STDOUT+ assert 'capture_output' not in kwargs # mutually exclusive with stderr=++ def test_a_command_that_never_ran_still_has_every_key(self):+ """A caller destructuring the result must not KeyError on the failure+ path — that is how an exec failure becomes a 500 instead of a message."""+ with patch('app.utils.system.subprocess.run', side_effect=FileNotFoundError('x')), \+ patch('app.utils.system.shutil.which', return_value='/bin/x'):+ result = run_checked(['x'])+ assert set(result) == {'success', 'output', 'stderr', 'error', 'returncode'}@patch('app.utils.system.subprocess.run')def test_capture_and_text_are_applied_for_the_caller(self, mock_run):