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(manifest): apply engine — resolve/plan/apply + core domain attach (Phase 2)

Juan Denis315c80e9a0fb
diff --git a/backend/app/api/manifests.py b/backend/app/api/manifests.py
index 8dd70907..79af5d7c 100644
--- a/backend/app/api/manifests.py
+++ b/backend/app/api/manifests.py
@@ -8,14 +8,40 @@ audit-logged.
from flask import Blueprint, jsonify, request, Response
from flask_jwt_extended import jwt_required, get_jwt_identity
+from app import db
from app.models.application import Application
+from app.models.application_manifest import ApplicationManifest, STATUS_PENDING
+from app.models.project import Project
from app.models.user import User
from app.services.manifest_scaffold_service import ManifestScaffoldService
from app.services.manifest_spec_service import ManifestSpecService, ManifestError
+from app.services.manifest_apply_service import ManifestApplyService
+from app.services.manifest_persistence_service import ManifestPersistenceService
manifests_bp = Blueprint('manifests', __name__)
+def _load_normalized(data):
+ """Normalize from an inline body, or fall back to the project's stored row.
+ Returns (normalized, raw_text, error_response_or_None)."""
+ if 'content' in data:
+ try:
+ return ManifestSpecService.normalize_text(data['content']), data['content'], None
+ except ManifestError as exc:
+ return None, None, (jsonify({'error': 'Invalid manifest', 'errors': exc.errors}), 400)
+ if 'manifest' in data:
+ try:
+ return ManifestSpecService.normalize(data['manifest']), None, None
+ except ManifestError as exc:
+ return None, None, (jsonify({'error': 'Invalid manifest', 'errors': exc.errors}), 400)
+ # fall back to the stored manifest for the project
+ project_id = data.get('project_id')
+ row = ApplicationManifest.query.filter_by(project_id=project_id).first() if project_id else None
+ if row and row.get_normalized():
+ return row.get_normalized(), row.raw_text, None
+ return None, None, (jsonify({'error': 'Provide `content`/`manifest`, or store one first'}), 400)
+
+
def _require_admin():
user = User.query.get(get_jwt_identity())
if not user or user.role != 'admin':
@@ -73,3 +99,76 @@ def validate_manifest():
'summary': ManifestSpecService.summarize(normalized),
'normalized': normalized,
}), 200
+
+
+@manifests_bp.route('', methods=['GET'])
+@jwt_required()
+def get_manifest():
+ """GET /api/v1/manifests?project_id= -> the stored manifest for a project."""
+ user, err = _require_admin()
+ if err:
+ return err
+ project_id = request.args.get('project_id', type=int)
+ if not project_id:
+ return jsonify({'error': 'project_id is required'}), 400
+ row = ApplicationManifest.query.filter_by(project_id=project_id).first()
+ if not row:
+ return jsonify({'manifest': None}), 200
+ return jsonify({'manifest': row.to_dict(include_raw=True)}), 200
+
+
+@manifests_bp.route('/plan', methods=['POST'])
+@jwt_required()
+def plan_manifest():
+ """POST /api/v1/manifests/plan {project_id, content|manifest?} -> dry-run plan."""
+ user, err = _require_admin()
+ if err:
+ return err
+ data = request.get_json(silent=True) or {}
+ project = Project.query.get(data.get('project_id')) if data.get('project_id') else None
+ if not project:
+ return jsonify({'error': 'A valid project_id is required'}), 400
+
+ normalized, _raw, err_resp = _load_normalized(data)
+ if err_resp:
+ return err_resp
+
+ plan = ManifestApplyService.plan(project, normalized)
+ return jsonify({'plan': plan}), 200
+
+
+@manifests_bp.route('/apply', methods=['POST'])
+@jwt_required()
+def apply_manifest():
+ """POST /api/v1/manifests/apply {project_id, content|manifest?} -> apply."""
+ user, err = _require_admin()
+ if err:
+ return err
+ data = request.get_json(silent=True) or {}
+ project = Project.query.get(data.get('project_id')) if data.get('project_id') else None
+ if not project:
+ return jsonify({'error': 'A valid project_id is required'}), 400
+
+ normalized, raw, err_resp = _load_normalized(data)
+ if err_resp:
+ return err_resp
+
+ # persist/refresh the manifest row (pending) before applying
+ row = ManifestPersistenceService.store_manifest(
+ project_id=project.id, normalized=normalized, raw_text=raw, status=STATUS_PENDING)
+ db.session.commit()
+
+ result = ManifestApplyService.apply(project, normalized, user_id=user.id,
+ manifest_row=row)
+
+ try:
+ from app.services.audit_service import AuditService
+ AuditService.log('manifest.apply', user_id=user.id, target_type='project',
+ target_id=project.id,
+ details={'success': result['success'], 'applied': result['applied'],
+ 'job_id': result['job_id']})
+ except Exception:
+ pass
+
+ status = 200 if result['success'] else 207
+ return jsonify(result), status
diff --git a/backend/app/services/domain_attach_service.py b/backend/app/services/domain_attach_service.py
new file mode 100644
index 00000000..31de4ae7
--- /dev/null
+++ b/backend/app/services/domain_attach_service.py
@@ -0,0 +1,159 @@
+"""Attach a custom domain to any managed app, end to end.
+
+This generalizes the WordPress "one-call attach a custom domain" pattern
+(``wordpress_service.attach_custom_domain``) so plain apps (docker, python,
+php, static) can use the same DNS + vhost + optional-SSL flow.
+
+The public entry point is :meth:`DomainAttachService.attach`. Every external
+stage (DNS provider API, nginx vhost write, certbot) degrades to a *warning*
+and never raises — HTTPS is optional in ServerKit and a certificate failure
+must never block the domain attach. The idempotent Domain row is the only
+hard requirement; everything after it is best-effort.
+
+Stateless — all classmethods, no instance state — matching the repo style.
+"""
+import os
+from typing import Dict, Optional
+
+from app import db
+from app.models.domain import Domain
+from app.services.site_domain_service import SiteDomainService
+from app.services.dns_provider_service import DNSProviderService
+
+
+class DomainAttachService:
+ """Point a user-owned domain at a managed app in one call."""
+
+ @staticmethod
+ def _normalize_host(host: str) -> str:
+ """Reduce a bare host or a full URL down to a lowercase hostname."""
+ h = (host or '').strip().lower()
+ if '://' in h:
+ h = h.split('://', 1)[1]
+ h = h.split('/', 1)[0].split(':', 1)[0]
+ return h.strip().strip('.').rstrip('.')
+
+ @classmethod
+ def attach(cls, app, host: str, ssl: str = 'auto',
+ email: Optional[str] = None, make_primary: bool = False) -> Dict:
+ """Attach ``host`` to ``app``: record the Domain, ensure DNS, publish the
+ vhost, and optionally obtain a certificate.
+
+ Args:
+ app: the ``Application`` row to attach the domain to.
+ host: the custom hostname (bare host or full URL).
+ ssl: ``'auto'``/``'on'``/``True`` obtains a certificate best-effort;
+ ``'off'``/``False`` skips SSL entirely.
+ email: ACME account email (defaults to ``admin@<host>``).
+ make_primary: when true, make this the app's primary domain
+ (unsetting any existing primary first).
+
+ Returns a dict with the EXACT shape the manifest applier consumes::
+
+ {'success': True, 'domain': host, 'created': bool,
+ 'dns': <ensure_a_record result>,
+ 'ssl': {'enabled': bool, 'error'?: str},
+ 'warnings': [str, ...]}
+
+ or ``{'success': False, 'error': msg}`` on an invalid host / DB failure.
+ """
+ if not app:
+ return {'success': False, 'error': 'An application is required'}
+
+ host = cls._normalize_host(host)
+ if not host or '.' not in host:
+ return {'success': False, 'error': 'A valid custom domain (e.g. example.com) is required'}
+
+ warnings = []
+
+ # 1) Idempotent Domain row (create if missing, honor make_primary).
+ try:
+ domain = Domain.query.filter_by(name=host, application_id=app.id).first()
+ created = domain is None
+ if make_primary:
+ Domain.query.filter_by(application_id=app.id, is_primary=True).update(
+ {'is_primary': False})
+ if domain is None:
+ # Guard against the host being claimed by a *different* app —
+ # `name` is globally unique, so we can't silently steal it.
+ clash = Domain.query.filter_by(name=host).first()
+ if clash and clash.application_id != app.id:
+ return {'success': False,
+ 'error': f'{host} is already attached to another app'}
+ domain = Domain(name=host, is_primary=bool(make_primary),
+ application_id=app.id)
+ db.session.add(domain)
+ elif make_primary:
+ domain.is_primary = True
+ db.session.flush()
+ except Exception as e:
+ db.session.rollback()
+ return {'success': False, 'error': f'Could not record domain: {e}'}
+
+ # 2) DNS: auto-create the A record best-effort (or report what to add).
+ dns = None
+ try:
+ dns = DNSProviderService.ensure_a_record(host, SiteDomainService.server_ip())
+ if dns and not dns.get('created'):
+ warnings.append(dns.get('message')
+ or f'Add the {host} A record manually.')
+ except Exception as e:
+ warnings.append(f'DNS auto-config skipped: {e}')
+
+ # 3) Publish the vhost so the host is actually served. Linux-only —
+ # on a Windows dev box nginx is unavailable, so skip with a warning
+ # rather than crashing.
+ if os.name == 'nt':
+ warnings.append('nginx vhost not written (not a Linux host).')
+ else:
+ try:
+ v = SiteDomainService.write_app_vhost(app)
+ if v and v.get('warning'):
+ warnings.append(v['warning'])
+ except Exception as e:
+ warnings.append(f'nginx vhost not written: {e}')
+
+ # 4) Optional HTTPS. Best-effort — a cert failure never fails the attach.
+ ssl_result = {'enabled': False}
+ want_ssl = ssl in ('auto', 'on', True)
+ if want_ssl:
+ try:
+ from app.services.ssl_service import SSLService
+ from app.services.nginx_service import NginxService
+ cert = SSLService.obtain_certificate([host], email or f'admin@{host}')
+ if cert and cert.get('success'):
+ domain.ssl_enabled = True
+ domain.ssl_certificate_path = cert.get('certificate_path')
+ domain.ssl_key_path = cert.get('private_key_path')
+ ssl_result['enabled'] = True
+ try:
+ NginxService.add_ssl_to_site(
+ app.name, cert.get('certificate_path'),
+ cert.get('private_key_path'))
+ except Exception as e:
+ warnings.append(f'certificate issued but nginx SSL wiring failed: {e}')
+ else:
+ err = (cert or {}).get('error') or 'certificate request failed'
+ ssl_result['error'] = err
+ warnings.append(
+ 'HTTPS is not set up yet — enable SSL once DNS has '
+ f'propagated to this server ({err}).')
+ except Exception as e:
+ ssl_result['error'] = str(e)
+ warnings.append(f'HTTPS is not set up yet: {e}')
+
+ # 5) Commit the Domain row (row + any SSL fields).
+ try:
+ db.session.commit()
+ except Exception as e:
+ db.session.rollback()
+ return {'success': False, 'error': f'Could not save domain: {e}'}
+
+ return {
+ 'success': True,
+ 'domain': host,
+ 'created': created,
+ 'dns': dns,
+ 'ssl': ssl_result,
+ 'warnings': warnings,
+ }
diff --git a/backend/app/services/manifest_apply_service.py b/backend/app/services/manifest_apply_service.py
new file mode 100644
index 00000000..34d2a0f1
--- /dev/null
+++ b/backend/app/services/manifest_apply_service.py
@@ -0,0 +1,570 @@
+"""The manifest apply engine (plan 17, Phase 2).
+
+resolve → plan → apply. Turns a normalized v1 manifest into an ordered action
+plan and executes it through the existing imperative services, inside a
+DeploymentJob for logging + before/after snapshots. Single-server for now;
+Phase 5 adds fleet targeting.
+
+`plan()` is pure enough to be a dry-run (no writes). `apply()` executes and is
+idempotent — a second plan against a just-applied manifest is empty.
+"""
+
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+from app import db
+from app.models.application import Application
+from app.models.application_manifest import (
+ ApplicationManifest, STATUS_APPLIED, STATUS_ERROR,
+)
+from app.models.domain import Domain
+from app.models.environment import Environment
+from app.models.managed_database import ManagedDatabase
+from app.models.project import Project
+
+
+# manifest backup schedule -> cron
+_SCHEDULE_CRON = {
+ 'hourly': '0 * * * *',
+ 'daily': '0 2 * * *',
+ 'weekly': '0 3 * * 0',
+ 'monthly': '0 4 1 * *',
+}
+
+# db engines the managed-database layer can actually record
+_MANAGED_DB_ENGINES = {'postgresql', 'mysql'}
+
+# ordering weight per step type (dbs before consumers; domains last)
+_STEP_ORDER = {
+ 'provision_db': 0,
+ 'warn': 1,
+ 'create_app': 2,
+ 'update_app': 3,
+ 'set_env': 4,
+ 'ensure_volume': 5,
+ 'upsert_backup_policy': 6,
+ 'attach_domain': 7,
+}
+
+
+class ManifestApplyService:
+
+ # -- resolve (#7) -------------------------------------------------------
+
+ @classmethod
+ def resolve_service(cls, svc: Dict[str, Any]) -> Dict[str, Any]:
+ """Normalized manifest service -> desired-state dict."""
+ literal_env: Dict[str, Any] = {}
+ env_refs: List[Dict[str, Any]] = []
+ for var in svc.get('env_vars', []):
+ if var['source'] == 'value':
+ literal_env[var['key']] = var['value']
+ else:
+ env_refs.append(var)
+ return {
+ 'name': svc['name'],
+ 'kind': svc['kind'],
+ 'app_type': svc.get('app_type'),
+ 'db_engine': svc.get('db_engine'),
+ 'engine_version': svc.get('engine_version'),
+ 'runtime': svc.get('runtime'),
+ 'port': svc.get('port'),
+ 'healthcheck_path': svc.get('healthcheck_path'),
+ 'build_command': svc.get('build_command'),
+ 'start_command': svc.get('start_command'),
+ 'cpu': cls._stringify(svc.get('cpu')),
+ 'memory': cls._stringify(svc.get('memory')),
+ 'auto_deploy': svc.get('auto_deploy', False),
+ 'env': literal_env,
+ 'env_refs': env_refs,
+ 'disks': svc.get('disks', []),
+ 'server': svc.get('server'),
+ }
+
+ # -- plan (#8) ----------------------------------------------------------
+
+ @classmethod
+ def plan(cls, project: Project, normalized: Dict[str, Any],
+ environment: Optional[Environment] = None) -> Dict[str, Any]:
+ """Diff desired manifest vs live state -> ordered action plan."""
+ env = environment or cls._default_environment(project)
+ steps: List[Dict[str, Any]] = []
+
+ services = normalized.get('services', [])
+ for svc in services:
+ resolved = cls.resolve_service(svc)
+ if resolved['kind'] == 'database':
+ steps.extend(cls._plan_db(resolved))
+ else:
+ steps.extend(cls._plan_app(project, env, resolved))
+
+ steps.extend(cls._plan_domains(project, normalized.get('domains', [])))
+
+ steps.sort(key=lambda s: (_STEP_ORDER.get(s['type'], 99), s.get('service') or ''))
+ return {
+ 'project_id': project.id,
+ 'environment_id': env.id if env else None,
+ 'steps': steps,
+ 'step_count': len(steps),
+ 'summary': cls._summarize_plan(steps),
+ }
+
+ @classmethod
+ def _plan_db(cls, resolved: Dict[str, Any]) -> List[Dict[str, Any]]:
+ engine = resolved['db_engine']
+ name = resolved['name']
+ if engine not in _MANAGED_DB_ENGINES:
+ return [{
+ 'type': 'warn', 'service': name,
+ 'description': f'{engine or resolved.get("app_type")} databases are not '
+ f'managed by ServerKit yet — declared but not provisioned',
+ 'payload': {},
+ }]
+ existing = ManagedDatabase.query.filter_by(engine=engine, name=name).first()
+ steps: List[Dict[str, Any]] = []
+ if not existing:
+ steps.append({
+ 'type': 'provision_db', 'service': name,
+ 'description': f'Provision {engine} database `{name}`',
+ 'payload': {'engine': engine, 'name': name,
+ 'version': resolved.get('engine_version')},
+ })
+ # backup declaration on the db's single disk
+ for disk in resolved.get('disks', []):
+ backup = disk.get('backup')
+ if backup and not cls._backup_policy_current(
+ 'database', existing.id if existing else None, backup):
+ steps.append(cls._db_backup_step(name, engine, backup, exists=bool(existing)))
+ return steps
+
+ @classmethod
+ def _plan_app(cls, project: Project, env: Optional[Environment],
+ resolved: Dict[str, Any]) -> List[Dict[str, Any]]:
+ steps: List[Dict[str, Any]] = []
+ name = resolved['name']
+ app = cls._find_app(project, name)
+
+ if app is None:
+ payload = {k: resolved[k] for k in
+ ('app_type', 'port', 'healthcheck_path', 'runtime',
+ 'build_command', 'start_command', 'cpu', 'memory')}
+ payload['name'] = name
+ steps.append({
+ 'type': 'create_app', 'service': name,
+ 'description': f'Create app `{name}` ({resolved["app_type"]})',
+ 'payload': payload,
+ })
+ else:
+ changes = cls._app_field_changes(app, resolved)
+ if changes:
+ steps.append({
+ 'type': 'update_app', 'service': name,
+ 'description': f'Update app `{name}`: ' + ', '.join(changes.keys()),
+ 'payload': {'app_id': app.id, 'changes': changes},
+ })
+
+ # env (literal values only; references bind in Phase 3)
+ desired_env = resolved['env']
+ if desired_env:
+ live_env = cls._live_env(app) if app else {}
+ missing = {k: v for k, v in desired_env.items() if str(live_env.get(k)) != str(v)}
+ if missing or app is None:
+ to_set = desired_env if app is None else missing
+ if to_set:
+ steps.append({
+ 'type': 'set_env', 'service': name,
+ 'description': f'Set {len(to_set)} env var(s) on `{name}`',
+ 'payload': {'app_id': app.id if app else None, 'env': to_set},
+ })
+
+ # disks
+ for disk in resolved.get('disks', []):
+ mount = disk.get('mount_path')
+ if not mount:
+ continue
+ has_vol = bool(app) and any(v.mount_path == mount for v in (app.volumes or []))
+ if not has_vol:
+ steps.append({
+ 'type': 'ensure_volume', 'service': name,
+ 'description': f'Ensure volume `{disk.get("name") or mount}` on `{name}`',
+ 'payload': {'app_id': app.id if app else None,
+ 'name': disk.get('name') or cls._slug(mount),
+ 'mount_path': mount, 'size': disk.get('size')},
+ })
+ backup = disk.get('backup')
+ if backup and not cls._backup_policy_current(
+ 'files', app.id if app else None, backup):
+ steps.append(cls._files_backup_step(name, app, mount, backup))
+
+ return steps
+
+ @classmethod
+ def _plan_domains(cls, project: Project, domains: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+ steps = []
+ for dom in domains:
+ host = dom.get('host')
+ svc_name = dom.get('service')
+ app = cls._find_app(project, svc_name) if svc_name else None
+ already = bool(app) and any(d.name == host for d in (app.domains or []))
+ if already:
+ continue
+ steps.append({
+ 'type': 'attach_domain', 'service': svc_name,
+ 'description': f'Attach domain `{host}`'
+ + (f' to `{svc_name}`' if svc_name else ''),
+ 'payload': {'host': host, 'service': svc_name, 'ssl': dom.get('ssl', 'auto'),
+ 'app_id': app.id if app else None},
+ })
+ return steps
+
+ @classmethod
+ def _db_backup_step(cls, name, engine, backup, exists):
+ return {
+ 'type': 'upsert_backup_policy', 'service': name,
+ 'description': f'Backup policy for db `{name}` ({backup["schedule"]})',
+ 'payload': {'target': 'database', 'engine': engine, 'db_name': name,
+ 'schedule': backup['schedule'], 'retain': backup['retain']},
+ }
+
+ @classmethod
+ def _files_backup_step(cls, name, app, mount, backup):
+ return {
+ 'type': 'upsert_backup_policy', 'service': name,
+ 'description': f'Backup policy for disk `{mount}` on `{name}` ({backup["schedule"]})',
+ 'payload': {'target': 'files', 'app_id': app.id if app else None,
+ 'mount_path': mount, 'schedule': backup['schedule'],
+ 'retain': backup['retain']},
+ }
+
+ # -- apply (#9) ---------------------------------------------------------
+
+ @classmethod
+ def apply(cls, project: Project, normalized: Dict[str, Any],
+ user_id: Optional[int] = None,
+ environment: Optional[Environment] = None,
+ manifest_row: Optional[ApplicationManifest] = None) -> Dict[str, Any]:
+ """Execute the plan inside a DeploymentJob with before/after snapshots."""
+ env = environment or cls._default_environment(project)
+ plan = cls.plan(project, normalized, env)
+ job = cls._create_job(project, user_id, plan)
+
+ cls._snapshot_existing(project, normalized, tag='before')
+
+ results = []
+ failed = False
+ for idx, step in enumerate(plan['steps']):
+ if failed:
+ results.append({**cls._step_ref(step), 'status': 'skipped'})
+ continue
+ try:
+ outcome = cls._execute_step(project, env, step, user_id)
+ results.append({**cls._step_ref(step), 'status': 'ok', 'result': outcome})
+ cls._log(job, idx, 'info', step['description'], outcome)
+ except Exception as exc: # stop the plan, report per-step
+ failed = True
+ results.append({**cls._step_ref(step), 'status': 'error', 'error': str(exc)})
+ cls._log(job, idx, 'error', f'{step["description"]}: {exc}')
+
+ cls._snapshot_existing(project, normalized, tag='after')
+
+ cls._finish_job(job, failed, results)
+ if manifest_row is not None:
+ manifest_row.status = STATUS_ERROR if failed else STATUS_APPLIED
+ if not failed:
+ manifest_row.applied_at = datetime.utcnow()
+ manifest_row.last_error = None
+ else:
+ manifest_row.last_error = next(
+ (r.get('error') for r in results if r.get('status') == 'error'), None)
+ db.session.commit()
+
+ return {
+ 'success': not failed,
+ 'job_id': job.id,
+ 'applied': sum(1 for r in results if r['status'] == 'ok'),
+ 'results': results,
+ 'plan': plan,
+ }
+
+ @classmethod
+ def _execute_step(cls, project, env, step, user_id) -> Dict[str, Any]:
+ stype = step['type']
+ # thread the step's service name into the payload so handlers can resolve
+ # an app that was created earlier in the same apply (app_id was None at
+ # plan time for brand-new services).
+ payload = dict(step.get('payload', {}))
+ payload.setdefault('service', step.get('service'))
+ handler = getattr(cls, f'_do_{stype}', None)
+ if handler is None:
+ return {'noop': True}
+ return handler(project, env, payload, user_id) or {}
+
+ # -- step handlers ------------------------------------------------------
+
+ @classmethod
+ def _do_warn(cls, project, env, payload, user_id):
+ return {'warned': True}
+
+ @classmethod
+ def _do_provision_db(cls, project, env, payload, user_id):
+ from app.services.managed_database_service import ManagedDatabaseService
+ managed = ManagedDatabaseService.record_provisioned(
+ engine=payload['engine'], name=payload['name'],
+ workspace_id=project.workspace_id,
+ )
+ return {'managed_database_id': managed.id}
+
+ @classmethod
+ def _do_create_app(cls, project, env, payload, user_id):
+ import json
+ overrides = {}
+ if payload.get('build_command'):
+ overrides['build_command'] = payload['build_command']
+ if payload.get('start_command'):
+ overrides['start_command'] = payload['start_command']
+ app = Application(
+ name=payload['name'],
+ app_type=payload.get('app_type') or 'docker',
+ status='stopped',
+ port=payload.get('port'),
+ healthcheck_path=payload.get('healthcheck_path'),
+ cpu_limit=payload.get('cpu'),
+ memory_limit=payload.get('memory'),
+ buildpack_overrides=json.dumps(overrides) if overrides else None,
+ source='manifest',
+ user_id=user_id,
+ project_id=project.id,
+ environment_id=env.id if env else None,
+ )
+ db.session.add(app)
+ db.session.commit()
+ return {'app_id': app.id}
+
+ @classmethod
+ def _do_update_app(cls, project, env, payload, user_id):
+ import json
+ app = Application.query.get(payload['app_id'])
+ if not app:
+ raise RuntimeError('app not found')
+ changes = payload['changes']
+ if 'port' in changes:
+ app.port = changes['port']
+ if 'healthcheck_path' in changes:
+ app.healthcheck_path = changes['healthcheck_path']
+ if 'cpu' in changes:
+ app.cpu_limit = changes['cpu']
+ if 'memory' in changes:
+ app.memory_limit = changes['memory']
+ if 'build_command' in changes or 'start_command' in changes:
+ overrides = {}
+ if app.buildpack_overrides:
+ try:
+ overrides = json.loads(app.buildpack_overrides) or {}
+ except Exception:
+ overrides = {}
+ if 'build_command' in changes:
+ overrides['build_command'] = changes['build_command']
+ if 'start_command' in changes:
+ overrides['start_command'] = changes['start_command']
+ app.buildpack_overrides = json.dumps(overrides)
+ db.session.commit()
+ return {'app_id': app.id, 'changed': list(changes.keys())}
+
+ @classmethod
+ def _do_set_env(cls, project, env, payload, user_id):
+ from app.services.env_service import EnvService
+ app_id = payload.get('app_id') or cls._resolve_app_id(project, payload)
+ count, errors = EnvService.bulk_set_env_vars(app_id, payload['env'], user_id)
+ if errors:
+ raise RuntimeError('; '.join(errors))
+ return {'set': count}
+
+ @classmethod
+ def _do_ensure_volume(cls, project, env, payload, user_id):
+ from app.services.volume_service import VolumeService
+ app = Application.query.get(payload.get('app_id') or cls._resolve_app_id(project, payload))
+ if not app:
+ raise RuntimeError('app not found')
+ if any(v.mount_path == payload['mount_path'] for v in (app.volumes or [])):
+ return {'exists': True}
+ vol = VolumeService.create(app, payload['name'], payload['mount_path'])
+ return {'volume_id': getattr(vol, 'id', None)}
+
+ @classmethod
+ def _do_upsert_backup_policy(cls, project, env, payload, user_id):
+ from app.services.backup_policy_service import BackupPolicyService
+ schedule_cron = _SCHEDULE_CRON.get(payload['schedule'], '0 2 * * *')
+ fields = {'enabled': True, 'schedule_cron': schedule_cron,
+ 'retention_count': payload['retain']}
+ if payload['target'] == 'database':
+ from app.services.managed_database_service import ManagedDatabaseService
+ managed = ManagedDatabase.query.filter_by(
+ engine=payload['engine'], name=payload['db_name']).first()
+ if not managed:
+ raise RuntimeError('managed database not found for backup policy')
+ ManagedDatabaseService.protect(managed, fields=fields)
+ return {'policy': 'database', 'db': payload['db_name']}
+ # files
+ app_id = payload.get('app_id') or cls._resolve_app_id(project, payload)
+ policy = BackupPolicyService.get_or_create_policy(
+ target_type='files', target_id=app_id, target_subtype='pathlist',
+ target_meta={'paths': [payload['mount_path']], 'managed_by': 'manifest'})
+ BackupPolicyService.update_policy(policy, fields)
+ return {'policy': 'files', 'policy_id': policy.id}
+
+ @classmethod
+ def _do_attach_domain(cls, project, env, payload, user_id):
+ from app.services.domain_attach_service import DomainAttachService
+ app_id = payload.get('app_id') or (
+ cls._resolve_app_id(project, payload) if payload.get('service') else None)
+ if not app_id:
+ return {'skipped': 'no target service'}
+ app = Application.query.get(app_id)
+ if not app:
+ raise RuntimeError('app not found for domain')
+ result = DomainAttachService.attach(app, payload['host'], ssl=payload.get('ssl', 'auto'))
+ return result
+
+ # -- snapshots + job ----------------------------------------------------
+
+ @classmethod
+ def _snapshot_existing(cls, project, normalized, tag):
+ from app.services.configuration_service import ConfigurationService
+ for svc in normalized.get('services', []):
+ if svc['kind'] != 'app':
+ continue
+ app = cls._find_app(project, svc['name'])
+ if app is None:
+ continue
+ try:
+ ConfigurationService.create_snapshot(app)
+ except Exception:
+ db.session.rollback()
+
+ @classmethod
+ def _create_job(cls, project, user_id, plan):
+ from app.models.deployment_job import DeploymentJob
+ job = DeploymentJob(
+ id=str(uuid.uuid4()), kind='manifest.apply', status='running',
+ requested_by=user_id, trigger='manual', started_at=datetime.utcnow(),
+ )
+ job.set_plan({'steps': plan['steps']})
+ job.total_steps = plan['step_count']
+ db.session.add(job)
+ db.session.commit()
+ return job
+
+ @classmethod
+ def _finish_job(cls, job, failed, results):
+ job.status = 'failed' if failed else 'succeeded'
+ job.completed_at = datetime.utcnow()
+ job.current_step = sum(1 for r in results if r['status'] in ('ok', 'error'))
+ job.set_result({'results': results})
+ db.session.commit()
+
+ @classmethod
+ def _log(cls, job, idx, level, message, data=None):
+ # Best-effort per-step log. Wrapped in a savepoint so a logging failure
+ # (e.g. SQLite BigInteger PK) never poisons the apply transaction. The
+ # authoritative per-step record also lives in job.result.
+ from app.models.deployment_job import DeploymentJobLog
+ import json
+ try:
+ with db.session.begin_nested():
+ db.session.add(DeploymentJobLog(
+ job_id=job.id, step_index=idx, level=level, message=message,
+ data=json.dumps(data) if data else None))
+ except Exception:
+ pass
+
+ # -- helpers ------------------------------------------------------------
+
+ @classmethod
+ def _app_field_changes(cls, app: Application, resolved: Dict[str, Any]) -> Dict[str, Any]:
+ import json
+ changes = {}
+ if resolved.get('port') is not None and app.port != resolved['port']:
+ changes['port'] = resolved['port']
+ if resolved.get('healthcheck_path') and app.healthcheck_path != resolved['healthcheck_path']:
+ changes['healthcheck_path'] = resolved['healthcheck_path']
+ if resolved.get('cpu') and app.cpu_limit != resolved['cpu']:
+ changes['cpu'] = resolved['cpu']
+ if resolved.get('memory') and app.memory_limit != resolved['memory']:
+ changes['memory'] = resolved['memory']
+ overrides = {}
+ if app.buildpack_overrides:
+ try:
+ overrides = json.loads(app.buildpack_overrides) or {}
+ except Exception:
+ overrides = {}
+ if resolved.get('build_command') and overrides.get('build_command') != resolved['build_command']:
+ changes['build_command'] = resolved['build_command']
+ if resolved.get('start_command') and overrides.get('start_command') != resolved['start_command']:
+ changes['start_command'] = resolved['start_command']
+ return changes
+
+ @classmethod
+ def _backup_policy_current(cls, target_type: str, target_id: Optional[int],
+ backup: Dict[str, Any]) -> bool:
+ """True when an enabled policy already matches the declared schedule/retain."""
+ if not target_id:
+ return False
+ from app.models.backup_policy import BackupPolicy
+ pol = BackupPolicy.query.filter_by(
+ target_type=target_type, target_id=target_id, enabled=True).first()
+ if not pol:
+ return False
+ want_cron = _SCHEDULE_CRON.get(backup['schedule'], '0 2 * * *')
+ return pol.schedule_cron == want_cron and pol.retention_count == backup['retain']
+
+ @staticmethod
+ def _find_app(project: Project, name: Optional[str]) -> Optional[Application]:
+ if not name:
+ return None
+ return Application.query.filter_by(project_id=project.id, name=name).first()
+
+ @classmethod
+ def _resolve_app_id(cls, project, payload):
+ app = cls._find_app(project, payload.get('service'))
+ if not app:
+ raise RuntimeError(f'app `{payload.get("service")}` not found')
+ return app.id
+
+ @staticmethod
+ def _live_env(app: Application) -> Dict[str, Any]:
+ from app.services.env_service import EnvService
+ try:
+ return EnvService.get_env_dict(app.id)
+ except Exception:
+ return {}
+
+ @staticmethod
+ def _default_environment(project: Project) -> Optional[Environment]:
+ env = Environment.query.filter_by(project_id=project.id, is_default=True).first()
+ if env:
+ return env
+ return Environment.query.filter_by(project_id=project.id).first()
+
+ @staticmethod
+ def _summarize_plan(steps: List[Dict[str, Any]]) -> str:
+ if not steps:
+ return 'no changes — live state matches the manifest'
+ counts: Dict[str, int] = {}
+ for s in steps:
+ counts[s['type']] = counts.get(s['type'], 0) + 1
+ return ', '.join(f'{v} {k.replace("_", " ")}' for k, v in counts.items())
+
+ @staticmethod
+ def _step_ref(step):
+ return {'type': step['type'], 'service': step.get('service'),
+ 'description': step['description']}
+
+ @staticmethod
+ def _stringify(value):
+ return None if value is None else str(value)
+
+ @staticmethod
+ def _slug(text):
+ import re
+ return re.sub(r'[^a-z0-9]+', '-', (text or '').lower()).strip('-') or 'vol'
diff --git a/backend/tests/test_domain_attach_service.py b/backend/tests/test_domain_attach_service.py
new file mode 100644
index 00000000..e35dcafe
--- /dev/null
+++ b/backend/tests/test_domain_attach_service.py
@@ -0,0 +1,178 @@
+"""Proving suite for DomainAttachService (manifest task #12).
+
+Generalizes the WordPress one-call "attach a custom domain" flow to any app.
+The suite runs on Windows (``os.name == 'nt'``), where nginx and certbot are
+unavailable, so the tests assert the service degrades every external stage to a
+warning and never raises — the Domain row is the only hard requirement.
+
+Proving points:
+- attach(..., ssl='off') records the Domain row, returns success, does NOT
+ attempt a certificate, and survives with nginx unavailable
+- an invalid host (no dot) returns {'success': False} and records nothing
+- the DNS best-effort result is captured and its "add manually" message
+ surfaces as a warning
+- ssl='auto' calls obtain_certificate; a failed cert degrades to a warning
+ (attach still succeeds) and a successful cert sets ssl_enabled + paths
+- make_primary re-points the primary domain
+- re-attaching the same host is idempotent (created=False, no duplicate row)
+"""
+import pytest
+
+from app import db
+from app.models import Application, User
+from app.models.domain import Domain
+from app.services.domain_attach_service import DomainAttachService
+from app.services.dns_provider_service import DNSProviderService
+from app.services.site_domain_service import SiteDomainService
+from app.services.ssl_service import SSLService
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+def _owner(username='testadmin'):
+ """The admin user the auth_headers fixture creates, or a fresh one."""
+ user = User.query.filter_by(username=username).first()
+ if user:
+ return user
+ from werkzeug.security import generate_password_hash
+ user = User(email=f'{username}@test.local', username=username,
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_ADMIN, is_active=True)
+ db.session.add(user)
+ db.session.commit()
+ return user
+
+
+def _mk_app(name='attach-app', app_type='docker', port=8300, **kw):
+ a = Application(name=name, app_type=app_type, user_id=_owner().id, port=port, **kw)
+ db.session.add(a)
+ db.session.commit()
+ return a
+
+
[email protected](autouse=True)
+def _hermetic(monkeypatch):
+ """Keep every test offline: DNS never touches a provider, and the nginx
+ write is a no-op. Individual tests override these as needed."""
+ monkeypatch.setattr(DNSProviderService, 'ensure_a_record',
+ classmethod(lambda cls, host, ip: {'created': False,
+ 'reason': 'no_provider',
+ 'message': f'add {host} manually'}))
+ monkeypatch.setattr(SiteDomainService, 'write_app_vhost',
+ classmethod(lambda cls, a, force_type=None: {'nginx': None, 'warning': None}))
+
+
+# ── core attach ──────────────────────────────────────────────────────────────
+
+def test_attach_ssl_off_creates_domain_and_succeeds(client, auth_headers, app, monkeypatch):
+ """The headline case: attach a domain with SSL off. A Domain row is created,
+ success is True, and nothing raises despite nginx being unavailable."""
+ # Assert SSL is never attempted when ssl='off'.
+ monkeypatch.setattr(SSLService, 'obtain_certificate',
+ classmethod(lambda cls, *a, **kw:
+ (_ for _ in ()).throw(AssertionError('SSL must not run'))))
+
+ app_row = _mk_app(name='attach-off')
+ result = DomainAttachService.attach(app_row, 'foo.example.com', ssl='off')
+
+ assert result['success'] is True
+ assert result['domain'] == 'foo.example.com'
+ assert result['created'] is True
+ assert result['ssl'] == {'enabled': False}
+ row = Domain.query.filter_by(name='foo.example.com', application_id=app_row.id).first()
+ assert row is not None
+ assert row.ssl_enabled is not True
+
+
+def test_dns_result_captured_and_warned(client, auth_headers, app):
+ app_row = _mk_app(name='attach-dns')
+ result = DomainAttachService.attach(app_row, 'bar.example.com', ssl='off')
+ assert result['dns']['reason'] == 'no_provider'
+ assert any('add bar.example.com manually' in w for w in result['warnings'])
+
+
+def test_invalid_host_returns_failure(client, auth_headers, app):
+ """A host with no dot is rejected and records nothing."""
+ app_row = _mk_app(name='attach-bad')
+ result = DomainAttachService.attach(app_row, 'nodothost', ssl='off')
+ assert result['success'] is False
+ assert 'error' in result
+ assert Domain.query.filter_by(application_id=app_row.id).count() == 0
+
+
+def test_full_url_is_normalized_to_host(client, auth_headers, app):
+ app_row = _mk_app(name='attach-url')
+ result = DomainAttachService.attach(app_row, 'https://Site.Example.com:8443/path',
+ ssl='off')
+ assert result['success'] is True
+ assert result['domain'] == 'site.example.com'
+ assert Domain.query.filter_by(name='site.example.com').first() is not None
+
+
+# ── idempotency + primary ────────────────────────────────────────────────────
+
+def test_reattach_is_idempotent(client, auth_headers, app):
+ app_row = _mk_app(name='attach-idem')
+ first = DomainAttachService.attach(app_row, 'idem.example.com', ssl='off')
+ second = DomainAttachService.attach(app_row, 'idem.example.com', ssl='off')
+ assert first['created'] is True
+ assert second['created'] is False
+ assert Domain.query.filter_by(name='idem.example.com').count() == 1
+
+
+def test_make_primary_repoints_primary(client, auth_headers, app):
+ app_row = _mk_app(name='attach-primary')
+ db.session.add(Domain(name='old.example.com', is_primary=True, application_id=app_row.id))
+ db.session.commit()
+
+ result = DomainAttachService.attach(app_row, 'new.example.com', ssl='off',
+ make_primary=True)
+ assert result['success'] is True
+ old = Domain.query.filter_by(name='old.example.com').first()
+ new = Domain.query.filter_by(name='new.example.com').first()
+ assert old.is_primary is False
+ assert new.is_primary is True
+
+
+def test_host_owned_by_other_app_is_rejected(client, auth_headers, app):
+ a1 = _mk_app(name='attach-owner-1')
+ a2 = _mk_app(name='attach-owner-2')
+ assert DomainAttachService.attach(a1, 'shared.example.com', ssl='off')['success'] is True
+ result = DomainAttachService.attach(a2, 'shared.example.com', ssl='off')
+ assert result['success'] is False
+ assert 'another app' in result['error']
+
+
+# ── SSL best-effort ──────────────────────────────────────────────────────────
+
+def test_ssl_auto_failure_degrades_to_warning(client, auth_headers, app, monkeypatch):
+ """A cert failure must never fail the attach — it becomes a warning."""
+ monkeypatch.setattr(SSLService, 'obtain_certificate',
+ classmethod(lambda cls, domains, email, **kw:
+ {'success': False, 'error': 'DNS not propagated'}))
+ app_row = _mk_app(name='attach-ssl-fail')
+ result = DomainAttachService.attach(app_row, 'ssl.example.com', ssl='auto')
+ assert result['success'] is True
+ assert result['ssl']['enabled'] is False
+ assert result['ssl']['error'] == 'DNS not propagated'
+ assert any('HTTPS is not set up yet' in w for w in result['warnings'])
+
+
+def test_ssl_auto_success_sets_flags(client, auth_headers, app, monkeypatch):
+ monkeypatch.setattr(SSLService, 'obtain_certificate',
+ classmethod(lambda cls, domains, email, **kw:
+ {'success': True,
+ 'certificate_path': '/c/fullchain.pem',
+ 'private_key_path': '/c/privkey.pem'}))
+ from app.services.nginx_service import NginxService
+ monkeypatch.setattr(NginxService, 'add_ssl_to_site',
+ classmethod(lambda cls, name, cert, key: {'success': True}))
+
+ app_row = _mk_app(name='attach-ssl-ok')
+ result = DomainAttachService.attach(app_row, 'https.example.com', ssl='auto')
+ assert result['success'] is True
+ assert result['ssl'] == {'enabled': True}
+ row = Domain.query.filter_by(name='https.example.com').first()
+ assert row.ssl_enabled is True
+ assert row.ssl_certificate_path == '/c/fullchain.pem'
+ assert row.ssl_key_path == '/c/privkey.pem'
diff --git a/backend/tests/test_manifest_apply.py b/backend/tests/test_manifest_apply.py
new file mode 100644
index 00000000..955ca2d1
--- /dev/null
+++ b/backend/tests/test_manifest_apply.py
@@ -0,0 +1,168 @@
+"""Proving tests for Phase 2 — the manifest apply engine (plan 17)."""
+
+import pytest
+
+import app.models.application_manifest # noqa: F401
+from app.services.manifest_spec_service import ManifestSpecService
+from app.services.manifest_apply_service import ManifestApplyService
+
+
+MANIFEST = {
+ 'version': 1,
+ 'services': [
+ {
+ 'name': 'api', 'type': 'web', 'port': 8000, 'healthCheckPath': '/health',
+ 'envVars': [{'key': 'LOG_LEVEL', 'value': 'info'},
+ {'key': 'SECRET_TOKEN', 'fromSecret': 'tok'}],
+ 'disks': [{'name': 'uploads', 'mountPath': '/data/uploads',
+ 'backup': {'schedule': 'daily', 'retain': 7}}],
+ },
+ {'name': 'db', 'type': 'postgres', 'version': '16',
+ 'disk': {'size': '10GB', 'backup': {'schedule': 'daily', 'retain': 7}}},
+ ],
+ 'domains': [{'host': 'api.example.com', 'service': 'api', 'ssl': 'auto'}],
+}
+
+
+def project(app):
+ from app import db
+ from app.models import Project, Environment
+ from app.services.workspace_service import WorkspaceService
+ ws = WorkspaceService.ensure_default_workspace()
+ proj = Project(workspace_id=ws.id, name='Shop', slug='shop')
+ db.session.add(proj)
+ db.session.commit()
+ env = Environment(project_id=proj.id, name='Production', slug='production', is_default=True)
+ db.session.add(env)
+ db.session.commit()
+ return proj
+
+
+def owner(app):
+ from app import db
+ from app.models import User
+ user = User.query.filter_by(username='testadmin').first()
+ if not user:
+ user = User(username='testadmin', email='[email protected]', role='admin')
+ if hasattr(user, 'set_password'):
+ user.set_password('admin')
+ db.session.add(user)
+ db.session.commit()
+ return user
+
+
[email protected](autouse=True)
+def _stub_side_effects(monkeypatch):
+ # avoid Docker / nginx / DNS in the harness
+ from app.services.docker_service import DockerService
+ from app.services.domain_attach_service import DomainAttachService
+ monkeypatch.setattr(DockerService, 'create_volume',
+ classmethod(lambda cls, name, driver='local': {'success': True}))
+ def _fake_attach(cls, app, host, ssl='auto', email=None, make_primary=False):
+ # realistic: create the Domain row so idempotence is genuinely exercised
+ from app import db as _db
+ from app.models.domain import Domain
+ if not any(d.name == host for d in (app.domains or [])):
+ _db.session.add(Domain(name=host, application_id=app.id, is_primary=False))
+ _db.session.commit()
+ return {'success': True, 'domain': host, 'created': True, 'warnings': []}
+ monkeypatch.setattr(DomainAttachService, 'attach', classmethod(_fake_attach))
+
+
+def test_plan_is_ordered(project):
+ n = ManifestSpecService.normalize(MANIFEST)
+ plan = ManifestApplyService.plan(project, n)
+ types = [s['type'] for s in plan['steps']]
+ # dbs before consumers, domains last
+ assert 'provision_db' in types
+ assert types.index('provision_db') < types.index('create_app')
+ assert types[-1] == 'attach_domain'
+ # every declared piece shows up
+ assert 'set_env' in types
+ assert 'ensure_volume' in types
+ assert types.count('upsert_backup_policy') == 2 # db + files
+
+
+def test_apply_materializes_and_is_idempotent(project, owner):
+ from app.models import Application
+ from app.models.managed_database import ManagedDatabase
+ from app.models.backup_policy import BackupPolicy
+ n = ManifestSpecService.normalize(MANIFEST)
+
+ result = ManifestApplyService.apply(project, n, user_id=owner.id)
+ assert result['success'] is True, result
+ assert result['applied'] >= 6
+
+ api = Application.query.filter_by(project_id=project.id, name='api').first()
+ assert api is not None
+ assert api.port == 8000
+ assert api.healthcheck_path == '/health'
+ assert api.source == 'manifest'
+
+ # env literal set, secret ref NOT applied in Phase 2
+ from app.services.env_service import EnvService
+ env = EnvService.get_env_dict(api.id)
+ assert env.get('LOG_LEVEL') == 'info'
+ assert 'SECRET_TOKEN' not in env
+
+ # managed db recorded
+ mdb = ManagedDatabase.query.filter_by(engine='postgresql', name='db').first()
+ assert mdb is not None
+
+ # backup policies: files (app) + database
+ assert BackupPolicy.query.filter_by(target_type='files', target_id=api.id).count() == 1
+ assert BackupPolicy.query.filter_by(target_type='database', target_id=mdb.id).count() == 1
+
+ # volume created
+ assert any(v.mount_path == '/data/uploads' for v in api.volumes)
+
+ # IDEMPOTENCE: a second plan is empty
+ plan2 = ManifestApplyService.plan(project, n)
+ assert plan2['step_count'] == 0, plan2['summary']
+
+
+def test_apply_records_job(project, owner):
+ from app.models.deployment_job import DeploymentJob
+ n = ManifestSpecService.normalize(MANIFEST)
+ result = ManifestApplyService.apply(project, n, user_id=owner.id)
+ job = DeploymentJob.query.get(result['job_id'])
+ assert job is not None
+ assert job.kind == 'manifest.apply'
+ assert job.status == 'succeeded'
+
+
+def test_plan_and_apply_endpoints(client, auth_headers, project):
+ # plan (dry-run)
+ resp = client.post('/api/v1/manifests/plan', headers=auth_headers,
+ json={'project_id': project.id, 'manifest': MANIFEST})
+ assert resp.status_code == 200, resp.get_json()
+ plan = resp.get_json()['plan']
+ assert plan['step_count'] > 0
+
+ # apply
+ resp = client.post('/api/v1/manifests/apply', headers=auth_headers,
+ json={'project_id': project.id, 'manifest': MANIFEST})
+ assert resp.status_code == 200, resp.get_json()
+ assert resp.get_json()['success'] is True
+
+ # stored manifest is now retrievable + marked applied
+ resp = client.get(f'/api/v1/manifests?project_id={project.id}', headers=auth_headers)
+ assert resp.status_code == 200
+ stored = resp.get_json()['manifest']
+ assert stored['status'] == 'applied'
+
+ # re-plan through the API is empty (idempotent)
+ resp = client.post('/api/v1/manifests/plan', headers=auth_headers,
+ json={'project_id': project.id})
+ assert resp.get_json()['plan']['step_count'] == 0
+
+
+def test_redis_declared_but_warns(project, owner):
+ n = ManifestSpecService.normalize({'version': 1,
+ 'services': [{'name': 'cache', 'type': 'redis'}]})
+ plan = ManifestApplyService.plan(project, n)
+ assert plan['steps'][0]['type'] == 'warn'
+ result = ManifestApplyService.apply(project, n, user_id=owner.id)
+ assert result['success'] is True