ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat: queue preview automation and preserve cleanup ownership through app deletion
Juan Denisc0dbb921e1bb
diff --git a/backend/app/api/previews.py b/backend/app/api/previews.pyindex 08761d88..bbf07ff0 100644--- a/backend/app/api/previews.py+++ b/backend/app/api/previews.py@@ -13,6 +13,10 @@ from app.models.application_preview import ApplicationPreviewfrom app.services.preview_service import PreviewServicefrom app.api._access import require_appfrom app.api._request import json_object+from app.middleware.rbac import developer_required+from app.services.previews.requests import enqueue, validate_request+from app.services.previews.plan import PreviewError+from app.exceptions import ValidationErrorpreviews_bp = Blueprint('previews', __name__)@@ -44,7 +48,10 @@ def update_preview_settings(app_id):"""Enable/disable previews and set the domain template + TTL for an app."""app = require_app(app_id, write=True, conceal=True)data = json_object(optional=True)- result = PreviewService.enable_previews(app_id, data)+ try:+ result = PreviewService.enable_previews(app_id, data)+ except ValueError as exc:+ raise ValidationError(str(exc)) from excreturn jsonify(result), 200@@ -67,14 +74,12 @@ def redeploy_preview(app_id, preview_id):id=preview_id, application_id=app_id).first()if not preview:return jsonify({'error': 'Preview not found'}), 404- result = PreviewService.create_preview(app, {- 'pr_number': preview.pr_number,- 'branch': preview.branch,- 'pr_title': preview.pr_title,- 'commit_sha': preview.commit_sha,+ job = enqueue(app_id, {+ 'pr_number': preview.pr_number, 'branch': preview.branch,+ 'pr_title': preview.pr_title, 'commit_sha': preview.commit_sha,})- status = 400 if result.get('error') else 200- return jsonify(result), status+ return jsonify({'status': 'queued', 'job_id': job.id}), 202+@previews_bp.route('/<int:app_id>/previews/<int:preview_id>', methods=['DELETE'])@@ -86,6 +91,18 @@ def destroy_preview(app_id, preview_id):id=preview_id, application_id=app_id).first()if not preview:return jsonify({'error': 'Preview not found'}), 404- result = PreviewService.destroy_preview(preview_id)- status = 400 if result.get('error') else 200- return jsonify(result), status+ job = enqueue(app_id, {'pr_number': preview.pr_number}, action='destroy')+ return jsonify({'status': 'queued', 'job_id': job.id}), 202+++@previews_bp.route('/<int:app_id>/previews', methods=['POST'])+@developer_required+def create_preview(app_id):+ """Queue a pinned same-repository preview (also supports API-key CI callers)."""+ app = require_app(app_id, write=True, conceal=True)+ data = json_object()+ try:+ job = enqueue(app_id, validate_request(app, data))+ except (PreviewError, TypeError, ValueError) as exc:+ raise ValidationError(str(exc) or 'Invalid preview request') from exc+ return jsonify({'status': 'queued', 'job_id': job.id}), 202diff --git a/backend/app/services/application_restore.py b/backend/app/services/application_restore.pyindex a3e19edb..4252780d 100644--- a/backend/app/services/application_restore.py+++ b/backend/app/services/application_restore.py@@ -221,4 +221,6 @@ def suspend_application(app, user_id=None):app.soft_delete(user_id)app.status = 'stopped'db.session.commit()+ from app.services.previews.lifecycle import cleanup_application+ results['previews'] = cleanup_application(app.id)return resultsdiff --git a/backend/app/services/preview_service.py b/backend/app/services/preview_service.pyindex e90d7cfc..13ca10e4 100644--- a/backend/app/services/preview_service.py+++ b/backend/app/services/preview_service.py@@ -246,16 +246,16 @@ class PreviewService:# ------------------------------------------------------------------ #@classmethod- def create_preview(cls, app, pr_payload, request_payload=None):+ def create_preview(cls, app, pr_payload, request_payload=None, log_callback=None):from app.services.deploy_lock import deploy_lockwith deploy_lock(app.id, 'preview deploy'):from app.services.previews.requests import currentif request_payload and not current(request_payload):return {'skipped': True, 'reason': 'superseded'}- return cls._create_preview_locked(app, pr_payload)+ return cls._create_preview_locked(app, pr_payload, manual=not request_payload, log_callback=log_callback)@classmethod- def _create_preview_locked(cls, app, pr_payload):+ def _create_preview_locked(cls, app, pr_payload, manual=True, log_callback=None):"""Create (or update-in-place) a preview for a PR. Best-effort.Writes/updates an :class:`ApplicationPreview` row, renders the domain,@@ -290,6 +290,8 @@ class PreviewService:preview = ApplicationPreview(application_id=app.id, pr_number=pr_number)db.session.add(preview)+ if manual:+ preview.requested_action = 'create'preview.branch = branchpreview.pr_title = pr_titlepreview.commit_sha = commit_sha@@ -304,7 +306,7 @@ class PreviewService:db.session.commit()# Best-effort provisioning — degrade gracefully when unavailable.- provisioned = cls._provision(app, preview)+ provisioned = cls._provision(app, preview, log_callback=log_callback)if provisioned.get('unsupported'):preview.status = ApplicationPreview.STATUS_UNAVAILABLEelif provisioned.get('ok') and provisioned.get('container_ids'):@@ -326,7 +328,7 @@ class PreviewService:return {'error': str(exc)}@classmethod- def _provision(cls, app, preview):+ def _provision(cls, app, preview, log_callback=None):"""Best-effort real provisioning. Returns ``{'ok': bool, 'container_ids': [...]}``.WordPress delegates to its preview hook; generic runtimes have a separate@@ -350,7 +352,7 @@ class PreviewService:logger.info('WP preview provisioning unavailable: %s', exc)return {'ok': False, 'container_ids': []}from app.services.previews.provisioner import provision- return provision(app, preview, cls.get_settings(app.id))+ return provision(app, preview, cls.get_settings(app.id), log_callback=log_callback)except Exception as exc:logger.info('preview provisioning unavailable: %s', exc)return {'ok': False, 'container_ids': []}@@ -368,6 +370,11 @@ class PreviewService:return {'skipped': True, 'reason': 'superseded'}from app import dbdb.session.refresh(row)+ if not request_payload:+ import uuid+ row.request_token = uuid.uuid4().hex+ row.requested_action = 'destroy'+ db.session.commit()return cls._destroy_preview_locked(preview_id)@classmethod@@ -380,7 +387,7 @@ class PreviewService:preview = ApplicationPreview.query.get(preview_id)if not preview:return {'error': 'preview not found'}- if preview.status == ApplicationPreview.STATUS_DESTROYED:+ if preview.status == ApplicationPreview.STATUS_DESTROYED and not preview.get_runtime_state():return preview.to_dict()app = None@@ -453,20 +460,23 @@ class PreviewService:).all()plan = cls.reconcile(open_prs, active)- created = destroyed = updated = 0+ created = destroyed = updated = failed = 0for pr in plan['to_create']:- cls.create_preview(app, pr)- created += 1+ result = cls.create_preview(app, pr)+ created += result.get('status') == 'running'+ failed += result.get('status') != 'running'for pr in plan['to_update']:- cls.create_preview(app, pr) # idempotent update-in-place- updated += 1+ result = cls.create_preview(app, pr)+ updated += result.get('status') == 'running'+ failed += result.get('status') != 'running'for preview in plan['to_destroy']:pid = preview.get('id') if isinstance(preview, dict) else getattr(preview, 'id', None)- cls.destroy_preview(pid)- destroyed += 1+ result = cls.destroy_preview(pid)+ destroyed += result.get('status') == 'destroyed'+ failed += result.get('status') != 'destroyed'- return {'success': True, 'created': created,- 'updated': updated, 'destroyed': destroyed}+ return {'success': failed == 0, 'created': created,+ 'updated': updated, 'destroyed': destroyed, 'failed': failed}except Exception as exc:logger.warning('sync_previews failed for app %s: %s', application_id, exc)return {'error': str(exc)}@@ -480,8 +490,8 @@ class PreviewService:from app.services.source_connection_service import SourceConnectionServicefn = getattr(SourceConnectionService, 'list_open_pull_requests', None)if callable(fn):- prs = fn(app.id) or []- return prs if isinstance(prs, list) else []+ prs = fn(app.id)+ return prs if isinstance(prs, list) else Noneexcept Exception as exc:logger.debug('open-PR listing unavailable for app %s: %s', app.id, exc)return None@@ -517,8 +527,15 @@ class PreviewService:app = Application.query_active().filter_by(id=payload.get('application_id')).first()if not app:- return {'error': 'Service not found'}- result = cls.create_preview(app, payload.get('pr') or payload, request_payload=payload)+ return {'skipped': True, 'reason': 'application_deleted'}+ stream = None+ if getattr(job, 'id', None):+ from app.services.run_log_service import stream_for+ stream = stream_for(job)+ result = cls.create_preview(app, payload.get('pr') or payload, request_payload=payload,+ log_callback=(lambda line: stream.log('info', line)) if stream else None)+ if stream:+ stream.flush()if result.get('skipped'):return resultif result.get('error') or result.get('status') != 'running':@@ -539,8 +556,8 @@ class PreviewService:if payload.get('pr'):return cls._job_create(job)result = cls.sync_previews(payload.get('application_id'))- if result.get('error'):- raise RuntimeError(result['error'])+ if result.get('error') or result.get('failed'):+ raise RuntimeError(result.get('error') or 'Some preview operations failed')return result@classmethoddiff --git a/backend/app/services/previews/lifecycle.py b/backend/app/services/previews/lifecycle.pynew file mode 100644index 00000000..81a2f018--- /dev/null+++ b/backend/app/services/previews/lifecycle.py@@ -0,0 +1,14 @@+"""Application deletion must not orphan preview-owned host resources."""+from app.models.application_preview import ApplicationPreview+++def cleanup_application(app_id):+ from app.services.preview_service import PreviewService+ rows = ApplicationPreview.query.filter_by(application_id=app_id).all()+ failed = []+ for row in rows:+ if row.status != 'destroyed' or row.get_runtime_state():+ result = PreviewService.destroy_preview(row.id)+ if result.get('error'):+ failed.append(row.id)+ return {'success': not failed, 'failed_preview_ids': failed}diff --git a/backend/app/services/previews/provisioner.py b/backend/app/services/previews/provisioner.pyindex a74d905e..84d20e28 100644--- a/backend/app/services/previews/provisioner.py+++ b/backend/app/services/previews/provisioner.py@@ -26,7 +26,7 @@ def check_domain(preview):raise PreviewError('Preview domain is already configured in nginx.')-def provision(app, preview, settings):+def provision(app, preview, settings, log_callback=None):config = GitService.get_app_config(app.id)request_token = preview.request_tokentry:@@ -42,11 +42,15 @@ def provision(app, preview, settings):name = identity(preview.id, state['token'])state['source'] = Trueruntime.save(preview, state)+ if log_callback:+ log_callback('Preparing an isolated checkout at the requested commit.')source.prepare(app, preview, target, config['repo_url'])state['image'] = Trueruntime.save(preview, state)- source.build(app, preview, target, name + ':preview')- runtime.start(app, preview, state)+ source.build(app, preview, target, name + ':preview', log_callback=log_callback)+ if log_callback:+ log_callback('Starting preview and checking HTTP health before publishing.')+ runtime.start(app, preview, state, inherit_environment=bool(settings.inherit_environment))db.session.refresh(preview, ['request_token', 'requested_action'])db.session.refresh(app, ['deleted_at'])if app.deleted_at or preview.request_token != request_token or preview.requested_action == 'destroy':diff --git a/backend/app/services/previews/requests.py b/backend/app/services/previews/requests.pyindex 699f2bbd..72d0d39e 100644--- a/backend/app/services/previews/requests.py+++ b/backend/app/services/previews/requests.py@@ -38,3 +38,23 @@ def current(payload):return Falsedb.session.refresh(row, ['request_token'])return row.request_token == payload['request_token']+++def validate_request(app, data):+ from types import SimpleNamespace+ from app.services.preview_service import PreviewService+ from app.services.git_service import GitService+ from .plan import validate+ settings = PreviewService.get_settings(app.id)+ if not settings.enabled:+ raise PreviewError('Enable previews before deploying.')+ try:+ number = int(data.get('pr_number'))+ except (TypeError, ValueError):+ raise PreviewError('A positive PR number is required.')+ candidate = SimpleNamespace(pr_number=number, branch=data.get('branch'),+ commit_sha=data.get('commit_sha'),+ domain=PreviewService._domain_for(app, settings, number, data.get('branch')))+ validate(app, candidate, settings, GitService.get_app_config(app.id))+ return {'pr_number': number, 'branch': candidate.branch,+ 'commit_sha': candidate.commit_sha, 'pr_title': data.get('pr_title')}diff --git a/backend/app/services/previews/runtime.py b/backend/app/services/previews/runtime.pyindex cb5cdd15..64689a5c 100644--- a/backend/app/services/previews/runtime.py+++ b/backend/app/services/previews/runtime.py@@ -28,14 +28,13 @@ def inspect(kind, name):raise PreviewError('Cannot inspect preview resources; cleanup must be retried.')-def start(app, preview, state):+def start(app, preview, state, inherit_environment=False):name = identity(preview.id, state['token'])state['container'] = Truesave(preview, state) # intent before docker run, even if it partially failsenv = {'SERVERKIT_PREVIEW': 'true', 'SERVERKIT_PR_NUMBER': str(preview.pr_number),'SERVERKIT_PREVIEW_BRANCH': preview.branch}- from app.services.preview_service import PreviewService- if PreviewService.get_settings(app.id).inherit_environment:+ if inherit_environment:from app.services.env_service import EnvServiceentries, complete = EnvService._effective_entries(app)if not complete:diff --git a/backend/app/services/previews/source.py b/backend/app/services/previews/source.pyindex 305114ca..b7a5f70b 100644--- a/backend/app/services/previews/source.py+++ b/backend/app/services/previews/source.py@@ -26,9 +26,10 @@ def prepare(app, preview, target, repo_url):shutil.rmtree(target / '.git')-def build(app, preview, target, image):+def build(app, preview, target, image, log_callback=None):config = dict(BuildService.get_app_build_config(app.id) or {})config['app_path'] = str(target)+ config['dockerfile_path'] = config.get('dockerfile_path') or 'Dockerfile'method = config.get('build_method', 'auto')if method == 'auto':method = BuildService.detect_build_method(str(target))['build_method']@@ -43,7 +44,7 @@ def build(app, preview, target, image):config['build_args'] = {}config['env_vars'] = {}result = BuildService.build_from_config(- f'preview-{preview.id}', config, image_tag=image,+ f'preview-{preview.id}', config, image_tag=image, log_callback=log_callback,)if not result.get('success'):- raise PreviewError('Preview image build failed. See the preview build logs.')+ raise PreviewError('Preview image build failed. See the preview job logs.')diff --git a/backend/app/services/recycle_bin_service.py b/backend/app/services/recycle_bin_service.pyindex d6bbe37a..02749a9d 100644--- a/backend/app/services/recycle_bin_service.py+++ b/backend/app/services/recycle_bin_service.py@@ -162,6 +162,10 @@ def purge(kind, record_id):return False, PURGE_NOT_FOUNDif row.deleted_at is None:return False, 'record is not in the recycle bin'+ if kind == 'application':+ from app.services.previews.lifecycle import cleanup_application+ if not cleanup_application(row.id)['success']:+ return False, 'Preview cleanup is incomplete; retry purge after restoring host access.'warning = _run_purge_hook(entry, row)db.session.delete(row)db.session.commit()@@ -177,15 +181,21 @@ def purge_expired(retention_days=DEFAULT_RETENTION_DAYS):entry['model'].deleted_at.isnot(None),entry['model'].deleted_at < cutoff,).all()+ purged = 0for row in rows:# The retention sweep is the OTHER way a row reaches the end of its# life, so it owes the same cleanup an explicit purge does — without# it, a directory is reclaimed only when someone happens to click# Purge, and never for the 30-day expiry path.+ if kind == 'application':+ from app.services.previews.lifecycle import cleanup_application+ if not cleanup_application(row.id)['success']:+ continue_run_purge_hook(entry, row)db.session.delete(row)- if rows:- counts[kind] = len(rows)+ purged += 1+ if purged:+ counts[kind] = purgedif counts:db.session.commit()return countsdiff --git a/backend/tests/test_generic_previews.py b/backend/tests/test_generic_previews.pyindex cc40d21e..a91e3b99 100644--- a/backend/tests/test_generic_previews.py+++ b/backend/tests/test_generic_previews.py@@ -25,7 +25,7 @@ def host(app, monkeypatch, tmp_path):resources['calls'].append(('clone', str(path), url))path.mkdir()(path / 'Dockerfile').write_text('FROM scratch')- def build(parent, preview, path, image):+ def build(parent, preview, path, image, **kwargs):resources['calls'].append(('build', image))resources['images'].add(image)monkeypatch.setattr(source, 'prepare', prepare)@@ -192,8 +192,8 @@ def test_close_during_build_cleans_up_without_publishing(host, monkeypatch):parent, resources = hostmonkeypatch.setattr(JobService, 'enqueue', lambda *a, **kw: None)original = source.build- def build(*args):- original(*args)+ def build(*args, **kwargs):+ original(*args, **kwargs)enqueue(parent.id, PR, action='destroy')monkeypatch.setattr(source, 'build', build)result = PreviewService.create_preview(parent, PR)@@ -206,3 +206,165 @@ def test_cleanup_paths_cannot_escape(tmp_path):workspace(tmp_path, 1, '../escape')with pytest.raises(PreviewError):identity(-1, 'a' * 32)+++def test_failed_cleanup_blocks_purge_and_retention_sweep(host, monkeypatch):+ from datetime import datetime, timedelta+ from app.services import recycle_bin_service+ parent, resources = host+ result = PreviewService.create_preview(parent, PR)+ parent.deleted_at = datetime.utcnow() - timedelta(days=90)+ db.session.commit()+ monkeypatch.setattr(runtime.DockerService, 'remove_container', lambda *a, **kw: {'success': False})+ ok, reason = recycle_bin_service.purge('application', parent.id)+ assert not ok and 'Preview cleanup' in reason+ assert db.session.get(ApplicationPreview, result['id']).get_runtime_state()+ counts = recycle_bin_service.purge_expired()+ assert counts.get('application', 0) == 0+ assert resources['containers']+++def test_environment_inheritance_is_opt_in(host):+ from app.services.env_service import EnvService+ parent, resources = host+ EnvService.set_env_var(parent.id, 'DATABASE_URL', 'production-credential', is_secret=True)+ PreviewService.create_preview(parent, PR)+ run = [call[1] for call in resources['calls'] if call[0] == 'run'][-1]+ assert 'DATABASE_URL' not in run['env']+ PreviewService.enable_previews(parent.id, {'inherit_environment': True})+ PreviewService.create_preview(parent, PR)+ run = [call[1] for call in resources['calls'] if call[0] == 'run'][-1]+ assert run['env']['DATABASE_URL'] == 'production-credential'+++def test_nginx_reload_failure_keeps_runtime_and_failed_status(host, monkeypatch):+ parent, resources = host+ result = PreviewService.create_preview(parent, PR)+ monkeypatch.setattr(runtime.NginxService, 'disable_site', lambda _: {'success': False})+ assert PreviewService.destroy_preview(result['id']).get('error')+ row = db.session.get(ApplicationPreview, result['id'])+ assert row.get_runtime_state()['vhost']+ assert row.deleted_at is None and resources['containers']+++def test_container_daemon_outage_is_not_treated_as_already_removed(host, monkeypatch):+ parent, resources = host+ result = PreviewService.create_preview(parent, PR)+ monkeypatch.setattr(runtime.DockerService, 'run', lambda *a, **kw: {'success': False, 'error': 'daemon unavailable'})+ assert PreviewService.destroy_preview(result['id']).get('error')+ assert db.session.get(ApplicationPreview, result['id']).get_runtime_state()['container']+++def test_api_queues_without_building_and_requires_app_write(host, client, monkeypatch):+ from factories import headers_for, make_user+ from app.models import User+ from app.jobs.service import JobService+ parent, resources = host+ owner = db.session.get(User, parent.user_id)+ queued = []+ monkeypatch.setattr(JobService, 'enqueue', lambda *a, **kw: queued.append((a, kw)) or SimpleNamespace(id='job-id'))+ url = f'/api/v1/apps/{parent.id}/previews'+ result = client.post(url, headers=headers_for(owner), json=PR)+ assert result.status_code == 202 and result.json['job_id'] == 'job-id'+ assert not resources['calls'] and len(queued) == 1+ assert client.post(url, headers=headers_for(owner), json={**PR, 'commit_sha': '-bad'}).status_code == 400+ stranger = make_user(db, role='developer')+ assert client.post(url, headers=headers_for(stranger), json=PR).status_code in (403, 404)+ viewer = make_user(db, role='viewer')+ assert client.post(url, headers=headers_for(viewer), json=PR).status_code == 403+ assert len(queued) == 1+++def test_source_checkout_is_pinned_and_removes_git_credentials(tmp_path, monkeypatch):+ calls = []+ target = tmp_path / 'checkout'+ def clone(path, url, branch):+ (target / '.git').mkdir(parents=True)+ (target / '.git' / 'config').write_text('credential')+ calls.append(('clone', path, url, branch))+ return {'success': True}+ monkeypatch.setattr(source.GitService, 'clone_repository', clone)+ monkeypatch.setattr(source, 'run_checked', lambda argv, **kw: calls.append(argv) or {'success': True})+ source.prepare(None, SimpleNamespace(**PR), target, 'https://example.test/repo.git')+ assert any('--is-ancestor' in call and SHA in call for call in calls)+ assert any('--detach' in call and SHA in call for call in calls)+ assert not (target / '.git').exists()+++def test_build_uses_isolated_namespace_and_existing_dispatcher(tmp_path, monkeypatch):+ from app.services.build_service import BuildService+ calls = []+ config = {'app_path': '/production', 'build_method': 'dockerfile',+ 'env_vars': {'SECRET': 'private'}, 'build_args': {'TOKEN': 'private'}}+ monkeypatch.setattr(BuildService, 'get_app_build_config', lambda _: config)+ monkeypatch.setattr(BuildService, 'build_from_config', lambda *a, **kw: calls.append((a, kw)) or {'success': True})+ source.build(SimpleNamespace(id=1), SimpleNamespace(id=2), tmp_path, 'isolated:tag')+ args, kwargs = calls[0]+ assert args[0] == 'preview-2'+ assert args[1]['app_path'] == str(tmp_path)+ assert args[1]['env_vars'] == args[1]['build_args'] == {}+ assert config['app_path'] == '/production' and config['env_vars']['SECRET'] == 'private'+ assert kwargs['image_tag'] == 'isolated:tag'+++def test_preview_migration_round_trip_and_existing_schema():+ import importlib.util+ from pathlib import Path+ import sqlalchemy as sa+ from alembic.migration import MigrationContext+ from alembic.operations import Operations+ file = Path(__file__).parents[1] / 'migrations/versions/111_preview_runtime.py'+ spec = importlib.util.spec_from_file_location('preview_migration', file)+ migration = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(migration)+ engine = sa.create_engine('sqlite://')+ with engine.begin() as connection:+ connection.exec_driver_sql('CREATE TABLE application_previews (id INTEGER PRIMARY KEY)')+ connection.exec_driver_sql('CREATE TABLE application_preview_settings (application_id INTEGER PRIMARY KEY)')+ connection.exec_driver_sql('INSERT INTO application_preview_settings VALUES (1)')+ with Operations.context(MigrationContext.configure(connection)):+ migration.upgrade()+ migration.upgrade()+ assert connection.exec_driver_sql('SELECT inherit_environment FROM application_preview_settings').scalar() == 0+ assert 'runtime_state' in {c['name'] for c in sa.inspect(connection).get_columns('application_previews')}+ migration.downgrade()+ assert {c['name'] for c in sa.inspect(connection).get_columns('application_previews')} == {'id'}+++def test_partial_docker_run_is_compensated(host, monkeypatch):+ parent, resources = host+ original = runtime.DockerService.run_container+ def partial(**kwargs):+ original(**kwargs)+ return {'success': False, 'error': 'start failed after create'}+ monkeypatch.setattr(runtime.DockerService, 'run_container', partial)+ result = PreviewService.create_preview(parent, PR)+ assert result['status'] == 'failed'+ assert not resources['containers'] and not resources['images']+++def test_partial_nginx_publish_is_compensated(host, monkeypatch):+ parent, resources = host+ original = runtime.NginxService.create_site+ def partial(*args, **kwargs):+ original(*args, **kwargs)+ return {'success': False}+ monkeypatch.setattr(runtime.NginxService, 'create_site', partial)+ result = PreviewService.create_preview(parent, PR)+ assert result['status'] == 'failed'+ assert not resources['routes'] and not resources['containers']+++def test_purge_cleans_preview_before_deleting_ownership_record(host, monkeypatch):+ from datetime import datetime+ from app.services import recycle_bin_service+ parent, resources = host+ result = PreviewService.create_preview(parent, PR)+ parent.deleted_at = datetime.utcnow()+ db.session.commit()+ # Parent host lifecycle has its own suite; only previews touch Docker here.+ monkeypatch.setattr(recycle_bin_service, '_run_purge_hook', lambda *a: None)+ ok, warning = recycle_bin_service.purge('application', parent.id)+ assert ok, warning+ assert not resources['containers'] and not resources['images']+ assert db.session.get(ApplicationPreview, result['id']) is Nonediff --git a/backend/tests/test_preview_boundaries.py b/backend/tests/test_preview_boundaries.pynew file mode 100644index 00000000..245217eb--- /dev/null+++ b/backend/tests/test_preview_boundaries.py@@ -0,0 +1,42 @@+"""Keep preview planning pure and host effects out of its orchestration facade."""+import ast+from pathlib import Path+import pytest++ROOT = Path(__file__).parents[1] / 'app/services/previews'+++def imports(text):+ for node in ast.walk(ast.parse(text)):+ if isinstance(node, ast.Import):+ yield from (alias.name for alias in node.names)+ elif isinstance(node, ast.ImportFrom):+ yield node.module or ''+++def forbidden(module, imported):+ if imported == 'subprocess' or imported.endswith('deployment_service'):+ return True # shared runners/builders, never the parent-app deploy pipeline+ if module == 'plan.py':+ return imported.startswith(('flask', 'app.models', 'shutil', 'os'))+ return False++[email protected]('name,ceiling', [+ ('plan.py', 100), ('source.py', 120), ('runtime.py', 200),+ ('provisioner.py', 120), ('requests.py', 120), ('lifecycle.py', 80),+])+def test_preview_owners_stay_small_and_use_existing_host_services(name, ceiling):+ text = (ROOT / name).read_text(encoding='utf-8')+ assert len(text.splitlines()) <= ceiling+ assert not [value for value in imports(text) if forbidden(name, value)]++[email protected]('module,statement', [+ ('plan.py', 'from app.models import Application'),+ ('plan.py', 'import shutil'),+ ('runtime.py', 'import subprocess'),+ ('provisioner.py', 'from app.services.deployment_service import DeploymentService'),+])+def test_preview_boundary_guard_rejects_crossings(module, statement):+ assert any(forbidden(module, value) for value in imports(statement))diff --git a/backend/tests/test_real_generic_preview.py b/backend/tests/test_real_generic_preview.pynew file mode 100644index 00000000..09efc0c3--- /dev/null+++ b/backend/tests/test_real_generic_preview.py@@ -0,0 +1,93 @@+"""Opt-in real Git checkout, Docker build/runtime and HTTP health-gate lifecycle.++SERVERKIT_REAL_PREVIEWS=1 pytest tests/test_real_generic_preview.py+Only nginx publication is replaced: this test must not alter the host's sites.+"""+import functools+import os+import subprocess+import threading+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer+from urllib.request import urlopen+import pytest+from app import db+from app.models.application_preview import ApplicationPreview+from app.services.preview_service import PreviewService+from app.services.previews import runtime+from app.services.git_service import GitService+from app.services.build_service import BuildService+from test_previews import _mk_app++pytestmark = pytest.mark.skipif(os.environ.get('SERVERKIT_REAL_PREVIEWS') != '1',+ reason='opt-in real Docker preview smoke')+++def test_real_checkout_build_redeploy_http_and_cleanup(app, tmp_path, monkeypatch):+ def git(*args, cwd=None):+ return subprocess.run(['git', *args], cwd=cwd, check=True, capture_output=True,+ text=True, timeout=60).stdout.strip()+ repo = tmp_path / 'source'+ repo.mkdir()+ git('init', '-b', 'preview', cwd=repo)+ git('config', 'user.name', 'Preview Test', cwd=repo)+ git('config', 'user.email', '[email protected]', cwd=repo)+ (repo / 'Dockerfile').write_text('FROM busybox:1.36\nCOPY index.html /www/index.html\nCMD ["httpd", "-f", "-p", "8400", "-h", "/www"]\n')+ (repo / 'index.html').write_text('first-preview-commit')+ git('add', '.', cwd=repo)+ git('commit', '-m', 'first', cwd=repo)+ first = git('rev-parse', 'HEAD', cwd=repo)+ (repo / 'index.html').write_text('second-preview-commit')+ git('commit', '-am', 'second', cwd=repo)+ second = git('rev-parse', 'HEAD', cwd=repo)+ remote = tmp_path / 'remote.git'+ git('clone', '--bare', str(repo), str(remote))+ git('update-server-info', cwd=remote)+ handler = functools.partial(SimpleHTTPRequestHandler, directory=str(tmp_path))+ server = ThreadingHTTPServer(('127.0.0.1', 0), handler)+ thread = threading.Thread(target=server.serve_forever, daemon=True)+ thread.start()+ monkeypatch.setattr(runtime, 'ROOT', tmp_path / 'previews')+ monkeypatch.setattr(BuildService, 'BUILD_LOG_DIR', str(tmp_path / 'logs'))+ monkeypatch.setattr(BuildService, 'get_app_build_config', lambda _: {'build_method': 'dockerfile'})+ monkeypatch.setattr(GitService, 'get_app_config', lambda _: {'repo_url': f'http://127.0.0.1:{server.server_port}/remote.git'})+ monkeypatch.setattr(runtime.NginxService, 'list_sites', lambda: [])+ routes = {}+ def publish(name, kind, domains, **kwargs):+ rendered = runtime.NginxService.render_site_config(name, kind, domains, **kwargs)+ assert rendered['success']+ routes[name] = rendered['config']+ return {'success': True}+ monkeypatch.setattr(runtime.NginxService, 'create_site', publish)+ monkeypatch.setattr(runtime.NginxService, 'disable_site', lambda _: {'success': True})+ # delete returns a dict, independent of the removed config text.+ def delete(name):+ routes.pop(name, None)+ return {'success': True}+ monkeypatch.setattr(runtime.NginxService, 'delete_site', delete)+ monkeypatch.setattr(runtime.SiteDomainService, 'covering_base', lambda _: None)+ try:+ with app.app_context():+ parent = _mk_app(name='real-preview')+ PreviewService.enable_previews(parent.id, {'enabled': True, 'domain_template': 'pr-{pr_number}.example.test'})+ preview_id = None+ try:+ for sha, expected in [(first, 'first-preview-commit'), (second, 'second-preview-commit')]:+ result = PreviewService.create_preview(parent, {'pr_number': 17, 'branch': 'preview', 'commit_sha': sha})+ preview_id = result.get('id')+ assert result['status'] == 'running', result+ row = db.session.get(ApplicationPreview, preview_id)+ state = row.get_runtime_state()+ with urlopen(f"http://127.0.0.1:{state['port']}", timeout=10) as response:+ assert response.read().decode() == expected+ assert str(state['port']) in next(iter(routes.values()))+ assert PreviewService.destroy_preview(preview_id)['status'] == 'destroyed'+ assert not routes and not list(runtime.ROOT.iterdir())+ assert runtime.inspect('container', runtime.identity(preview_id, state['token'])) is None+ assert runtime.inspect('image', runtime.identity(preview_id, state['token']) + ':preview') is None+ finally:+ if preview_id:+ PreviewService.destroy_preview(preview_id)+ finally:+ server.shutdown()+ server.server_close()+ thread.join(timeout=5)diff --git a/docs/CORE_BOUNDARIES.md b/docs/CORE_BOUNDARIES.mdindex b679d26b..5485f556 100644--- a/docs/CORE_BOUNDARIES.md+++ b/docs/CORE_BOUNDARIES.md@@ -152,11 +152,11 @@ both non-Compose apps and unreadable Compose files, so that case is explicitlylabelled as unfiltered configuration.A preview can be advertised as running only after an explicit successful-provider result with runtime IDs. Generic manifest configuration generation is-not deployment and reports `unavailable`. Legacy running rows without IDs are-projected as unavailable without mutating them on read. Only running previews-with recorded IDs expose a URL. These checks establish provisioning evidence;-they do not claim live container health or validate DNS reachability.+provider result with runtime IDs. Generic previews additionally gate on HTTP+health before publishing nginx. Legacy running rows without IDs are projected+as unavailable without mutating them on read. The generic URL scheme reflects+whether a covering single-label wildcard certificate was actually selected;+otherwise it is HTTP. DNS must point to the preview host.Regression coverage: `test_effective_env.py`, `test_env_vars_api.py`,`test_compose_env_overlay.py`, `test_previews.py`, and@@ -164,3 +164,57 @@ Regression coverage: `test_effective_env.py`, `test_env_vars_api.py`,check runs in frontend CI and covers service switching with late replies,failed discovery, masking, incomplete results, retry, the local editor, andpreview link/toast behavior.+++## Generic preview deployment ownership++`services/previews/` separates six concerns:++- `plan.py`: pure eligibility, resource identities and path containment.+- `requests.py`: short request reservations and queued desired state. PR closes+ supersede queued/in-flight creates; old jobs cannot revive a newer request.+- `source.py`: independent Git clone, exact reachable commit checkout, credential+ metadata removal, and delegation to `BuildService.build_from_config`.+- `runtime.py`: persisted resource intent, Docker start/inspection/cleanup,+ existing HTTP health gate, and nginx publication/removal.+- `provisioner.py`: validation, sequencing and compensation on failure.+- `lifecycle.py`: cleanup when deleting or purging the parent application.++Generic support currently means local Git-backed single-container apps using+Dockerfiles or container buildpacks with nginx ingress. Compose, remote targets,+proxy-stack ingress, and host-command builds are rejected. Fork commits must+be reachable from the selected branch in the parent's configured repository;+arbitrary fork repositories are not fetched. Redeploy is stop/recreate, not a+zero-downtime switch. Signed PR update webhooks deploy their supplied commit;+full open-PR discovery remains unavailable and fails without deleting anything.++Production deployment records, source trees, container identities, ports,+volumes, networks and build configuration are never repurposed. Each preview+attempt has a random generation name, an isolated image and checkout, and a+Docker-assigned loopback host port. Parent build secrets are not copied.+Runtime environment inheritance defaults off and is an explicit setting; when+on, it can grant preview code access to production services. Use only trusted+PR code and credentials appropriate to its intended environment.++Migration `111_preview_runtime` records the cleanup ledger, request token,+desired action, error and environment opt-in. Persist each resource intent+before touching the host, and clear it only after successful cleanup. Docker+inspection failure is not evidence that a resource is gone. Failed deletion+retains the ledger and reports failure; retry deletion to finish. Application+purge/retention must keep the parent row when preview cleanup fails so the+ownership record is not lost. Interrupted builds can likewise be deleted or+redeployed using their persisted ledger.++Create, redeploy and delete return 202 with a unified job ID; build output goes+to the existing Jobs log stream. The new create endpoint deliberately supports+API-key CI automation through `developer_required`, plus app write access.+Existing JWT-only endpoints retain their authentication boundary. UI refresh is+manual and queued deletion never claims cleanup already finished.++Run `test_generic_previews.py`, `test_preview_boundaries.py`, existing preview,+buildpack, recycle-bin, authorization and migration suites. For a disposable+real Git/Docker smoke run, set `SERVERKIT_REAL_PREVIEWS=1` and run+`tests/test_real_generic_preview.py`: it builds two exact commits, checks their+HTTP responses and cleanup, while rendering rather than installing nginx sites.+The existing frontend browser check covers the pinned create form, environment+opt-in, and queued deletion. No new UI styling system is introduced.diff --git a/docs/MIGRATION_INVENTORY.md b/docs/MIGRATION_INVENTORY.mdindex 1709215c..4b257b36 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 | 598 | 598 | 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 | 848 | 850 | migrate when touched; new endpoints raise |+| Hand-shaped {'error': ...} bodies in app/api | typed errors + the global handler | 849 | 850 | migrate when touched; new endpoints raise || Raw subprocess calls outside the runners | app/utils/system.py runners | 23 | 23 | migrate when touched || Controller-boundary violations (routes doing service work) | service layer extraction | 477 | 477 | migrate when touched (first-wave ratchet) || raw api.* calls in pages/ | E1: useServerQuery/useServerMutation | 374 | 398 | migrate when touched |