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: provision isolated generic previews with retryable resource cleanup

Juan Denis5a13a0dfb167
diff --git a/backend/app/api/webhooks.py b/backend/app/api/webhooks.py
index 24f45ce7..891ce00c 100644
--- a/backend/app/api/webhooks.py
+++ b/backend/app/api/webhooks.py
@@ -189,24 +189,13 @@ def receive_pull_request(token):
'pr_title': pr.get('pr_title'),
}}
- # On close we destroy by preview-id (the PR number maps to exactly one
- # preview row); resolving it here avoids a full sync that — with no
- # connected provider — would otherwise tear down every preview.
- if job_kind == 'preview.destroy':
- from app.models.application_preview import ApplicationPreview
- preview = ApplicationPreview.query.filter_by(
- application_id=webhook.app_id, pr_number=pr.get('pr_number')).first()
- if not preview:
- return jsonify({'success': True, 'action': 'ignored',
- 'reason': 'no preview for closed PR'}), 200
- payload = {'preview_id': preview.id}
-
- # Enqueue the matching preview job. Under ENV=testing the job system is a
- # no-op; never let an enqueue failure break the webhook response.
+ # Reserve desired state even when the create job has not started yet.
+ # A close must cancel a queued build rather than disappear for lack of a row.
enqueued = False
try:
- from app.plugins_sdk import jobs
- jobs.enqueue(job_kind, payload)
+ from app.services.previews.requests import enqueue
+ enqueue(webhook.app_id, payload['pr'],
+ action='destroy' if job_kind == 'preview.destroy' else 'create')
enqueued = True
except Exception as exc:
logger.warning('failed to enqueue %s for app %s: %s',
diff --git a/backend/app/models/application_preview.py b/backend/app/models/application_preview.py
index 1f35fd58..4688adbb 100644
--- a/backend/app/models/application_preview.py
+++ b/backend/app/models/application_preview.py
@@ -48,6 +48,12 @@ class ApplicationPreview(TimestampMixin, JsonColumnMixin, db.Model):
# when Docker isn't available, e.g. dev/test).
container_ids = db.Column(db.Text, nullable=True)
+ # Durable intent ledger: written before external effects, retained on cleanup failure.
+ request_token = db.Column(db.String(32), nullable=True)
+ requested_action = db.Column(db.String(16), nullable=True)
+ runtime_state = db.Column(db.Text, nullable=True)
+ error_message = db.Column(db.Text, nullable=True)
+
commit_sha = db.Column(db.String(64), nullable=True)
expires_at = db.Column(db.DateTime, nullable=True)
@@ -60,6 +66,12 @@ class ApplicationPreview(TimestampMixin, JsonColumnMixin, db.Model):
def set_container_ids(self, ids):
self._json_write('container_ids', list(ids or []), falsy='[]')
+ def get_runtime_state(self):
+ return self._json_read('runtime_state', {}, expect=dict)
+
+ def set_runtime_state(self, state):
+ self._json_write('runtime_state', state, falsy='{}')
+
def to_dict(self):
container_ids = self.get_container_ids()
# Older generic previews were marked running after config generation
@@ -75,11 +87,11 @@ class ApplicationPreview(TimestampMixin, JsonColumnMixin, db.Model):
'branch': self.branch,
'status': status,
'status_reason': (
- 'No provisioned runtime is recorded for this preview.'
- if status == self.STATUS_UNAVAILABLE else None
+ self.error_message or ('No provisioned runtime is recorded for this preview.'
+ if status == self.STATUS_UNAVAILABLE else None)
),
'domain': self.domain,
- 'url': (f'https://{self.domain}'
+ 'url': (f"{self.get_runtime_state().get('scheme', 'https')}://{self.domain}"
if self.domain and status == self.STATUS_RUNNING and container_ids else None),
'container_ids': container_ids,
'commit_sha': self.commit_sha,
@@ -107,6 +119,7 @@ class ApplicationPreviewSettings(TimestampMixin, db.Model):
application = db.relationship('Application',
backref=db.backref('preview_settings', uselist=False))
+ inherit_environment = db.Column(db.Boolean, nullable=False, default=False, server_default='0')
enabled = db.Column(db.Boolean, default=False, nullable=False)
domain_template = db.Column(
db.String(255), default=DEFAULT_DOMAIN_TEMPLATE, nullable=False)
@@ -120,6 +133,7 @@ class ApplicationPreviewSettings(TimestampMixin, db.Model):
return {
'application_id': self.application_id,
'enabled': bool(self.enabled),
+ 'inherit_environment': bool(self.inherit_environment),
'domain_template': self.domain_template or self.DEFAULT_DOMAIN_TEMPLATE,
'target_server_id': self.target_server_id,
'ttl_days': self.ttl_days,
diff --git a/backend/app/services/build_service.py b/backend/app/services/build_service.py
index ff382973..8d609ff9 100644
--- a/backend/app/services/build_service.py
+++ b/backend/app/services/build_service.py
@@ -622,6 +622,17 @@ class BuildService:
if not build_config:
return {'success': False, 'error': 'Build is not set up for this service'}
+ return cls.build_from_config(app_id, build_config, no_cache=no_cache,
+ log_callback=log_callback, image_tag=image_tag)
+
+ @classmethod
+ def build_from_config(cls, app_id, build_config, no_cache=False,
+ log_callback=None, image_tag=None):
+ """Build an explicit workspace without changing an app's saved config.
+
+ Isolated consumers must supply their own log namespace and image tag.
+ The production build() entry point delegates here too.
+ """
app_path = build_config['app_path']
build_method = build_config.get('build_method', 'auto')
timeout = build_config.get('timeout', cls.DEFAULT_TIMEOUT)
diff --git a/backend/app/services/docker_service.py b/backend/app/services/docker_service.py
index 20fe6842..5684b07e 100644
--- a/backend/app/services/docker_service.py
+++ b/backend/app/services/docker_service.py
@@ -309,7 +309,7 @@ class DockerService:
@staticmethod
def run_container(image, name=None, ports=None, volumes=None, env=None,
- network=None, restart_policy='unless-stopped', command=None, detach=True):
+ network=None, restart_policy='unless-stopped', command=None, detach=True, labels=None):
"""Run a new container (create and start)."""
try:
cmd = ['run']
@@ -332,6 +332,9 @@ class DockerService:
for key, value in env.items():
cmd.extend(['-e', f'{key}={value}'])
+ for key, value in (labels or {}).items():
+ cmd.extend(['--label', f'{key}={value}'])
+
if network:
cmd.extend(['--network', network])
diff --git a/backend/app/services/preview_service.py b/backend/app/services/preview_service.py
index 9c75d567..e90d7cfc 100644
--- a/backend/app/services/preview_service.py
+++ b/backend/app/services/preview_service.py
@@ -171,6 +171,10 @@ class PreviewService:
row = ApplicationPreviewSettings(application_id=application_id)
db.session.add(row)
+ if 'inherit_environment' in settings:
+ if not isinstance(settings['inherit_environment'], bool):
+ raise ValueError('inherit_environment must be a boolean')
+ row.inherit_environment = settings['inherit_environment']
if 'enabled' in settings:
row.enabled = bool(settings['enabled'])
if 'domain_template' in settings and settings['domain_template']:
@@ -242,7 +246,16 @@ class PreviewService:
# ------------------------------------------------------------------ #
@classmethod
- def create_preview(cls, app, pr_payload):
+ def create_preview(cls, app, pr_payload, request_payload=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)
+
+ @classmethod
+ def _create_preview_locked(cls, app, pr_payload):
"""Create (or update-in-place) a preview for a PR. Best-effort.
Writes/updates an :class:`ApplicationPreview` row, renders the domain,
@@ -254,10 +267,15 @@ class PreviewService:
from app.models.application_preview import ApplicationPreview
try:
+ db.session.refresh(app)
+ if app.deleted_at is not None:
+ return {'error': 'Service not found'}
pr_number = cls._pr_field(pr_payload, 'pr_number', 'number')
if pr_number is None:
return {'error': 'pr_number is required'}
pr_number = int(pr_number)
+ if pr_number <= 0:
+ return {'error': 'PR number must be positive'}
branch = cls._pr_field(pr_payload, 'branch', 'head_ref', 'head')
pr_title = cls._pr_field(pr_payload, 'pr_title', 'title')
commit_sha = cls._pr_field(pr_payload, 'commit_sha', 'sha', 'head_sha')
@@ -280,8 +298,8 @@ class PreviewService:
preview.deleted_at = None
ttl_days = getattr(settings, 'ttl_days', None)
- if ttl_days:
- preview.expires_at = datetime.utcnow() + timedelta(days=int(ttl_days))
+ preview.expires_at = (datetime.utcnow() + timedelta(days=int(ttl_days))
+ if ttl_days else None)
db.session.commit()
@@ -295,6 +313,8 @@ class PreviewService:
preview.status = ApplicationPreview.STATUS_FAILED
if provisioned.get('container_ids'):
preview.set_container_ids(provisioned['container_ids'])
+ elif not preview.get_runtime_state().get('container'):
+ preview.set_container_ids([])
db.session.commit()
return preview.to_dict()
except Exception as exc:
@@ -309,8 +329,8 @@ class PreviewService:
def _provision(cls, app, preview):
"""Best-effort real provisioning. Returns ``{'ok': bool, 'container_ids': [...]}``.
- WordPress delegates to its preview hook. Generic config generation is
- not provisioning: until a runtime provisioner exists, report unsupported.
+ WordPress delegates to its preview hook; generic runtimes have a separate
+ journalled provisioner reusing the standard container builders.
A provider must explicitly report success and return runtime identifiers.
"""
try:
@@ -329,24 +349,29 @@ class PreviewService:
except Exception as exc:
logger.info('WP preview provisioning unavailable: %s', exc)
return {'ok': False, 'container_ids': []}
- # Non-WP: clone the manifest-resolved config (env + per-preview
- # overrides + domain) when the app is manifest-managed (#20). The
- # resolved config is the portable unit; a full Docker clone for
- # generic apps remains best-effort future work.
- manifest_preview = None
- try:
- from app.services.manifest_preview_service import ManifestPreviewService
- manifest_preview = ManifestPreviewService.build_preview_config(app, preview)
- except Exception as exc:
- logger.info('manifest preview config unavailable: %s', exc)
- return {'ok': False, 'unsupported': True, 'container_ids': [],
- 'manifest_preview': manifest_preview}
+ from app.services.previews.provisioner import provision
+ return provision(app, preview, cls.get_settings(app.id))
except Exception as exc:
logger.info('preview provisioning unavailable: %s', exc)
return {'ok': False, 'container_ids': []}
@classmethod
- def destroy_preview(cls, preview_id):
+ def destroy_preview(cls, preview_id, request_payload=None):
+ from app.models.application_preview import ApplicationPreview
+ from app.services.deploy_lock import deploy_lock
+ row = ApplicationPreview.query.get(preview_id)
+ if not row:
+ return {'error': 'preview not found'}
+ with deploy_lock(row.application_id, 'preview cleanup'):
+ from app.services.previews.requests import current
+ if request_payload and not current(request_payload):
+ return {'skipped': True, 'reason': 'superseded'}
+ from app import db
+ db.session.refresh(row)
+ return cls._destroy_preview_locked(preview_id)
+
+ @classmethod
+ def _destroy_preview_locked(cls, preview_id):
"""Tear down a preview and mark it destroyed. Best-effort; never raises."""
from app import db
from app.models.application_preview import ApplicationPreview
@@ -368,6 +393,10 @@ class PreviewService:
except Exception:
pass
+ if preview.runtime_state:
+ from app.services.previews.runtime import cleanup
+ cleanup(preview)
+
# Best-effort WordPress teardown.
if app is not None and getattr(app, 'app_type', None) == 'wordpress':
try:
@@ -391,7 +420,11 @@ class PreviewService:
db.session.rollback()
except Exception:
pass
- return {'error': str(exc)}
+ if preview:
+ preview.status = ApplicationPreview.STATUS_FAILED
+ preview.error_message = 'Preview cleanup failed; retry deletion.'
+ db.session.commit()
+ return {'error': 'Preview cleanup failed; retry deletion.'}
@classmethod
def sync_previews(cls, application_id):
@@ -412,6 +445,8 @@ class PreviewService:
return {'error': 'Service not found'}
open_prs = cls._fetch_open_prs(app)
+ if open_prs is None:
+ return {'error': 'Open PR discovery is unavailable; existing previews were left unchanged.'}
active = ApplicationPreview.query.filter(
ApplicationPreview.application_id == application_id,
ApplicationPreview.status != ApplicationPreview.STATUS_DESTROYED,
@@ -449,7 +484,7 @@ class PreviewService:
return prs if isinstance(prs, list) else []
except Exception as exc:
logger.debug('open-PR listing unavailable for app %s: %s', app.id, exc)
- return []
+ return None
@classmethod
def expire_stale(cls):
@@ -464,9 +499,8 @@ class PreviewService:
ApplicationPreview.expires_at < now,
ApplicationPreview.status != ApplicationPreview.STATUS_DESTROYED,
).all()
- for preview in stale:
- cls.destroy_preview(preview.id)
- return {'expired': len(stale)}
+ expired = sum(cls.destroy_preview(p.id).get('status') == 'destroyed' for p in stale)
+ return {'expired': expired, 'failed': len(stale) - expired}
except Exception as exc:
logger.warning('expire_stale failed: %s', exc)
return {'expired': 0, 'error': str(exc)}
@@ -484,17 +518,30 @@ class PreviewService:
id=payload.get('application_id')).first()
if not app:
return {'error': 'Service not found'}
- return cls.create_preview(app, payload.get('pr') or payload)
+ result = cls.create_preview(app, payload.get('pr') or payload, request_payload=payload)
+ if result.get('skipped'):
+ return result
+ if result.get('error') or result.get('status') != 'running':
+ raise RuntimeError(result.get('error') or result.get('status_reason') or 'Preview was not deployed')
+ return result
@classmethod
def _job_destroy(cls, job):
payload = job.get_payload() or {}
- return cls.destroy_preview(payload.get('preview_id'))
+ result = cls.destroy_preview(payload.get('preview_id'), request_payload=payload)
+ if result.get('error'):
+ raise RuntimeError(result['error'])
+ return result
@classmethod
def _job_sync(cls, job):
payload = job.get_payload() or {}
- return cls.sync_previews(payload.get('application_id'))
+ 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'])
+ return result
@classmethod
def _job_expire(cls, _job):
diff --git a/backend/app/services/previews/__init__.py b/backend/app/services/previews/__init__.py
new file mode 100644
index 00000000..594f1716
--- /dev/null
+++ b/backend/app/services/previews/__init__.py
@@ -0,0 +1 @@
+"""Isolated generic preview planning, source preparation and runtime lifecycle."""
diff --git a/backend/app/services/previews/plan.py b/backend/app/services/previews/plan.py
new file mode 100644
index 00000000..83dd3835
--- /dev/null
+++ b/backend/app/services/previews/plan.py
@@ -0,0 +1,53 @@
+"""Pure preview identity and eligibility; no host operations."""
+import re
+from pathlib import Path
+from app.services.nginx.validation import _validate_domain
+from app.utils.git_security import validate_repo_url, validate_ref_name
+
+
+class PreviewError(ValueError):
+ pass
+
+
+def validate(app, preview, settings, git_config):
+ if app.server_id or settings.target_server_id:
+ raise PreviewError('Generic previews currently require a local server.')
+ if app.compose_file or app.managed_by in ('docker_compose', 'systemd'):
+ raise PreviewError('Compose and systemd previews are not supported by this provisioner.')
+ if app.ingress_plane not in (None, '', 'nginx'):
+ raise PreviewError('Generic previews currently require nginx ingress.')
+ if not app.port or not 1 <= app.port <= 65535:
+ raise PreviewError('Configure the application container port before deploying a preview.')
+ if not preview.domain or len(preview.domain) > 253 or not _validate_domain(preview.domain):
+ raise PreviewError('Invalid preview domain.')
+ if not isinstance(preview.pr_number, int) or preview.pr_number <= 0:
+ raise PreviewError('PR number must be a positive integer.')
+ if not preview.branch or validate_ref_name(preview.branch, 'branch'):
+ raise PreviewError('A valid branch in the configured repository is required.')
+ if not re.fullmatch(r'[0-9a-fA-F]{40}|[0-9a-fA-F]{64}', preview.commit_sha or ''):
+ raise PreviewError('An exact full commit SHA is required.')
+ if not git_config or validate_repo_url(git_config.get('repo_url')):
+ raise PreviewError('Configure a valid Git repository for this application first.')
+
+
+def identity(preview_id, token):
+ if not isinstance(preview_id, int) or preview_id <= 0 or not re.fullmatch(r'[0-9a-f]{32}', token):
+ raise PreviewError('Invalid preview resource identity.')
+ return f'serverkit-preview-{preview_id}-{token}'
+
+
+def workspace(root, preview_id, token):
+ # Never accept stored/PR-provided paths as cleanup targets.
+ name = identity(preview_id, token)
+ base = Path(root).resolve()
+ target = base / name
+ if target.is_symlink() or target.resolve().parent != base:
+ raise PreviewError('Preview workspace escaped its managed directory.')
+ return target
+
+
+def relative_file(root, name):
+ path = Path(root) / name
+ if Path(name).is_absolute() or not path.resolve().is_relative_to(Path(root).resolve()):
+ raise PreviewError('Build path must stay inside the preview checkout.')
+ return path
diff --git a/backend/app/services/previews/provisioner.py b/backend/app/services/previews/provisioner.py
new file mode 100644
index 00000000..a74d905e
--- /dev/null
+++ b/backend/app/services/previews/provisioner.py
@@ -0,0 +1,67 @@
+"""Generic preview transaction: validate, journal, build, gate, publish; compensate failures."""
+import uuid
+from app import db
+from app.models import Domain
+from app.models.application_preview import ApplicationPreview
+from app.services.git_service import GitService
+from app.services.nginx_service import NginxService
+from . import runtime, source
+from .plan import PreviewError, validate, identity, workspace
+
+
+def check_domain(preview):
+ domain = preview.domain.lower()
+ if Domain.query_active().filter(db.func.lower(Domain.name) == domain).first():
+ raise PreviewError('Preview domain is already assigned to an application.')
+ if ApplicationPreview.query.filter(
+ ApplicationPreview.id != preview.id,
+ db.func.lower(ApplicationPreview.domain) == domain,
+ ApplicationPreview.status != 'destroyed',
+ ).first():
+ raise PreviewError('Preview domain is already assigned to another preview.')
+ owned = preview.get_runtime_state().get('token')
+ own_name = identity(preview.id, owned) if owned else None
+ for site in NginxService.list_sites():
+ if site['name'] != own_name and domain in [d.lower() for d in site.get('domains', [])]:
+ raise PreviewError('Preview domain is already configured in nginx.')
+
+
+def provision(app, preview, settings):
+ config = GitService.get_app_config(app.id)
+ request_token = preview.request_token
+ try:
+ validate(app, preview, settings, config)
+ check_domain(preview)
+ # Stop/recreate semantics are deliberate: cleanup must finish before a
+ # new attempt. We never lose ownership of an abandoned generation.
+ runtime.cleanup(preview)
+ state = {'token': uuid.uuid4().hex}
+ runtime.save(preview, state)
+ target = workspace(runtime.ROOT, preview.id, state['token'])
+ target.parent.mkdir(parents=True, exist_ok=True)
+ name = identity(preview.id, state['token'])
+ state['source'] = True
+ runtime.save(preview, state)
+ 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)
+ 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':
+ raise PreviewError('Preview request was superseded or its application was deleted.')
+ runtime.publish(preview, state)
+ preview.error_message = None
+ return {'ok': True, 'container_ids': [state['container_id']]}
+ except Exception as exc:
+ # Only controlled diagnostics go to the browser; host errors may carry
+ # credentials or environment values. The journal survives cleanup errors.
+ error = str(exc) if isinstance(exc, PreviewError) else 'Preview provisioning failed.'
+ try:
+ runtime.cleanup(preview)
+ except Exception:
+ error += ' Cleanup is incomplete; retry deletion before deploying again.'
+ preview.error_message = error
+ db.session.commit()
+ return {'ok': False, 'container_ids': [], 'error': error}
diff --git a/backend/app/services/previews/requests.py b/backend/app/services/previews/requests.py
new file mode 100644
index 00000000..699f2bbd
--- /dev/null
+++ b/backend/app/services/previews/requests.py
@@ -0,0 +1,40 @@
+"""Short request reservations, separate from long-running deployment locks."""
+import uuid
+from app import db
+from app.models.application_preview import ApplicationPreview
+from app.jobs.service import JobService
+from app.services.deploy_lock import deploy_lock
+from .plan import PreviewError
+
+
+def enqueue(app_id, pr, action='create'):
+ try:
+ number = int(pr.get('pr_number'))
+ except (TypeError, ValueError):
+ raise PreviewError('A positive PR number is required.')
+ if number <= 0 or action not in ('create', 'destroy'):
+ raise PreviewError('Invalid preview request.')
+ # Distinct from the app deploy lock: a close can supersede an in-flight
+ # build immediately instead of blocking the webhook for several minutes.
+ with deploy_lock(f'preview-request-{app_id}', 'preview request'):
+ row = ApplicationPreview.query.filter_by(application_id=app_id, pr_number=number).first()
+ if row is None:
+ row = ApplicationPreview(application_id=app_id, pr_number=number, status='queued')
+ db.session.add(row)
+ row.request_token = uuid.uuid4().hex
+ row.requested_action = action
+ db.session.commit()
+ return JobService.enqueue('preview.' + action, {
+ 'application_id': app_id, 'preview_id': row.id, 'pr': pr,
+ 'request_token': row.request_token,
+ }, max_attempts=1, owner_type='application', owner_id=str(app_id))
+
+
+def current(payload):
+ if not payload.get('request_token'):
+ return True # compatibility with older queued jobs
+ row = db.session.get(ApplicationPreview, payload.get('preview_id'))
+ if not row:
+ return False
+ db.session.refresh(row, ['request_token'])
+ return row.request_token == payload['request_token']
diff --git a/backend/app/services/previews/runtime.py b/backend/app/services/previews/runtime.py
new file mode 100644
index 00000000..cb5cdd15
--- /dev/null
+++ b/backend/app/services/previews/runtime.py
@@ -0,0 +1,123 @@
+"""Host effects for one journalled preview generation; never operate on parent resources."""
+import json
+import shutil
+from pathlib import Path
+from app import db, paths
+from app.services.docker_service import DockerService
+from app.services.nginx_service import NginxService
+from app.services.site_domain_service import SiteDomainService
+from app.services import health_gate
+from .plan import PreviewError, identity, workspace
+
+ROOT = Path(paths.SERVERKIT_DIR) / 'previews'
+LABEL = 'serverkit.preview'
+
+
+def save(preview, state):
+ preview.set_runtime_state(state)
+ db.session.commit()
+
+
+def inspect(kind, name):
+ result = DockerService.run([kind, 'inspect', name], timeout=30)
+ if result.get('success'):
+ return json.loads(result['output'])[0]
+ error = (result.get('error') or '').lower()
+ if 'no such' in error:
+ return None
+ raise PreviewError('Cannot inspect preview resources; cleanup must be retried.')
+
+
+def start(app, preview, state):
+ 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:
+ from app.services.env_service import EnvService
+ entries, complete = EnvService._effective_entries(app)
+ if not complete:
+ raise PreviewError('Inherited environment is incomplete; preview deployment stopped.')
+ env = {**{key: value['value'] for key, value in entries.items()}, **env}
+ result = DockerService.run_container(
+ image=name + ':preview', name=name, ports=[f'127.0.0.1::{app.port}'],
+ env=env, restart_policy='unless-stopped', labels={LABEL: str(preview.id)},
+ )
+ if not result.get('success'):
+ raise PreviewError('Could not start the preview container.')
+ info = inspect('container', name)
+ if not info or info.get('Config', {}).get('Labels', {}).get(LABEL) != str(preview.id):
+ raise PreviewError('Preview container ownership could not be verified.')
+ bindings = info.get('NetworkSettings', {}).get('Ports', {}).get(f'{app.port}/tcp') or []
+ binding = next((b for b in bindings if b.get('HostIp') == '127.0.0.1'), None)
+ if not binding:
+ raise PreviewError('Preview container has no loopback HTTP port.')
+ state['port'] = int(binding['HostPort'])
+ state['container_id'] = info['Id']
+ save(preview, state)
+ health_gate.gate_for_app(app, port=state['port'], container=name)
+ info = inspect('container', name)
+ if not info or not info.get('State', {}).get('Running'):
+ raise PreviewError('Preview container stopped during its health check.')
+
+
+def publish(preview, state):
+ name = identity(preview.id, state['token'])
+ cert = key = None
+ base = SiteDomainService.covering_base(preview.domain)
+ # A wildcard certificate covers exactly one label, not pr.app.base.
+ if base and preview.domain.endswith('.' + base) and preview.domain.count('.') == base.count('.') + 1:
+ if SiteDomainService.https_enabled(base):
+ cert, key = SiteDomainService.wildcard_cert_paths(base)
+ state['scheme'] = 'https' if cert and key else 'http'
+ state['vhost'] = True
+ save(preview, state)
+ result = NginxService.create_site(name, 'docker', [preview.domain],
+ port=state['port'], ssl_cert=cert, ssl_key=key)
+ if not result.get('success'):
+ raise PreviewError('Preview routing could not be published.')
+
+
+def cleanup(preview):
+ """Idempotent, fail closed. Retain each intent until its removal succeeds."""
+ state = preview.get_runtime_state()
+ if not state:
+ if preview.runtime_state and preview.runtime_state != '{}':
+ raise PreviewError('Preview resource ledger is invalid; refusing untracked cleanup.')
+ return
+ name = identity(preview.id, state.get('token', ''))
+ target = workspace(ROOT, preview.id, state['token'])
+ if state.get('vhost'):
+ # delete_site historically ignores disable failures. Check disable first
+ # so nginx cannot continue serving a resource reported as destroyed.
+ if not NginxService.disable_site(name).get('success'):
+ raise PreviewError('Preview routing cleanup failed; retry deletion.')
+ if not NginxService.delete_site(name).get('success'):
+ raise PreviewError('Preview vhost cleanup failed; retry deletion.')
+ state['vhost'] = False
+ save(preview, state)
+ if state.get('container'):
+ info = inspect('container', name)
+ if info:
+ if info.get('Config', {}).get('Labels', {}).get(LABEL) != str(preview.id):
+ raise PreviewError('Refusing to delete a container without preview ownership.')
+ if not DockerService.remove_container(name, force=True, volumes=True).get('success'):
+ raise PreviewError('Preview container cleanup failed; retry deletion.')
+ state['container'] = False
+ preview.set_container_ids([])
+ save(preview, state)
+ if state.get('image'):
+ if inspect('image', name + ':preview') is not None:
+ if not DockerService.remove_image(name + ':preview', force=False).get('success'):
+ raise PreviewError('Preview image cleanup failed; retry deletion.')
+ state['image'] = False
+ save(preview, state)
+ if state.get('source'):
+ if target.exists():
+ shutil.rmtree(target)
+ state['source'] = False
+ save(preview, state)
+ preview.set_container_ids([])
+ save(preview, {})
diff --git a/backend/app/services/previews/source.py b/backend/app/services/previews/source.py
new file mode 100644
index 00000000..305114ca
--- /dev/null
+++ b/backend/app/services/previews/source.py
@@ -0,0 +1,49 @@
+"""Prepare an independent, pinned checkout and reuse the standard builders."""
+import shutil
+from app.services.git_service import GitService
+from app.services.build_service import BuildService
+from app.utils.git_security import git_argv, git_env
+from app.utils.system import run_checked
+from .plan import PreviewError, relative_file
+
+
+def prepare(app, preview, target, repo_url):
+ result = GitService.clone_repository(str(target), repo_url, branch=preview.branch)
+ if not result.get('success'):
+ # Raw Git output can contain authenticated repository URLs.
+ raise PreviewError('Preview repository clone failed. Check repository access and branch.')
+ sha = preview.commit_sha.lower()
+ # A PR must name a commit reachable from the selected same-repository branch.
+ result = run_checked(git_argv('-C', str(target), 'merge-base', '--is-ancestor',
+ sha, 'HEAD'), timeout=30, env=git_env())
+ if not result.get('success'):
+ raise PreviewError('Preview commit is not reachable from the selected repository branch.')
+ result = run_checked(git_argv('-C', str(target), 'checkout', '--detach', sha),
+ timeout=60, env=git_env())
+ if not result.get('success'):
+ raise PreviewError('Could not check out the requested preview commit.')
+ # Do not send clone credentials / Git metadata into a Docker build context.
+ shutil.rmtree(target / '.git')
+
+
+def build(app, preview, target, image):
+ config = dict(BuildService.get_app_build_config(app.id) or {})
+ config['app_path'] = str(target)
+ method = config.get('build_method', 'auto')
+ if method == 'auto':
+ method = BuildService.detect_build_method(str(target))['build_method']
+ if method not in ('dockerfile', 'nixpacks'):
+ raise PreviewError('Previews require a Dockerfile or container buildpack; host-command builds are disabled.')
+ config['build_method'] = method
+ relative_file(target, config.get('dockerfile_path') or 'Dockerfile')
+ relative_file(target, 'Dockerfile.serverkit')
+ # Detect the PR's source, not the parent branch's persisted plan. Parent
+ # build secrets are not implicitly handed to PR code.
+ config.pop('buildpack_plan', None)
+ config['build_args'] = {}
+ config['env_vars'] = {}
+ result = BuildService.build_from_config(
+ f'preview-{preview.id}', config, image_tag=image,
+ )
+ if not result.get('success'):
+ raise PreviewError('Preview image build failed. See the preview build logs.')
diff --git a/backend/migrations/versions/111_preview_runtime.py b/backend/migrations/versions/111_preview_runtime.py
new file mode 100644
index 00000000..2518dc85
--- /dev/null
+++ b/backend/migrations/versions/111_preview_runtime.py
@@ -0,0 +1,31 @@
+"""Track preview-owned resources and opt-in environment inheritance."""
+import sqlalchemy as sa
+from alembic import op
+
+revision = '111_preview_runtime'
+down_revision = '110_drop_workflow_schedules_job'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ inspector = sa.inspect(op.get_bind())
+ existing = {c['name'] for c in inspector.get_columns('application_previews')}
+ for name, kind in [('request_token', sa.String(32)), ('requested_action', sa.String(16)),
+ ('runtime_state', sa.Text()), ('error_message', sa.Text())]:
+ if name not in existing:
+ op.add_column('application_previews', sa.Column(name, kind, nullable=True))
+ existing = {c['name'] for c in inspector.get_columns('application_preview_settings')}
+ if 'inherit_environment' not in existing:
+ op.add_column('application_preview_settings', sa.Column(
+ 'inherit_environment', sa.Boolean(), nullable=False, server_default='0'))
+
+
+def downgrade():
+ with op.batch_alter_table('application_preview_settings') as batch:
+ batch.drop_column('inherit_environment')
+ with op.batch_alter_table('application_previews') as batch:
+ batch.drop_column('request_token')
+ batch.drop_column('requested_action')
+ batch.drop_column('error_message')
+ batch.drop_column('runtime_state')
diff --git a/backend/tests/test_generic_previews.py b/backend/tests/test_generic_previews.py
new file mode 100644
index 00000000..cc40d21e
--- /dev/null
+++ b/backend/tests/test_generic_previews.py
@@ -0,0 +1,208 @@
+"""Generic previews: real orchestration with fake external Git/Docker/nginx effects."""
+import json
+from types import SimpleNamespace
+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, source
+from app.services.previews.plan import PreviewError, identity, workspace, validate
+from test_previews import _mk_app
+
+SHA = 'a' * 40
+PR = {'pr_number': 7, 'branch': 'feature/preview', 'commit_sha': SHA}
+
+
+def host(app, monkeypatch, tmp_path):
+ from app.services.git_service import GitService
+ from app.services.build_service import BuildService
+ resources = {'containers': {}, 'images': set(), 'routes': {}, 'calls': []}
+ monkeypatch.setattr(runtime, 'ROOT', tmp_path / 'previews')
+ monkeypatch.setattr(BuildService, 'BUILD_LOG_DIR', str(tmp_path / 'logs'))
+ monkeypatch.setattr(GitService, 'get_app_config', lambda _: {'repo_url': 'https://example.test/repo.git'})
+ def prepare(parent, preview, path, url):
+ resources['calls'].append(('clone', str(path), url))
+ path.mkdir()
+ (path / 'Dockerfile').write_text('FROM scratch')
+ def build(parent, preview, path, image):
+ resources['calls'].append(('build', image))
+ resources['images'].add(image)
+ monkeypatch.setattr(source, 'prepare', prepare)
+ monkeypatch.setattr(source, 'build', build)
+ def run_container(**kwargs):
+ resources['calls'].append(('run', kwargs))
+ name = kwargs['name']
+ resources['containers'][name] = {'Id': name + '-id',
+ 'Config': {'Labels': kwargs['labels']}, 'State': {'Running': True},
+ 'NetworkSettings': {'Ports': {'8400/tcp': [{'HostIp': '127.0.0.1', 'HostPort': '39001'}]}}}
+ return {'success': True, 'container_id': name + '-id'}
+ def inspect(args, **kwargs):
+ kind, _, name = args
+ data = resources['containers'].get(name) if kind == 'container' else ({} if name in resources['images'] else None)
+ if data is None:
+ return {'success': False, 'error': 'No such object'}
+ return {'success': True, 'output': json.dumps([data])}
+ def remove(name, **kwargs):
+ resources['calls'].append(('remove', name, kwargs))
+ resources['containers'].pop(name, None)
+ return {'success': True}
+ def remove_image(name, **kwargs):
+ resources['images'].discard(name)
+ return {'success': True}
+ def publish(name, kind, domains, **kwargs):
+ resources['routes'][name] = domains
+ return {'success': True}
+ def delete(name):
+ resources['routes'].pop(name, None)
+ return {'success': True}
+ monkeypatch.setattr(runtime.DockerService, 'run_container', run_container)
+ monkeypatch.setattr(runtime.DockerService, 'run', inspect)
+ monkeypatch.setattr(runtime.DockerService, 'remove_container', remove)
+ monkeypatch.setattr(runtime.DockerService, 'remove_image', remove_image)
+ monkeypatch.setattr(runtime.NginxService, 'list_sites', lambda: [])
+ monkeypatch.setattr(runtime.NginxService, 'create_site', publish)
+ monkeypatch.setattr(runtime.NginxService, 'disable_site', lambda _: {'success': True})
+ monkeypatch.setattr(runtime.NginxService, 'delete_site', delete)
+ monkeypatch.setattr(runtime.SiteDomainService, 'covering_base', lambda _: None)
+ monkeypatch.setattr(runtime.health_gate, 'gate_for_app', lambda *a, **kw: {'status': 200})
+ with app.app_context():
+ parent = _mk_app(name='generic')
+ parent.container_id = 'production-container'
+ parent.docker_image = 'production:live'
+ db.session.commit()
+ PreviewService.enable_previews(parent.id, {'enabled': True, 'domain_template': 'pr-{pr_number}.test.example'})
+ yield parent, resources
+
+
+def test_create_redeploy_destroy_are_isolated_and_idempotent(host):
+ parent, resources = host
+ first = PreviewService.create_preview(parent, PR)
+ assert first['status'] == 'running', first
+ assert first['url'] == 'http://pr-7.test.example'
+ old_ids = first['container_ids']
+ call = next(c[1] for c in resources['calls'] if c[0] == 'run')
+ assert call['ports'] == ['127.0.0.1::8400']
+ assert 'volumes' not in call and 'network' not in call
+ assert call['env'] == {'SERVERKIT_PREVIEW': 'true', 'SERVERKIT_PR_NUMBER': '7', 'SERVERKIT_PREVIEW_BRANCH': 'feature/preview'}
+ second = PreviewService.create_preview(parent, {**PR, 'commit_sha': 'b' * 40})
+ assert second['status'] == 'running'
+ assert second['id'] == first['id'] and second['container_ids'] != old_ids
+ assert len(resources['containers']) == len(resources['images']) == len(resources['routes']) == 1
+ result = PreviewService.destroy_preview(first['id'])
+ assert result['status'] == 'destroyed'
+ assert not resources['containers'] and not resources['images'] and not resources['routes']
+ assert not list(runtime.ROOT.iterdir())
+ assert PreviewService.destroy_preview(first['id'])['status'] == 'destroyed'
+ db.session.refresh(parent)
+ assert parent.container_id == 'production-container'
+ assert parent.docker_image == 'production:live' and parent.port == 8400
+
+
[email protected]('failure', ['clone', 'build', 'start', 'health', 'route'])
+def test_each_failure_compensates_owned_resources(host, monkeypatch, failure):
+ parent, resources = host
+ def fail(*args, **kwargs):
+ raise RuntimeError('secret-diagnostic-do-not-expose')
+ owner, attr = {'clone': (source, 'prepare'), 'build': (source, 'build'),
+ 'start': (runtime, 'start'), 'health': (runtime.health_gate, 'gate_for_app'),
+ 'route': (runtime, 'publish')}[failure]
+ monkeypatch.setattr(owner, attr, fail)
+ result = PreviewService.create_preview(parent, PR)
+ assert result['status'] == 'failed' and result['url'] is None
+ assert 'secret-diagnostic' not in str(result)
+ assert not resources['containers'] and not resources['images'] and not resources['routes']
+ row = db.session.get(ApplicationPreview, result['id'])
+ assert row.get_runtime_state() == {}
+
+
+def test_cleanup_failure_preserves_journal_and_retry_succeeds(host, monkeypatch):
+ parent, resources = host
+ result = PreviewService.create_preview(parent, PR)
+ remove = runtime.DockerService.remove_container
+ monkeypatch.setattr(runtime.DockerService, 'remove_container', lambda *a, **kw: {'success': False})
+ failed = PreviewService.destroy_preview(result['id'])
+ assert failed.get('error')
+ row = db.session.get(ApplicationPreview, result['id'])
+ assert row.status == 'failed' and row.deleted_at is None
+ assert row.get_runtime_state()['container'] is True
+ assert resources['containers']
+ monkeypatch.setattr(runtime.DockerService, 'remove_container', remove)
+ assert PreviewService.destroy_preview(result['id'])['status'] == 'destroyed'
+ assert not resources['containers']
+
+
+def test_domain_conflict_prevents_host_effects(host):
+ from app.models import Domain
+ parent, resources = host
+ db.session.add(Domain(name='pr-7.test.example', application_id=parent.id))
+ db.session.commit()
+ result = PreviewService.create_preview(parent, PR)
+ assert result['status'] == 'failed'
+ assert not resources['calls']
+
+
+def test_unsupported_target_and_bad_ref_do_not_provision(host):
+ parent, resources = host
+ parent.compose_file = 'compose.yml'
+ db.session.commit()
+ assert PreviewService.create_preview(parent, PR)['status'] == 'failed'
+ parent.compose_file = None
+ db.session.commit()
+ assert PreviewService.create_preview(parent, {**PR, 'commit_sha': '--bad'})['status'] == 'failed'
+ assert not resources['calls']
+
+
+def test_unknown_provider_does_not_destroy_existing_previews(host):
+ parent, resources = host
+ result = PreviewService.create_preview(parent, PR)
+ assert PreviewService.sync_previews(parent.id).get('error')
+ assert db.session.get(ApplicationPreview, result['id']).status == 'running'
+ assert resources['containers']
+
+
+def test_cleanup_rejects_missing_ownership(host):
+ parent, resources = host
+ result = PreviewService.create_preview(parent, PR)
+ next(iter(resources['containers'].values()))['Config']['Labels'] = {}
+ assert PreviewService.destroy_preview(result['id']).get('error')
+ assert resources['containers']
+
+
+def test_close_supersedes_queued_create_before_row_has_runtime(host, monkeypatch):
+ from app.services.previews.requests import enqueue
+ from app.jobs.service import JobService
+ parent, resources = host
+ jobs = []
+ def capture(kind, payload, **kwargs):
+ job = SimpleNamespace(kind=kind, get_payload=lambda: payload)
+ jobs.append(job)
+ return job
+ monkeypatch.setattr(JobService, 'enqueue', capture)
+ enqueue(parent.id, PR)
+ enqueue(parent.id, PR, action='destroy')
+ assert PreviewService._job_create(jobs[0])['reason'] == 'superseded'
+ assert PreviewService._job_destroy(jobs[1])['status'] == 'destroyed'
+ assert not resources['calls']
+
+
+def test_close_during_build_cleans_up_without_publishing(host, monkeypatch):
+ from app.services.previews.requests import enqueue
+ from app.jobs.service import JobService
+ parent, resources = host
+ monkeypatch.setattr(JobService, 'enqueue', lambda *a, **kw: None)
+ original = source.build
+ def build(*args):
+ original(*args)
+ enqueue(parent.id, PR, action='destroy')
+ monkeypatch.setattr(source, 'build', build)
+ result = PreviewService.create_preview(parent, PR)
+ assert result['status'] == 'failed'
+ assert not resources['routes'] and not resources['containers']
+
+
+def test_cleanup_paths_cannot_escape(tmp_path):
+ with pytest.raises(PreviewError):
+ workspace(tmp_path, 1, '../escape')
+ with pytest.raises(PreviewError):
+ identity(-1, 'a' * 32)
diff --git a/backend/tests/test_previews.py b/backend/tests/test_previews.py
index 6da064d2..69126e7c 100644
--- a/backend/tests/test_previews.py
+++ b/backend/tests/test_previews.py
@@ -156,12 +156,12 @@ def test_create_and_destroy_writes_rows_and_flips_status(app):
'pr_title': 'Add X',
})
assert created.get('pr_number') == 12
- assert created.get('status') == ApplicationPreview.STATUS_UNAVAILABLE
+ assert created.get('status') == ApplicationPreview.STATUS_FAILED
assert created['url'] is None
assert created.get('domain') # a domain was rendered
row = ApplicationPreview.query.filter_by(application_id=a.id, pr_number=12).first()
- assert row is not None and row.status == ApplicationPreview.STATUS_UNAVAILABLE
+ assert row is not None and row.status == ApplicationPreview.STATUS_FAILED
destroyed = PreviewService.destroy_preview(row.id)
assert destroyed.get('status') == ApplicationPreview.STATUS_DESTROYED