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(templates): deploy templates as a backend repo-kind catalog entry

Juan Denisabe0fbece9e1
diff --git a/backend/app/api/templates.py b/backend/app/api/templates.py
index 44c62ce4..87f0139b 100644
--- a/backend/app/api/templates.py
+++ b/backend/app/api/templates.py
@@ -16,6 +16,7 @@ from app.middleware.rbac import admin_required
from app.models import User, Application
from app.services.deployment_job_service import DeploymentJobService
from app.services.template_service import TemplateService
+from app.services.repository_manifest_service import RepositoryManifestService
from app.services.resource_grant_service import ResourceGrantService
from app.utils.slug import validate_app_name
@@ -104,6 +105,8 @@ def get_template(template_id):
'description': template.get('description'),
'icon': template.get('icon'),
'categories': template.get('categories', []),
+ 'kind': template.get('kind', 'compose'),
+ 'repo': template.get('repo') if template.get('kind') == 'repo' else None,
'source': template.get('source'),
'documentation': template.get('documentation'),
'website': template.get('website'),
@@ -117,6 +120,47 @@ def get_template(template_id):
}), 200
+@templates_bp.route('/<template_id>/manifest', methods=['GET'])
+@jwt_required()
+def get_template_manifest(template_id):
+ """Inspect a repo template's public repository for deploy manifests.
+
+ Fetches the supported manifest files from the repo's raw host (no clone, no
+ OAuth) and analyzes them. When live inspection turns up nothing (private
+ repo, host down, no manifests), falls back to the template's declared
+ ``repo`` hints and tags ``source: 'template-hints'`` so the wizard can label
+ the confidence honestly.
+ """
+ result = TemplateService.get_template(template_id)
+ if not result.get('success'):
+ return jsonify(result), 404
+
+ template = result['template']
+ if template.get('kind') != 'repo':
+ return jsonify({'error': 'Manifest inspection is only available for repo templates'}), 400
+
+ repo = template.get('repo') or {}
+ repo_url = repo.get('url')
+ branch = request.args.get('branch') or repo.get('branch') or 'main'
+
+ manifest = None
+ if repo_url:
+ try:
+ manifest = RepositoryManifestService.analyze_public_repo(repo_url, branch)
+ except Exception:
+ manifest = None
+
+ # A real inspection detected an actual strategy or at least one manifest file.
+ if manifest and (manifest.get('strategy') or manifest.get('manifests')):
+ manifest['source'] = 'repo'
+ return jsonify({'manifest': manifest, 'source': 'repo'}), 200
+
+ # Honest fallback: the declared hints, clearly labeled.
+ hints = TemplateService.build_template_hints(template)
+ hints['source'] = 'template-hints'
+ return jsonify({'manifest': hints, 'source': 'template-hints'}), 200
+
+
# ==================== CATALOG SCHEMA ====================
@templates_bp.route('/catalog/schema', methods=['GET'])
diff --git a/backend/app/services/repository_manifest_service.py b/backend/app/services/repository_manifest_service.py
index 2461b77d..3552ceb6 100644
--- a/backend/app/services/repository_manifest_service.py
+++ b/backend/app/services/repository_manifest_service.py
@@ -5,6 +5,7 @@ import re
from pathlib import Path
from typing import Any, Dict, List, Optional
+import requests
import yaml
try:
@@ -42,6 +43,65 @@ class RepositoryManifestService:
+ cls.BUILD_FILES
))
+ @classmethod
+ def analyze_public_repo(cls, repo_url: str, branch: str = 'main') -> Dict:
+ """Inspect a PUBLIC repository by fetching its supported manifest files
+ from the provider's raw host (raw.githubusercontent.com, GitLab/Bitbucket
+ raw endpoints). No clone and no OAuth — this is the connection-less path
+ used to inspect a deploy-template repo the operator has not connected.
+
+ Returns the same shape as :meth:`analyze_files`. On an unsupported host
+ or a total fetch failure, returns an empty result with a warning so the
+ caller can fall back to declared template hints.
+ """
+ raw_base = cls._raw_base_url(repo_url, branch)
+ if not raw_base:
+ return cls._empty_result([f'Unsupported repository host: {repo_url}'])
+
+ file_map = {}
+ for file_name in cls.supported_files():
+ content = cls._fetch_raw(f'{raw_base}/{file_name}')
+ if content is not None:
+ file_map[file_name] = content
+
+ if not file_map:
+ return cls._empty_result(
+ [f'No supported manifest files found in {repo_url}@{branch}'])
+
+ return cls.analyze_files(file_map, root_files=sorted(file_map.keys()))
+
+ @staticmethod
+ def _raw_base_url(repo_url: str, branch: str) -> Optional[str]:
+ """Map a repository web/clone URL to its raw-file base URL for ``branch``.
+ Supports GitHub, GitLab, and Bitbucket; returns None otherwise."""
+ url = (repo_url or '').strip()
+ branch = branch or 'main'
+ m = re.match(r'^(?:https?://|git@)github\.com[:/]([^/]+)/([^/]+?)(?:\.git)?/?$', url)
+ if m:
+ return f'https://raw.githubusercontent.com/{m.group(1)}/{m.group(2)}/{branch}'
+ m = re.match(r'^(?:https?://|git@)gitlab\.com[:/]([^/]+)/([^/]+?)(?:\.git)?/?$', url)
+ if m:
+ return f'https://gitlab.com/{m.group(1)}/{m.group(2)}/-/raw/{branch}'
+ m = re.match(r'^(?:https?://|git@)bitbucket\.org[:/]([^/]+)/([^/]+?)(?:\.git)?/?$', url)
+ if m:
+ return f'https://bitbucket.org/{m.group(1)}/{m.group(2)}/raw/{branch}'
+ return None
+
+ @staticmethod
+ def _fetch_raw(url: str) -> Optional[str]:
+ """Fetch a single raw file, returning its text or None (missing/too big/
+ unreachable). Isolated so tests can monkeypatch it deterministically."""
+ try:
+ response = requests.get(url, timeout=10)
+ except requests.RequestException:
+ return None
+ if response.status_code != 200:
+ return None
+ content = response.content or b''
+ if len(content) > RepositoryManifestService.MAX_FILE_BYTES:
+ return None
+ return content.decode('utf-8', errors='replace')
+
@classmethod
def analyze_path(cls, repo_path: str) -> Dict:
root = Path(repo_path)
diff --git a/backend/app/services/template_service.py b/backend/app/services/template_service.py
index 02ad9447..cd89bf25 100644
--- a/backend/app/services/template_service.py
+++ b/backend/app/services/template_service.py
@@ -85,9 +85,21 @@ class TemplateService:
if field not in template:
errors.append(f"Missing required field: {field}")
- # Must have either compose or dockerfile
- if 'compose' not in template and 'dockerfile' not in template:
- errors.append("Template must have either 'compose' or 'dockerfile'")
+ # A template is either a one-click compose/dockerfile stack (the default,
+ # kind: compose) or a deployable Git repository (kind: repo). Repo
+ # templates carry a `repo` block with a `url` instead of a compose stack;
+ # they are deployed through the New Service wizard, not installed here.
+ kind = template.get('kind', 'compose')
+ if kind == 'repo':
+ repo = template.get('repo')
+ if not isinstance(repo, dict) or not repo.get('url'):
+ errors.append("Repo template must have a 'repo' block with a 'url'")
+ elif kind == 'compose':
+ # Must have either compose or dockerfile
+ if 'compose' not in template and 'dockerfile' not in template:
+ errors.append("Template must have either 'compose' or 'dockerfile'")
+ else:
+ errors.append(f"Unknown template kind: {kind}")
# Validate compose structure
if 'compose' in template:
@@ -677,16 +689,28 @@ class TemplateService:
if result.get('success'):
template = result['template']
seen_ids.add(template_id)
- templates.append({
+ kind = template.get('kind', 'compose')
+ entry = {
'id': template_id,
'name': template.get('name'),
'version': template.get('version'),
'description': template.get('description'),
'icon': template.get('icon'),
'categories': template.get('categories', []),
+ 'kind': kind,
'source': 'local',
'filepath': filepath
- })
+ }
+ # Repo templates surface a minimal repo summary so the
+ # catalog grid can badge them and link to the wizard
+ # without a second fetch.
+ if kind == 'repo' and isinstance(template.get('repo'), dict):
+ repo = template['repo']
+ entry['repo'] = {
+ 'url': repo.get('url'),
+ 'branch': repo.get('branch', 'main'),
+ }
+ templates.append(entry)
return templates
@@ -821,6 +845,58 @@ class TemplateService:
return {'success': False, 'error': 'Template not found'}
+ @classmethod
+ def build_template_hints(cls, template: Dict) -> Dict:
+ """Build a manifest-shaped payload from a repo template's declared
+ ``repo`` hints, used as an honest fallback when the public repo cannot be
+ inspected live. Mirrors ``RepositoryManifestService`` output so the wizard
+ renders it with the same code path; the caller tags ``source`` so the UI
+ can label confidence.
+ """
+ repo = template.get('repo') if isinstance(template.get('repo'), dict) else {}
+ build_method = repo.get('build_method')
+ recommended = {
+ 'app_type': repo.get('app_type'),
+ 'build_method': build_method,
+ 'port': repo.get('port'),
+ 'dockerfile_path': repo.get('dockerfile_path')
+ or ('Dockerfile' if build_method == 'dockerfile' else None),
+ 'custom_build_cmd': repo.get('build_command'),
+ 'custom_start_cmd': repo.get('start_command'),
+ 'healthcheck_path': repo.get('healthcheck_path'),
+ }
+ manifests = [
+ {
+ 'type': 'template-hint',
+ 'file': file_name,
+ 'label': file_name,
+ 'summary': 'Declared by template',
+ }
+ for file_name in (repo.get('manifest_files') or [])
+ ]
+ env = []
+ for item in (repo.get('env') or []):
+ if isinstance(item, dict) and item.get('key'):
+ env.append({
+ 'key': item['key'],
+ 'value': None if item.get('secret') else item.get('value'),
+ 'required': bool(item.get('required')),
+ 'secret': bool(item.get('secret')),
+ 'source': 'template-hints',
+ 'description': item.get('description', ''),
+ })
+ return {
+ 'success': True,
+ 'strategy': repo.get('strategy')
+ or ('docker_compose' if build_method else None),
+ 'recommended': recommended,
+ 'manifests': manifests,
+ 'env': env,
+ 'ports': [repo['port']] if repo.get('port') else [],
+ 'detected_files': list(repo.get('manifest_files') or []),
+ 'warnings': [],
+ }
+
@classmethod
def build_install_plan(cls, template_id: str, app_name: str,
user_variables: Dict = None, user_id: int = None,
diff --git a/backend/templates/agentsite.yaml b/backend/templates/agentsite.yaml
new file mode 100644
index 00000000..e88a91b4
--- /dev/null
+++ b/backend/templates/agentsite.yaml
@@ -0,0 +1,51 @@
+id: agentsite
+name: AgentSite
+version: "1.0"
+kind: repo
+description: AI-powered website builder with multi-agent orchestration, deployed straight from its Git repository.
+icon: data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cmVjdCB4PSIzIiB5PSIxMSIgd2lkdGg9IjE4IiBoZWlnaHQ9IjEwIiByeD0iMiIvPjxjaXJjbGUgY3g9IjEyIiBjeT0iNSIgcj0iMiIvPjxwYXRoIGQ9Ik0xMiA3djQiLz48cGF0aCBkPSJNOCAxNmguMDEiLz48cGF0aCBkPSJNMTYgMTZoLjAxIi8+PC9zdmc+
+categories:
+ - ai
+ - website
+ - deployment
+website: https://github.com/jhd3197/AgentSite
+documentation: https://github.com/jhd3197/AgentSite#readme
+
+# Repo templates are not one-click compose stacks — they carry a `repo` block and
+# are deployed through the New Service wizard, which inspects the live repository
+# for manifests. The hints below are only used as a labeled fallback when the
+# public repo cannot be inspected.
+repo:
+ url: https://github.com/jhd3197/AgentSite.git
+ branch: main
+ service_name: agentsite
+ app_type: docker
+ build_method: dockerfile
+ port: 6391
+ dockerfile_path: Dockerfile
+ healthcheck_path: /api/health
+ strategy: docker_compose
+ manifest_files:
+ - docker-compose.yml
+ - render.yaml
+ - railway.json
+ - app.json
+ env:
+ - key: OPENAI_API_KEY
+ required: true
+ secret: true
+ - key: CLAUDE_API_KEY
+ required: true
+ secret: true
+ - key: GOOGLE_API_KEY
+ required: true
+ secret: true
+ - key: GROQ_API_KEY
+ required: true
+ secret: true
+ - key: GROK_API_KEY
+ required: true
+ secret: true
+ - key: OPENROUTER_API_KEY
+ required: true
+ secret: true
diff --git a/backend/templates/index.json b/backend/templates/index.json
index 307ff1f5..b300c76e 100644
--- a/backend/templates/index.json
+++ b/backend/templates/index.json
@@ -1138,6 +1138,17 @@
"vpn",
"security"
]
+ },
+ {
+ "id": "agentsite",
+ "name": "AgentSite",
+ "version": "1.0",
+ "description": "AI-powered website builder with multi-agent orchestration, deployed straight from its Git repository.",
+ "categories": [
+ "ai",
+ "website",
+ "deployment"
+ ]
}
],
"categories": [
@@ -1245,6 +1256,7 @@
"whiteboard",
"wiki",
"workflow",
- "zigbee"
+ "zigbee",
+ "deployment"
]
}
diff --git a/backend/tests/BASELINE_COUNT b/backend/tests/BASELINE_COUNT
index 70081150..ff7f50a6 100644
--- a/backend/tests/BASELINE_COUNT
+++ b/backend/tests/BASELINE_COUNT
@@ -1 +1 @@
-2475
+2498
diff --git a/backend/tests/test_template_catalog_validation.py b/backend/tests/test_template_catalog_validation.py
index 3087feea..d7e4f0ca 100644
--- a/backend/tests/test_template_catalog_validation.py
+++ b/backend/tests/test_template_catalog_validation.py
@@ -138,8 +138,15 @@ def test_every_template_conforms_to_schema():
if not template.get("name"):
failures.append(f"{filename}: missing 'name'")
- # --- at least one of compose / dockerfile / ports -----------------
- if not any(k in template for k in ("compose", "dockerfile", "ports")):
+ # --- deployable shape depends on kind -----------------------------
+ # compose templates (the default) must define at least one of
+ # compose/dockerfile/ports; repo templates (kind: repo) instead carry a
+ # `repo` block with a `url` and are deployed through the wizard.
+ if template.get("kind") == "repo":
+ repo = template.get("repo")
+ if not isinstance(repo, dict) or not repo.get("url"):
+ failures.append(f"{filename}: repo template missing 'repo.url'")
+ elif not any(k in template for k in ("compose", "dockerfile", "ports")):
failures.append(
f"{filename}: must define at least one of compose/dockerfile/ports"
)
diff --git a/backend/tests/test_template_repo_kind.py b/backend/tests/test_template_repo_kind.py
new file mode 100644
index 00000000..0de8558f
--- /dev/null
+++ b/backend/tests/test_template_repo_kind.py
@@ -0,0 +1,151 @@
+"""Proving tests for repo-kind deploy templates (plan 43, Phase 1).
+
+Deploy templates used to be a hardcoded frontend constant; they now live in the
+backend catalog as ``kind: repo`` YAML entries that blend with the 105 compose
+templates. These tests cover: kind parsing + backward compat, the agentsite
+entry, repo-kind validation, the declared-hints fallback, public-repo manifest
+inspection (with a mocked raw fetch), and the ``/manifest`` endpoint's two paths
+(live inspection vs. hint fallback). Additions only — ratchet-safe.
+"""
+import pytest
+
+from app.services.template_service import TemplateService
+from app.services.repository_manifest_service import RepositoryManifestService
+
+
+# --------------------------------------------------------------------------- #
+# Kind parsing + backward compatibility
+# --------------------------------------------------------------------------- #
+def test_compose_templates_default_to_compose_kind():
+ """Every bundled compose template lists as kind 'compose' (no YAML change)."""
+ entries = TemplateService.list_local_templates()
+ portainer = next((e for e in entries if e['id'] == 'portainer'), None)
+ assert portainer is not None
+ assert portainer['kind'] == 'compose'
+ assert 'repo' not in portainer
+
+
+def test_validate_template_backward_compat_no_kind():
+ """A template with no `kind` and a compose block still validates."""
+ tmpl = {'name': 'X', 'version': '1', 'description': 'd', 'compose': {'services': {}}}
+ assert TemplateService.validate_template(tmpl)['valid'] is True
+
+
+def test_validate_repo_template_requires_url():
+ ok = {'name': 'X', 'version': '1', 'description': 'd', 'kind': 'repo',
+ 'repo': {'url': 'https://github.com/a/b.git'}}
+ assert TemplateService.validate_template(ok)['valid'] is True
+
+ missing = {'name': 'X', 'version': '1', 'description': 'd', 'kind': 'repo', 'repo': {}}
+ result = TemplateService.validate_template(missing)
+ assert result['valid'] is False
+ assert any('repo' in e.lower() for e in result['errors'])
+
+
+def test_unknown_kind_is_rejected():
+ tmpl = {'name': 'X', 'version': '1', 'description': 'd', 'kind': 'bogus'}
+ result = TemplateService.validate_template(tmpl)
+ assert result['valid'] is False
+
+
+# --------------------------------------------------------------------------- #
+# agentsite.yaml — the migrated deploy template
+# --------------------------------------------------------------------------- #
+def test_agentsite_served_as_repo_kind():
+ result = TemplateService.get_template('agentsite')
+ assert result['success'] is True
+ tmpl = result['template']
+ assert tmpl['kind'] == 'repo'
+ assert tmpl['repo']['url'].startswith('https://github.com/')
+ assert tmpl['repo']['app_type'] == 'docker'
+ assert tmpl.get('icon')
+
+
+def test_agentsite_in_list_with_repo_summary():
+ entries = TemplateService.list_local_templates()
+ agent = next((e for e in entries if e['id'] == 'agentsite'), None)
+ assert agent is not None
+ assert agent['kind'] == 'repo'
+ assert agent['repo']['url']
+ assert agent['repo']['branch'] == 'main'
+
+
+# --------------------------------------------------------------------------- #
+# Declared-hints fallback
+# --------------------------------------------------------------------------- #
+def test_build_template_hints_shape():
+ tmpl = TemplateService.get_template('agentsite')['template']
+ hints = TemplateService.build_template_hints(tmpl)
+ assert hints['strategy'] == 'docker_compose'
+ assert hints['recommended']['app_type'] == 'docker'
+ assert hints['recommended']['port'] == 6391
+ keys = {e['key'] for e in hints['env']}
+ assert 'OPENAI_API_KEY' in keys
+ # Secret env values are never leaked in hints.
+ assert all(e['value'] is None for e in hints['env'] if e['secret'])
+ assert {m['file'] for m in hints['manifests']} >= {'docker-compose.yml', 'render.yaml'}
+
+
+# --------------------------------------------------------------------------- #
+# Public-repo manifest inspection (mocked raw fetch)
+# --------------------------------------------------------------------------- #
+def test_raw_base_url_mapping():
+ gh = RepositoryManifestService._raw_base_url('https://github.com/a/b.git', 'main')
+ assert gh == 'https://raw.githubusercontent.com/a/b/main'
+ gl = RepositoryManifestService._raw_base_url('https://gitlab.com/a/b', 'dev')
+ assert gl == 'https://gitlab.com/a/b/-/raw/dev'
+ assert RepositoryManifestService._raw_base_url('https://example.com/a/b', 'main') is None
+
+
+def test_analyze_public_repo_happy_path(monkeypatch):
+ compose = 'services:\n web:\n build: .\n ports:\n - "6391:6391"\n'
+
+ def fake_fetch(url):
+ if url.endswith('/docker-compose.yml'):
+ return compose
+ return None
+
+ monkeypatch.setattr(RepositoryManifestService, '_fetch_raw', staticmethod(fake_fetch))
+ result = RepositoryManifestService.analyze_public_repo('https://github.com/a/b.git', 'main')
+ assert result['strategy'] == 'docker_compose'
+ assert 6391 in result['ports']
+ assert any(m['type'] == 'docker_compose' for m in result['manifests'])
+
+
+def test_analyze_public_repo_no_files(monkeypatch):
+ monkeypatch.setattr(RepositoryManifestService, '_fetch_raw', staticmethod(lambda url: None))
+ result = RepositoryManifestService.analyze_public_repo('https://github.com/a/b.git', 'main')
+ assert result['strategy'] is None
+ assert result['warnings']
+
+
+# --------------------------------------------------------------------------- #
+# /manifest endpoint — live inspection and hint fallback
+# --------------------------------------------------------------------------- #
+def test_manifest_endpoint_live_inspection(client, auth_headers, monkeypatch):
+ compose = 'services:\n web:\n build: .\n ports:\n - "6391:6391"\n'
+ monkeypatch.setattr(
+ RepositoryManifestService, '_fetch_raw',
+ staticmethod(lambda url: compose if url.endswith('/docker-compose.yml') else None),
+ )
+ resp = client.get('/api/v1/templates/agentsite/manifest', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['source'] == 'repo'
+ assert body['manifest']['strategy'] == 'docker_compose'
+
+
+def test_manifest_endpoint_falls_back_to_hints(client, auth_headers, monkeypatch):
+ # No supported files reachable -> honest declared-hints fallback.
+ monkeypatch.setattr(
+ RepositoryManifestService, '_fetch_raw', staticmethod(lambda url: None))
+ resp = client.get('/api/v1/templates/agentsite/manifest', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['source'] == 'template-hints'
+ assert body['manifest']['recommended']['port'] == 6391
+
+
+def test_manifest_endpoint_rejects_compose_template(client, auth_headers):
+ resp = client.get('/api/v1/templates/portainer/manifest', headers=auth_headers)
+ assert resp.status_code == 400
diff --git a/frontend/src/services/api/apps.js b/frontend/src/services/api/apps.js
index eac3bd83..a1aa002d 100644
--- a/frontend/src/services/api/apps.js
+++ b/frontend/src/services/api/apps.js
@@ -309,6 +309,13 @@ export async function getTemplate(templateId) {
return this.request(`/templates/${templateId}`);
}
+// Inspect a repo-kind template's public repository for deploy manifests.
+// Returns { manifest, source: 'repo' | 'template-hints' }.
+export async function inspectTemplateManifest(templateId, branch = null) {
+ const query = branch ? `?branch=${encodeURIComponent(branch)}` : '';
+ return this.request(`/templates/${templateId}/manifest${query}`);
+}
+
export async function installTemplate(templateId, appName, variables = {}, options = {}) {
return this.request(`/templates/${templateId}/install`, {
method: 'POST',