Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat: 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.py
index 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 ApplicationPreview
from app.services.preview_service import PreviewService
from app.api._access import require_app
from 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 ValidationError
previews_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 exc
return 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}), 202
diff --git a/backend/app/services/application_restore.py b/backend/app/services/application_restore.py
index 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 results
diff --git a/backend/app/services/preview_service.py b/backend/app/services/preview_service.py
index 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_lock
with deploy_lock(app.id, 'preview deploy'):
from app.services.previews.requests import current
if 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 = branch
preview.pr_title = pr_title
preview.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_UNAVAILABLE
elif 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 db
db.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 = 0
for 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 SourceConnectionService
fn = 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 None
except 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 result
if 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
@classmethod
diff --git a/backend/app/services/previews/lifecycle.py b/backend/app/services/previews/lifecycle.py
new file mode 100644
index 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.py
index 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_token
try:
@@ -42,11 +42,15 @@ def provision(app, preview, settings):
name = identity(preview.id, state['token'])
state['source'] = True
runtime.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'] = True
runtime.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.py
index 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 False
db.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.py
index 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'] = True
save(preview, state) # intent before docker run, even if it partially fails
env = {'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 EnvService
entries, complete = EnvService._effective_entries(app)
if not complete:
diff --git a/backend/app/services/previews/source.py b/backend/app/services/previews/source.py
index 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.py
index 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_FOUND
if 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 = 0
for 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] = purged
if counts:
db.session.commit()
return counts
diff --git a/backend/tests/test_generic_previews.py b/backend/tests/test_generic_previews.py
index 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 = host
monkeypatch.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 None
diff --git a/backend/tests/test_preview_boundaries.py b/backend/tests/test_preview_boundaries.py
new file mode 100644
index 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.py
new file mode 100644
index 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.md
index 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 explicitly
labelled 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, and
preview 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.md
index 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 |