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): persist manifest + seed env + health-check gate (Phase 1)

Juan Denisae0f823e903f
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index 0aaaab79..5e6a6967 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -837,9 +837,22 @@ def create_app_from_repository():
if not build_result.get('success'):
raise RuntimeError(build_result.get('error', 'Failed to configure build'))
+ # Stop dropping what we detect: persist the manifest, seed non-secret
+ # env values, and record the health-check path (plan 17, Phase 1).
+ manifest_summary = None
+ try:
+ from app.services.manifest_persistence_service import ManifestPersistenceService
+ manifest_summary = ManifestPersistenceService.apply_import(
+ app, manifest, user_id=current_user_id,
+ source_repo=deploy_repo_url, source_ref=branch or 'main',
+ )
+ except Exception:
+ manifest_summary = None
+
return jsonify({
'message': 'Repository service created',
'app': _attach_deploy_config(app.to_dict(include_linked=True)),
+ 'manifest_import': manifest_summary,
'deploy_config': {
'repo_url': _safe_repo_url(deploy_repo_url),
'branch': branch or 'main',
@@ -1257,6 +1270,9 @@ def update_app(app_id):
app.python_version = data['python_version']
if 'port' in data:
app.port = data['port']
+ if 'healthcheck_path' in data:
+ hc = (data['healthcheck_path'] or '').strip()
+ app.healthcheck_path = hc or None
if 'root_path' in data:
app.root_path = data['root_path']
if 'docker_image' in data:
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index a9f2a67f..b0fce330 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -31,6 +31,7 @@ from app.models.source_connection import SourceConnection
from app.models.registrar_connection import RegistrarConnection
from app.models.container_registry import ContainerRegistry
from app.models.app_volume import AppVolume
+from app.models.application_manifest import ApplicationManifest
from app.models.managed_database import ManagedDatabase
from app.models.api_key import ApiKey
from app.models.api_usage import ApiUsageLog, ApiUsageSummary
diff --git a/backend/app/models/application.py b/backend/app/models/application.py
index e3824e81..39b3de5d 100644
--- a/backend/app/models/application.py
+++ b/backend/app/models/application.py
@@ -26,6 +26,10 @@ class Application(db.Model):
python_version = db.Column(db.String(10), nullable=True) # '3.9', '3.10', '3.11', '3.12'
port = db.Column(db.Integer, nullable=True)
root_path = db.Column(db.String(500), nullable=True)
+ # HTTP path used for health checks and the zero-downtime restart gate.
+ # Populated from a manifest at import, editable in Settings. NULL => no gate
+ # (the restart falls back to a fixed wait).
+ healthcheck_path = db.Column(db.String(255), nullable=True)
# Docker specific
docker_image = db.Column(db.String(200), nullable=True)
@@ -116,6 +120,7 @@ class Application(db.Model):
'php_version': self.php_version,
'python_version': self.python_version,
'port': self.port,
+ 'healthcheck_path': self.healthcheck_path,
'root_path': self.root_path,
'docker_image': self.docker_image,
'container_id': self.container_id,
diff --git a/backend/app/models/application_manifest.py b/backend/app/models/application_manifest.py
new file mode 100644
index 00000000..2953428b
--- /dev/null
+++ b/backend/app/models/application_manifest.py
@@ -0,0 +1,82 @@
+"""Persisted declarative manifest for a project.
+
+One row per project (the manifest maps to a Project). Import stores the raw
+text + normalized JSON + hash + source so nothing detected is discarded and
+later pushes can re-read it. History lives in the existing DeploymentSnapshot
+mechanism, not a second table.
+"""
+
+import json
+from datetime import datetime
+
+from app import db
+
+
+# status values
+STATUS_PENDING = 'pending' # a changed manifest awaiting an explicit apply
+STATUS_APPLIED = 'applied' # live state matches the declared spec
+STATUS_DRIFTED = 'drifted' # live state diverged from the manifest
+STATUS_ERROR = 'error' # last apply / parse failed
+
+
+class ApplicationManifest(db.Model):
+ __tablename__ = 'application_manifests'
+
+ id = db.Column(db.Integer, primary_key=True)
+ project_id = db.Column(db.Integer, db.ForeignKey('projects.id'), nullable=False, index=True)
+
+ raw_text = db.Column(db.Text, nullable=True) # the manifest file as committed
+ normalized_json = db.Column(db.Text, nullable=True) # ManifestSpecService.normalize() output
+ manifest_hash = db.Column(db.String(64), nullable=True, index=True)
+
+ # provenance
+ source_repo = db.Column(db.String(500), nullable=True)
+ source_ref = db.Column(db.String(200), nullable=True)
+ source_commit = db.Column(db.String(64), nullable=True)
+ source_path = db.Column(db.String(255), nullable=True, default='serverkit.yaml')
+
+ status = db.Column(db.String(20), nullable=False, default=STATUS_PENDING, index=True)
+ last_error = db.Column(db.Text, nullable=True)
+ applied_at = db.Column(db.DateTime, nullable=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ __table_args__ = (
+ db.UniqueConstraint('project_id', name='uq_application_manifest_project'),
+ )
+
+ def get_normalized(self):
+ if not self.normalized_json:
+ return None
+ try:
+ return json.loads(self.normalized_json)
+ except Exception:
+ return None
+
+ def set_normalized(self, value):
+ self.normalized_json = json.dumps(value) if value is not None else None
+
+ def to_dict(self, include_raw=False):
+ data = {
+ 'id': self.id,
+ 'project_id': self.project_id,
+ 'manifest_hash': self.manifest_hash,
+ 'status': self.status,
+ 'last_error': self.last_error,
+ 'source': {
+ 'repo': self.source_repo,
+ 'ref': self.source_ref,
+ 'commit': self.source_commit,
+ 'path': self.source_path,
+ },
+ 'normalized': self.get_normalized(),
+ 'applied_at': self.applied_at.isoformat() if self.applied_at else None,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+ if include_raw:
+ data['raw_text'] = self.raw_text
+ return data
+
+ def __repr__(self):
+ return f'<ApplicationManifest project={self.project_id} status={self.status}>'
diff --git a/backend/app/services/git_deploy_service.py b/backend/app/services/git_deploy_service.py
index d608f21e..f90f1b2b 100644
--- a/backend/app/services/git_deploy_service.py
+++ b/backend/app/services/git_deploy_service.py
@@ -430,9 +430,9 @@ class GitDeployService:
timeout=120
)
- # Wait for new container to be healthy
- import time
- time.sleep(5)
+ # Wait for the new container to be healthy. When a health-check path
+ # is declared, poll it instead of a blind fixed wait (plan 17 #4).
+ output.append(cls._wait_for_health(app))
# Scale back down
scale_result = subprocess.run(
@@ -455,6 +455,43 @@ class GitDeployService:
except Exception as e:
return {'success': False, 'error': str(e), 'output': '\n'.join(output)}
+ @classmethod
+ def _wait_for_health(cls, app, timeout: int = 30, fallback: int = 5) -> str:
+ """Block until the app answers its health-check path, or time out.
+
+ Falls back to a fixed wait when no path/port is declared, preserving the
+ previous behavior. Best-effort — never raises.
+ """
+ import time
+
+ path = getattr(app, 'healthcheck_path', None)
+ port = getattr(app, 'port', None)
+ if not path or not port:
+ time.sleep(fallback)
+ return f"Waited {fallback}s (no health check configured)"
+
+ import urllib.request
+ import urllib.error
+
+ url = f"http://127.0.0.1:{port}{path if path.startswith('/') else '/' + path}"
+ deadline = time.time() + timeout
+ last = None
+ while time.time() < deadline:
+ try:
+ with urllib.request.urlopen(url, timeout=3) as resp:
+ if 200 <= resp.status < 400:
+ return f"Health check passed ({url} -> {resp.status})"
+ last = f"status {resp.status}"
+ except urllib.error.HTTPError as exc:
+ if 200 <= exc.code < 500:
+ # a 4xx still means the app is up and routing
+ return f"Health check reachable ({url} -> {exc.code})"
+ last = f"HTTP {exc.code}"
+ except Exception as exc: # not up yet
+ last = str(exc)
+ time.sleep(1)
+ return f"Health check did not pass within {timeout}s ({url}; last: {last})"
+
@classmethod
def _run_script(cls, script: str, cwd: str) -> Dict:
"""Run a deployment script."""
diff --git a/backend/app/services/manifest_persistence_service.py b/backend/app/services/manifest_persistence_service.py
new file mode 100644
index 00000000..c90cc756
--- /dev/null
+++ b/backend/app/services/manifest_persistence_service.py
@@ -0,0 +1,120 @@
+"""Persist a detected manifest and seed what it declares (plan 17, Phase 1).
+
+Stops the import flow from discarding what `RepositoryManifestService` already
+parses: the health-check path, the manifest env, and (for v1 manifests) the
+whole normalized spec are recorded so later pushes can re-read them.
+"""
+
+import hashlib
+import json
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from app import db
+from app.models.application import Application
+from app.models.application_manifest import ApplicationManifest, STATUS_PENDING
+from app.services.env_service import EnvService
+
+
+class ManifestPersistenceService:
+ """Store the manifest row + seed non-secret env at import. Best-effort."""
+
+ @classmethod
+ def apply_import(cls, app: Application, analysis: Dict[str, Any],
+ user_id: Optional[int] = None,
+ source_repo: Optional[str] = None,
+ source_ref: Optional[str] = None,
+ source_commit: Optional[str] = None) -> Dict[str, Any]:
+ """Consume a RepositoryManifestService result for a freshly imported app.
+
+ - populate ``app.healthcheck_path`` from the detected recommendation
+ - seed non-secret env values as EnvironmentVariable rows
+ - store the ApplicationManifest row (v1 only, when the app has a project)
+
+ Never raises — import must not fail because a manifest hint could not be
+ persisted. Returns a small summary for the response/logs.
+ """
+ summary = {'healthcheck_path': None, 'env_seeded': 0, 'manifest_stored': False}
+
+ recommended = analysis.get('recommended') or {}
+ hc = recommended.get('healthcheck_path')
+ if hc and not app.healthcheck_path:
+ app.healthcheck_path = hc
+ summary['healthcheck_path'] = hc
+
+ summary['env_seeded'] = cls._seed_env(app, analysis, user_id)
+
+ if analysis.get('manifest_v1_normalized') and app.project_id:
+ try:
+ cls.store_manifest(
+ project_id=app.project_id,
+ normalized=analysis['manifest_v1_normalized'],
+ raw_text=analysis.get('manifest_v1_raw'),
+ source_repo=source_repo,
+ source_ref=source_ref,
+ source_commit=source_commit,
+ source_path=analysis.get('manifest_v1_file') or 'serverkit.yaml',
+ )
+ summary['manifest_stored'] = True
+ except Exception:
+ db.session.rollback()
+
+ try:
+ db.session.commit()
+ except Exception:
+ db.session.rollback()
+ return summary
+
+ @classmethod
+ def _seed_env(cls, app: Application, analysis: Dict[str, Any],
+ user_id: Optional[int]) -> int:
+ """Seed non-secret literal env values. Secrets/placeholders stay empty."""
+ entries = analysis.get('env') or []
+ to_set: Dict[str, Any] = {}
+ for entry in entries:
+ key = entry.get('key')
+ if not key or entry.get('kind') == 'env_file':
+ continue
+ if entry.get('secret'):
+ continue # placeholder — UI hints the operator to fill it
+ value = entry.get('value')
+ if value in (None, ''):
+ continue
+ to_set[key] = value
+ if not to_set:
+ return 0
+ try:
+ count, _errors = EnvService.bulk_set_env_vars(app.id, to_set, user_id)
+ return count
+ except Exception:
+ return 0
+
+ @classmethod
+ def store_manifest(cls, project_id: int, normalized: Dict[str, Any],
+ raw_text: Optional[str] = None,
+ source_repo: Optional[str] = None,
+ source_ref: Optional[str] = None,
+ source_commit: Optional[str] = None,
+ source_path: str = 'serverkit.yaml',
+ status: str = STATUS_PENDING) -> ApplicationManifest:
+ """Upsert the single ApplicationManifest row for a project."""
+ row = ApplicationManifest.query.filter_by(project_id=project_id).first()
+ if row is None:
+ row = ApplicationManifest(project_id=project_id)
+ db.session.add(row)
+
+ row.raw_text = raw_text
+ row.set_normalized(normalized)
+ row.manifest_hash = cls.hash_normalized(normalized)
+ row.source_repo = source_repo
+ row.source_ref = source_ref
+ row.source_commit = source_commit
+ row.source_path = source_path
+ row.status = status
+ db.session.flush()
+ return row
+
+ @staticmethod
+ def hash_normalized(normalized: Dict[str, Any]) -> str:
+ payload = json.dumps(normalized, sort_keys=True, separators=(',', ':'))
+ return hashlib.sha256(payload.encode('utf-8')).hexdigest()
diff --git a/backend/app/services/repository_manifest_service.py b/backend/app/services/repository_manifest_service.py
index 8bdb0102..b1acefaa 100644
--- a/backend/app/services/repository_manifest_service.py
+++ b/backend/app/services/repository_manifest_service.py
@@ -117,7 +117,7 @@ class RepositoryManifestService:
# v1 declarative manifest: recognize it, surface a multi-service summary,
# and seed `recommended` from the first app service for the wizard. Legacy
# flat files (no `version: 1`) keep the original code path untouched.
- if cls._detect_serverkit_v1(file_name, data, result):
+ if cls._detect_serverkit_v1(file_name, data, result, file_map.get(file_name)):
return
build = data.get('build') if isinstance(data.get('build'), dict) else {}
@@ -150,13 +150,17 @@ class RepositoryManifestService:
cls._add_manifest(result, 'serverkit', file_name, 'ServerKit manifest', 'Native import settings')
@classmethod
- def _detect_serverkit_v1(cls, file_name: str, data: Dict, result: Dict) -> bool:
+ def _detect_serverkit_v1(cls, file_name: str, data: Dict, result: Dict,
+ raw: Optional[str] = None) -> bool:
"""Recognize a `version: 1` manifest. Returns True when handled."""
from app.services.manifest_spec_service import ManifestSpecService, ManifestError
if not ManifestSpecService.is_v1(data):
return False
+ result['manifest_v1_raw'] = raw
+ result['manifest_v1_file'] = file_name
+
try:
normalized = ManifestSpecService.normalize(data)
except ManifestError as exc:
diff --git a/backend/migrations/versions/054_serverkit_manifest.py b/backend/migrations/versions/054_serverkit_manifest.py
new file mode 100644
index 00000000..4b55ddf1
--- /dev/null
+++ b/backend/migrations/versions/054_serverkit_manifest.py
@@ -0,0 +1,74 @@
+"""Declarative serverkit.yaml manifest persistence (plan 17, Phase 1).
+
+Adds:
+- applications.healthcheck_path (String(255), nullable) — populated from a
+ manifest at import, editable in Settings, consumed by the restart gate.
+- application_manifests table — one row per project storing the raw manifest,
+ its normalized JSON, hash, provenance and status. Nothing detected is dropped.
+
+Idempotent: MigrationService runs _fix_missing_columns() + db.create_all() on boot
+before Alembic, so guard on the live schema.
+
+Revision ID: 054_serverkit_manifest
+Revises: 053_micro_cache
+Create Date: 2026-07-04
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '054_serverkit_manifest'
+down_revision = '053_micro_cache'
+branch_labels = None
+depends_on = None
+
+_COLUMN = 'healthcheck_path'
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+
+ if 'applications' in tables:
+ cols = {c['name'] for c in inspector.get_columns('applications')}
+ if _COLUMN not in cols:
+ op.add_column('applications', sa.Column(_COLUMN, sa.String(255), nullable=True))
+
+ if 'application_manifests' not in tables:
+ op.create_table(
+ 'application_manifests',
+ sa.Column('id', sa.Integer, nullable=False),
+ sa.Column('project_id', sa.Integer, nullable=False),
+ sa.Column('raw_text', sa.Text, nullable=True),
+ sa.Column('normalized_json', sa.Text, nullable=True),
+ sa.Column('manifest_hash', sa.String(64), nullable=True),
+ sa.Column('source_repo', sa.String(500), nullable=True),
+ sa.Column('source_ref', sa.String(200), nullable=True),
+ sa.Column('source_commit', sa.String(64), nullable=True),
+ sa.Column('source_path', sa.String(255), nullable=True),
+ sa.Column('status', sa.String(20), nullable=False, server_default='pending'),
+ sa.Column('last_error', sa.Text, nullable=True),
+ sa.Column('applied_at', sa.DateTime, nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=True),
+ sa.Column('updated_at', sa.DateTime, nullable=True),
+ sa.PrimaryKeyConstraint('id'),
+ sa.ForeignKeyConstraint(['project_id'], ['projects.id']),
+ sa.UniqueConstraint('project_id', name='uq_application_manifest_project'),
+ )
+ op.create_index('ix_application_manifests_project_id', 'application_manifests', ['project_id'])
+ op.create_index('ix_application_manifests_manifest_hash', 'application_manifests', ['manifest_hash'])
+ op.create_index('ix_application_manifests_status', 'application_manifests', ['status'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = set(inspector.get_table_names())
+
+ if 'application_manifests' in tables:
+ op.drop_table('application_manifests')
+
+ if 'applications' in tables:
+ cols = {c['name'] for c in inspector.get_columns('applications')}
+ if _COLUMN in cols:
+ op.drop_column('applications', _COLUMN)
diff --git a/backend/tests/test_manifest_persistence.py b/backend/tests/test_manifest_persistence.py
new file mode 100644
index 00000000..67478de1
--- /dev/null
+++ b/backend/tests/test_manifest_persistence.py
@@ -0,0 +1,118 @@
+"""Proving tests for Phase 1 — stop dropping detected config (plan 17)."""
+
+import pytest
+
+# register the new table on metadata before create_all()
+import app.models.application_manifest # noqa: F401
+from app.services.manifest_persistence_service import ManifestPersistenceService
+from app.services.git_deploy_service import GitDeployService
+
+
+def _owner():
+ from app.models import User
+ return User.query.filter_by(username='testadmin').first()
+
+
+def _make_app(project_id=None, healthcheck=None):
+ from app import db
+ from app.models import Application
+ row = Application(name='hcapp', app_type='docker', port=9099,
+ user_id=_owner().id, status='running',
+ project_id=project_id, healthcheck_path=healthcheck)
+ db.session.add(row)
+ db.session.commit()
+ return row
+
+
+def _project():
+ from app import db
+ from app.models import Project
+ from app.services.workspace_service import WorkspaceService
+ ws = WorkspaceService.ensure_default_workspace()
+ proj = Project(workspace_id=ws.id, name='Proj', slug='proj')
+ db.session.add(proj)
+ db.session.commit()
+ return proj
+
+
+def test_healthcheck_column_and_todict(client, auth_headers, app):
+ app_row = _make_app(healthcheck='/health')
+ assert app_row.healthcheck_path == '/health'
+ assert app_row.to_dict()['healthcheck_path'] == '/health'
+
+
+def test_apply_import_seeds_env_and_healthcheck(client, auth_headers, app):
+ app_row = _make_app()
+ analysis = {
+ 'recommended': {'healthcheck_path': '/up'},
+ 'env': [
+ {'key': 'LOG_LEVEL', 'value': 'info', 'secret': False},
+ {'key': 'API_TOKEN', 'value': 'shh', 'secret': True}, # secret -> not seeded
+ {'key': 'EMPTY', 'value': None, 'secret': False}, # empty -> skipped
+ ],
+ }
+ summary = ManifestPersistenceService.apply_import(app_row, analysis, user_id=_owner().id)
+ assert summary['healthcheck_path'] == '/up'
+ assert app_row.healthcheck_path == '/up'
+ assert summary['env_seeded'] == 1
+
+ from app.services.env_service import EnvService
+ env = EnvService.get_env_dict(app_row.id)
+ assert env.get('LOG_LEVEL') == 'info'
+ assert 'API_TOKEN' not in env # secrets stay placeholders
+ assert 'EMPTY' not in env
+
+
+def test_store_manifest_upserts_one_row_per_project(client, auth_headers, app):
+ from app.models.application_manifest import ApplicationManifest
+ proj = _project()
+ normalized = {'version': 1, 'services': [{'name': 'api', 'type': 'web'}]}
+ row1 = ManifestPersistenceService.store_manifest(proj.id, normalized,
+ raw_text='version: 1', source_repo='r')
+ from app import db
+ db.session.commit()
+ h1 = row1.manifest_hash
+
+ normalized2 = {'version': 1, 'services': [{'name': 'api', 'type': 'worker'}]}
+ row2 = ManifestPersistenceService.store_manifest(proj.id, normalized2)
+ db.session.commit()
+
+ assert row1.id == row2.id # upsert, not insert
+ assert row2.manifest_hash != h1
+ assert ApplicationManifest.query.filter_by(project_id=proj.id).count() == 1
+
+
+def test_apply_import_stores_manifest_when_project_and_v1(client, auth_headers, app):
+ from app.models.application_manifest import ApplicationManifest
+ proj = _project()
+ app_row = _make_app(project_id=proj.id)
+ analysis = {
+ 'recommended': {},
+ 'env': [],
+ 'manifest_v1_normalized': {'version': 1, 'services': [{'name': 'api', 'type': 'web'}]},
+ 'manifest_v1_raw': 'version: 1\n',
+ 'manifest_v1_file': 'serverkit.yaml',
+ }
+ summary = ManifestPersistenceService.apply_import(app_row, analysis, user_id=_owner().id)
+ assert summary['manifest_stored'] is True
+ stored = ApplicationManifest.query.filter_by(project_id=proj.id).first()
+ assert stored is not None
+ assert stored.get_normalized()['services'][0]['name'] == 'api'
+
+
+def test_health_wait_falls_back_without_path(app):
+ from app.models import Application
+ a = Application(name='x', app_type='docker', user_id=_owner().id if _owner() else 1)
+ a.healthcheck_path = None
+ a.port = None
+ msg = GitDeployService._wait_for_health(a, timeout=1, fallback=0)
+ assert 'no health check' in msg
+
+
+def test_health_wait_times_out_when_unreachable(app):
+ from app.models import Application
+ a = Application(name='x', app_type='docker', user_id=1)
+ a.healthcheck_path = '/health'
+ a.port = 1 # nothing listening
+ msg = GitDeployService._wait_for_health(a, timeout=1)
+ assert 'did not pass' in msg