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.

fix(apps): start/stop/restart a docker app that has no compose project

Juan Denis503dedd95cc2
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index a97b54d7..89ddb13f 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -137,6 +137,36 @@ def _assert_managed_app_path(app_name):
raise ValueError('Invalid application path')
+def _has_local_compose_project(app):
+ """True when a local app really has a compose project on disk.
+
+ ``app_type == 'docker'`` is not the same as "compose-managed". A build-pack
+ app is deployed by building an image and running a single container
+ (``DeploymentService._deploy_docker``); nothing in that path ever writes a
+ compose file, so ``compose_file`` stays NULL. Handing such a directory to
+ ``docker compose`` fails with "no configuration file provided: not found",
+ which is what start/stop/restart did for every build-pack app.
+ """
+ if app.server_id or not app.root_path:
+ return False
+ if app.compose_file:
+ return os.path.isfile(os.path.join(app.root_path, app.compose_file))
+ return any(
+ os.path.isfile(os.path.join(app.root_path, name))
+ for name in ('docker-compose.yml', 'docker-compose.yaml',
+ 'compose.yml', 'compose.yaml')
+ )
+
+
+def _app_container_name(app):
+ """The single container a build-pack deploy creates for this app.
+
+ Must match ``DeploymentService._deploy_docker``, which names it
+ ``serverkit-app-<id>``.
+ """
+ return f'serverkit-app-{app.id}'
+
+
def _ensure_local_image_compose(app):
"""Materialize a compose project for a local docker app that carries a
``docker_image`` but has no source on disk yet.
@@ -1525,7 +1555,7 @@ def start_app(app_id):
detach=True,
user_id=current_user_id
)
- else:
+ elif _has_local_compose_project(app):
# Authenticate a bound private registry before compose pulls the
# image; best-effort, always logs back out. No-op without registry_id.
_registry = ContainerRegistryService.login_for_app(app)
@@ -1537,6 +1567,14 @@ def start_app(app_id):
)
finally:
ContainerRegistryService.logout_for_app(_registry)
+ else:
+ # Build-pack app: one container, created by the deploy.
+ container = _app_container_name(app)
+ if not DockerService.get_container(container):
+ return jsonify({'error': 'This application has not been deployed yet. '
+ 'Run a deploy to build its image and create '
+ 'the container.'}), 400
+ result = DockerService.start_container(container)
if not result.get('success') or _agent_result_failed(result):
return jsonify({'error': _agent_result_error(result, 'Failed to start containers')}), 400
@@ -1961,11 +1999,17 @@ def stop_app(app_id):
_compose_target(app),
user_id=current_user_id
)
- else:
+ elif _has_local_compose_project(app):
result = DockerService.compose_down(
app.root_path,
compose_file=_local_compose_file(app)
)
+ else:
+ # Build-pack app. A container that no longer exists is already
+ # stopped -- reporting that as a failure would strand the app.
+ container = _app_container_name(app)
+ result = ({'success': True} if not DockerService.get_container(container)
+ else DockerService.stop_container(container))
if not result.get('success') or _agent_result_failed(result):
return jsonify({'error': _agent_result_error(result, 'Failed to stop containers')}), 400
@@ -2000,11 +2044,18 @@ def restart_app(app_id):
_compose_target(app),
user_id=current_user_id
)
- else:
+ elif _has_local_compose_project(app):
result = DockerService.compose_restart(
app.root_path,
compose_file=_local_compose_file(app)
)
+ else:
+ container = _app_container_name(app)
+ if not DockerService.get_container(container):
+ return jsonify({'error': 'This application has not been deployed yet. '
+ 'Run a deploy to build its image and create '
+ 'the container.'}), 400
+ result = DockerService.restart_container(container)
if not result.get('success') or _agent_result_failed(result):
return jsonify({'error': _agent_result_error(result, 'Failed to restart containers')}), 400
diff --git a/backend/tests/test_app_lifecycle_noncompose.py b/backend/tests/test_app_lifecycle_noncompose.py
new file mode 100644
index 00000000..1a8eb653
--- /dev/null
+++ b/backend/tests/test_app_lifecycle_noncompose.py
@@ -0,0 +1,121 @@
+"""Start/stop/restart for a docker app that has no compose project.
+
+``app_type == 'docker'`` is not the same as "compose-managed". A build-pack
+app is deployed by building an image and running a single container
+(``DeploymentService._deploy_docker`` names it ``serverkit-app-<id>``), and
+nothing in that path writes a compose file. start/stop/restart nevertheless
+called ``docker compose`` for every docker app, so every build-pack app failed
+with ``no configuration file provided: not found`` and could never be started
+from the panel.
+
+Proving points:
+- the compose-project probe is about files on disk, not app_type
+- start/restart drive the container, and never touch compose, when there is
+ no compose project
+- start/restart on an app that was never deployed explain that, rather than
+ surfacing a docker error
+- stop treats an already-gone container as stopped rather than as a failure
+"""
+from unittest.mock import patch
+
+import pytest
+
+from app import db
+from app.api.apps import _has_local_compose_project
+from app.models import Application, User
+from factories import headers_for, make_user
+
+
+def owner(app, db_session):
+ return make_user(db_session, role='admin', username='lifecycle-owner')
+
+
+def buildpack_app(app, owner, tmp_path):
+ """A build-pack app: source on disk, no compose file anywhere."""
+ application = Application(name='buildpack-app', app_type='docker',
+ status='stopped', root_path=str(tmp_path),
+ buildpack_type='nixpacks', port=4173,
+ user_id=owner.id)
+ db.session.add(application)
+ db.session.commit()
+ return application
+
+
+# ── the probe ────────────────────────────────────────────────────────────────
+
+def test_docker_app_type_alone_is_not_a_compose_project(buildpack_app):
+ assert _has_local_compose_project(buildpack_app) is False
+
+
+def test_a_compose_file_on_disk_is_a_compose_project(buildpack_app, tmp_path):
+ (tmp_path / 'docker-compose.yml').write_text('services: {}\n', encoding='utf-8')
+ assert _has_local_compose_project(buildpack_app) is True
+
+
+# ── start ────────────────────────────────────────────────────────────────────
+
+def test_start_drives_the_container_and_never_compose(client, buildpack_app, owner):
+ with patch('app.api.apps.DockerService.get_container', return_value={'Id': 'abc'}), \
+ patch('app.api.apps.DockerService.start_container',
+ return_value={'success': True}) as start, \
+ patch('app.api.apps.DockerService.compose_up') as compose:
+ response = client.post(f'/api/v1/apps/{buildpack_app.id}/start',
+ headers=headers_for(owner))
+
+ assert response.status_code == 200
+ start.assert_called_once_with(f'serverkit-app-{buildpack_app.id}')
+ compose.assert_not_called()
+
+
+def test_start_before_any_deploy_says_so(client, buildpack_app, owner):
+ with patch('app.api.apps.DockerService.get_container', return_value=None), \
+ patch('app.api.apps.DockerService.compose_up') as compose:
+ response = client.post(f'/api/v1/apps/{buildpack_app.id}/start',
+ headers=headers_for(owner))
+
+ assert response.status_code == 400
+ assert 'not been deployed' in response.get_json()['error']
+ compose.assert_not_called()
+
+
+# ── restart ──────────────────────────────────────────────────────────────────
+
+def test_restart_drives_the_container_and_never_compose(client, buildpack_app, owner):
+ with patch('app.api.apps.DockerService.get_container', return_value={'Id': 'abc'}), \
+ patch('app.api.apps.DockerService.restart_container',
+ return_value={'success': True}) as restart, \
+ patch('app.api.apps.DockerService.compose_restart') as compose:
+ response = client.post(f'/api/v1/apps/{buildpack_app.id}/restart',
+ headers=headers_for(owner))
+
+ assert response.status_code == 200
+ restart.assert_called_once_with(f'serverkit-app-{buildpack_app.id}')
+ compose.assert_not_called()
+
+
+# ── stop ─────────────────────────────────────────────────────────────────────
+
+def test_stop_of_a_vanished_container_is_not_a_failure(client, buildpack_app, owner):
+ with patch('app.api.apps.DockerService.get_container', return_value=None), \
+ patch('app.api.apps.DockerService.compose_down') as compose:
+ response = client.post(f'/api/v1/apps/{buildpack_app.id}/stop',
+ headers=headers_for(owner))
+
+ assert response.status_code == 200
+ assert Application.query.get(buildpack_app.id).status == 'stopped'
+ compose.assert_not_called()
+
+
+def test_stop_drives_the_container_when_it_exists(client, buildpack_app, owner):
+ with patch('app.api.apps.DockerService.get_container', return_value={'Id': 'abc'}), \
+ patch('app.api.apps.DockerService.stop_container',
+ return_value={'success': True}) as stop, \
+ patch('app.api.apps.DockerService.compose_down') as compose:
+ response = client.post(f'/api/v1/apps/{buildpack_app.id}/stop',
+ headers=headers_for(owner))
+
+ assert response.status_code == 200
+ stop.assert_called_once_with(f'serverkit-app-{buildpack_app.id}')
+ compose.assert_not_called()
diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.md
index 4f983e3e..826a452c 100644
--- a/docs/MIGRATION_INVENTORY.md
+++ b/docs/MIGRATION_INVENTORY.md
@@ -16,7 +16,7 @@ debt. Regenerate with `python scripts/generate-migration-inventory.py`.
| Routes on bare @jwt_required() | auth_required() / role decorators | 608 | 608 | REGISTERED EXCEPTION: JWT-only is the deliberate default; conversion grants API-key access and happens per route, on decision |
| HTTP statuses chosen by sniffing error text | typed errors from app.exceptions | 0 | 0 | INVARIANT at 0 - migration completed 2026-08-19 |
| API crashes swallowed without recording | app.error_reporting | 0 | 0 | INVARIANT at 0 |
-| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 1142 | 1150 | migrate when touched; new endpoints raise |
+| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 1144 | 1150 | migrate when touched; new endpoints raise |
| Raw subprocess calls outside the runners | app/utils/system.py runners | 24 | 24 | migrate when touched |
| Controller-boundary violations (routes doing service work) | service layer extraction | 511 | 511 | migrate when touched (first-wave ratchet) |
| raw api.* calls in pages/ | E1: useServerQuery/useServerMutation | 405 | 405 | migrate when touched |