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(recipes): serverkit-recipes registry catalog with one-call installs

Juan Denis93c8abbbbe9a
diff --git a/backend/app/api/recipes.py b/backend/app/api/recipes.py
index 0a1c9399..faaccf7a 100644
--- a/backend/app/api/recipes.py
+++ b/backend/app/api/recipes.py
@@ -1,17 +1,23 @@
-"""Recipe run API (plan 68 Phase 0).
-
-Registry browsing and bundled recipe content land in later phases. This first
-surface accepts a reviewed inline/stored v1 manifest, creates a normal
-DeploymentJob, and resumes encrypted human handoffs on that same run.
+"""Recipe run API (plan 68).
+
+Starts runs from three manifest sources — a registry slug (the curated
+``serverkit-recipes`` catalog), reviewed inline YAML/JSON, or a manifest
+already stored on the project — creates a normal DeploymentJob, and resumes
+encrypted human handoffs on that same run. Runs target either an explicit
+``project_id`` or a ``server_id``, for which a per-workspace Recipes project
+is found or created so a catalog install is one call.
"""
from flask import Blueprint, jsonify, request
from app import db
-from app.middleware.rbac import admin_required, get_current_user
+from app.exceptions import NotFoundError
+from app.middleware.rbac import admin_required, auth_required, get_current_user
from app.models.application_manifest import STATUS_ERROR, STATUS_PENDING
from app.models.deployment_job import DeploymentJob
from app.models.project import Project
+from app.models.server import Server
+from app.services import recipe_registry_service
from app.services.manifest_persistence_service import ManifestPersistenceService
from app.services.manifest_spec_service import ManifestError, ManifestSpecService
from app.services.recipe_execution_service import (
@@ -22,8 +28,14 @@ from app.services.recipe_execution_service import (
recipes_bp = Blueprint('recipes', __name__)
+RECIPES_PROJECT_SLUG = 'recipes'
+
def _normalized_recipe(data, project_id):
+ """Resolve the manifest source: registry slug > inline content > stored."""
+ if data.get('registry_slug'):
+ text = recipe_registry_service.get_manifest_text(data['registry_slug'])
+ return ManifestSpecService.normalize_text(text), text
if 'content' in data:
return ManifestSpecService.normalize_text(data['content']), data['content']
if 'manifest' in data:
@@ -32,20 +44,103 @@ def _normalized_recipe(data, project_id):
row = ApplicationManifest.query.filter_by(project_id=project_id).first()
if row and row.get_normalized():
return row.get_normalized(), row.raw_text
- raise ManifestError(['Provide `content`/`manifest`, or store one first'])
+ raise ManifestError(['Provide `registry_slug`, `content`, `manifest`, or store one first'])
+
+
+def _resolve_project(server):
+ """Find-or-create the per-workspace Recipes project for a server-targeted
+ run. Idempotent: every subsequent install reuses it."""
+ project = Project.query.filter_by(
+ workspace_id=server.workspace_id, slug=RECIPES_PROJECT_SLUG).first()
+ if project:
+ return project
+ project = Project(workspace_id=server.workspace_id,
+ name='Recipes', slug=RECIPES_PROJECT_SLUG,
+ description='Apps installed through the Recipe catalog')
+ db.session.add(project)
+ db.session.flush()
+ return project
+
+
+def _validated_params(normalized, raw_params):
+ """Check up-front params against the manifest's declared inputs. Only
+ non-secret inputs may be preset; secrets must use the mid-run handoff."""
+ if raw_params in (None, {}):
+ return {}
+ if not isinstance(raw_params, dict):
+ raise ValueError('params must be an object of input keys')
+ inputs = {
+ (step.get('input') or {}).get('key'): (step.get('input') or {})
+ for step in (normalized.get('configure') or [])
+ if step.get('input')
+ }
+ unknown = [k for k in raw_params if k not in inputs]
+ if unknown:
+ raise ValueError(f"Unknown recipe input(s): {', '.join(sorted(unknown))}")
+ secrets = [k for k, v in raw_params.items() if v is not None and inputs[k].get('secret')]
+ if secrets:
+ raise ValueError(
+ f"{', '.join(sorted(secrets))} is collected securely during the run "
+ "and cannot be preset")
+ return {k: str(v) for k, v in raw_params.items() if v is not None}
+
+
+@recipes_bp.route('/registry', methods=['GET'])
+@auth_required()
+def list_recipe_registry():
+ return jsonify({
+ 'recipes': recipe_registry_service.list_catalog(),
+ 'source': recipe_registry_service.registry_source_label(),
+ }), 200
+
+
+@recipes_bp.route('/registry/<slug>', methods=['GET'])
+@auth_required()
+def get_recipe_registry_entry(slug):
+ entry = recipe_registry_service.get_entry(slug)
+ if entry is None:
+ return jsonify({'error': 'Recipe not found in the registry'}), 404
+ try:
+ manifest_text = recipe_registry_service.get_manifest_text(slug)
+ except NotFoundError as exc:
+ return jsonify({'error': str(exc)}), 404
+ except Exception:
+ return jsonify({'error': 'Could not download the recipe from the registry'}), 503
+ public = {k: v for k, v in entry.items() if k != '_manifest_url'}
+ return jsonify({'recipe': public, 'manifest': manifest_text}), 200
@recipes_bp.route('/runs', methods=['POST'])
@admin_required
def start_recipe_run():
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
+
+ project = None
+ server = None
+ if data.get('server_id'):
+ server = Server.query.get(data.get('server_id'))
+ if not server:
+ return jsonify({'error': 'A valid server_id is required'}), 400
+ if data.get('project_id'):
+ project = Project.query.get(data.get('project_id'))
+ if not project:
+ return jsonify({'error': 'A valid project_id is required'}), 400
+ if project is None and server is None:
+ return jsonify({'error': 'Provide server_id or project_id'}), 400
+
try:
- normalized, raw = _normalized_recipe(data, project.id)
+ normalized, raw = _normalized_recipe(data, project.id if project else None)
+ params = _validated_params(normalized, data.get('params'))
except ManifestError as exc:
return jsonify({'error': 'Invalid Recipe manifest', 'errors': exc.errors}), 400
+ except (ValueError, NotFoundError) as exc:
+ return jsonify({'error': str(exc)}), 400
+
+ # A server-targeted catalog run pins the manifest's default server ref.
+ if server is not None:
+ normalized['server'] = server.name
+ if project is None:
+ project = _resolve_project(server)
unsupported = RecipeExecutionService.unsupported_capabilities(normalized)
if unsupported:
@@ -64,8 +159,9 @@ def start_recipe_run():
wait = request.args.get('wait', 'false').lower() == 'true'
result = RecipeExecutionService.start(
project, normalized, user_id=user.id,
- slug=data.get('slug'), title=data.get('title'),
- manifest_row=row, wait=wait)
+ slug=data.get('slug') or data.get('registry_slug'),
+ title=data.get('title'),
+ manifest_row=row, params=params, wait=wait)
if not result.get('success'):
row.status = STATUS_ERROR
row.last_error = result.get('error')
@@ -73,7 +169,8 @@ def start_recipe_run():
return jsonify(result), 400
_audit('recipe.start', user.id, result.get('job_id'), {
- 'project_id': project.id, 'slug': data.get('slug'),
+ 'project_id': project.id, 'slug': data.get('slug') or data.get('registry_slug'),
+ 'server_id': server.id if server else None,
})
return jsonify(result), 200 if wait else 202
diff --git a/backend/app/data/recipes_index.json b/backend/app/data/recipes_index.json
new file mode 100644
index 00000000..32dbca28
--- /dev/null
+++ b/backend/app/data/recipes_index.json
@@ -0,0 +1,132 @@
+{
+ "$schema": "./schema/index.schema.json",
+ "name": "serverkit-recipes",
+ "recipes": [
+ {
+ "slug": "minecraft-java",
+ "name": "Minecraft server",
+ "version": "1.4.0",
+ "category": "Game servers",
+ "icon": "box",
+ "description": "Paper server with RCON, auto-restart and a nightly world backup.",
+ "author": "serverkit",
+ "minutes": 4,
+ "featured": true,
+ "requirements": { "cpuCores": 4, "memoryMB": 8192, "diskGB": 40, "igpu": "none", "gpu": "none" },
+ "capabilities": [
+ "probe:runtime.java", "probe:hardware.capacity", "apply:files.fetch",
+ "handoff:text", "handoff:secret", "apply:systemd.unit",
+ "verify:net.listen", "verify:backup.schedule"
+ ],
+ "inputs": [
+ { "key": "world_name", "label": "World name", "help": "Becomes the level-name in server.properties.", "placeholder": "survival-01" },
+ { "key": "max_players", "label": "Max players", "help": "Slot count advertised to clients.", "placeholder": "20" },
+ { "key": "motd", "label": "MOTD", "help": "Message of the day shown in the server list.", "placeholder": "Welcome to the server" }
+ ],
+ "handoffs": [
+ { "key": "rcon_password", "label": "RCON password", "secret": true }
+ ],
+ "steps": 8,
+ "manifest": "recipes/minecraft-java/recipe.yaml"
+ },
+ {
+ "slug": "plex",
+ "name": "Plex Media Server",
+ "version": "2.1.0",
+ "category": "Media",
+ "icon": "play",
+ "description": "Plex with hardware transcoding, claimed to your account and pointed at your library.",
+ "author": "serverkit",
+ "minutes": 6,
+ "featured": true,
+ "requirements": { "cpuCores": 4, "memoryMB": 8192, "diskGB": 200, "igpu": "required", "gpu": "none" },
+ "capabilities": [
+ "probe:device.dri", "handoff:text", "derive:config.libraries",
+ "apply:container.pull", "handoff:secret", "apply:container.run",
+ "verify:media.transcode"
+ ],
+ "inputs": [
+ { "key": "server_name", "label": "Server name", "help": "How this server appears in your Plex apps.", "placeholder": "acme-plex" },
+ { "key": "media_path", "label": "Media path", "help": "Absolute path to your library on the server.", "placeholder": "/srv/media" }
+ ],
+ "handoffs": [
+ { "key": "claim_token", "label": "Plex claim token", "secret": true, "url": "https://plex.tv/claim" }
+ ],
+ "steps": 6,
+ "manifest": "recipes/plex/recipe.yaml"
+ },
+ {
+ "slug": "jellyfin",
+ "name": "Jellyfin",
+ "version": "1.6.0",
+ "category": "Media",
+ "icon": "play",
+ "description": "Open-source media server, no account required. Hardware transcode when a device is present.",
+ "author": "serverkit",
+ "minutes": 4,
+ "featured": false,
+ "requirements": { "cpuCores": 2, "memoryMB": 4096, "diskGB": 100, "igpu": "preferred", "gpu": "none" },
+ "capabilities": [
+ "probe:device.dri", "handoff:text", "derive:config.jellyfin",
+ "apply:container.run", "handoff:secret", "verify:http.probe"
+ ],
+ "inputs": [
+ { "key": "server_name", "label": "Server name", "help": "How this server appears in Jellyfin clients.", "placeholder": "jellyfin" }
+ ],
+ "handoffs": [
+ { "key": "admin_password", "label": "Admin password", "secret": true }
+ ],
+ "steps": 5,
+ "manifest": "recipes/jellyfin/recipe.yaml"
+ },
+ {
+ "slug": "vaultwarden",
+ "name": "Vaultwarden",
+ "version": "1.2.0",
+ "category": "Security",
+ "icon": "lock",
+ "description": "Bitwarden-compatible vault behind Caddy, with TLS and an admin token.",
+ "author": "serverkit",
+ "minutes": 3,
+ "featured": false,
+ "requirements": { "cpuCores": 1, "memoryMB": 1024, "diskGB": 10, "igpu": "none", "gpu": "none" },
+ "capabilities": [
+ "probe:proxy.caddy", "handoff:text", "derive:config.env",
+ "apply:container.run", "apply:tls.cert", "handoff:secret",
+ "verify:http.probe"
+ ],
+ "inputs": [
+ { "key": "domain", "label": "Domain", "help": "The hostname the vault answers on.", "placeholder": "vault.acme.dev" },
+ { "key": "admin_email", "label": "Admin email", "help": "Used for the TLS certificate contact.", "placeholder": "[email protected]" }
+ ],
+ "handoffs": [
+ { "key": "admin_token", "label": "Admin token", "secret": true }
+ ],
+ "steps": 7,
+ "manifest": "recipes/vaultwarden/recipe.yaml"
+ },
+ {
+ "slug": "ollama",
+ "name": "Ollama",
+ "version": "0.9.0",
+ "category": "AI",
+ "icon": "zap",
+ "description": "Local model runner with an OpenAI-compatible endpoint. Unattended — no secrets needed.",
+ "author": "serverkit",
+ "minutes": 7,
+ "featured": true,
+ "requirements": { "cpuCores": 4, "memoryMB": 16384, "diskGB": 100, "igpu": "none", "gpu": "preferred" },
+ "capabilities": [
+ "probe:device.gpu", "handoff:text", "derive:config.models",
+ "apply:package.install", "apply:model.pull", "verify:http.probe"
+ ],
+ "inputs": [
+ { "key": "models", "label": "Models to pull", "help": "Comma-separated model tags.", "placeholder": "llama3.1:8b, qwen2.5:7b" },
+ { "key": "listen_port", "label": "Port", "help": "HTTP port for the API endpoint.", "placeholder": "11434" }
+ ],
+ "handoffs": [],
+ "steps": 6,
+ "manifest": "recipes/ollama/recipe.yaml"
+ }
+ ]
+}
diff --git a/backend/app/services/recipe_execution_service.py b/backend/app/services/recipe_execution_service.py
index 829d53ee..b345ccec 100644
--- a/backend/app/services/recipe_execution_service.py
+++ b/backend/app/services/recipe_execution_service.py
@@ -112,6 +112,7 @@ class RecipeExecutionService:
def start(cls, project: Project, normalized: Dict[str, Any], *,
user_id: Optional[int], slug: Optional[str] = None,
title: Optional[str] = None, manifest_row=None,
+ params: Optional[Dict[str, str]] = None,
wait: bool = False) -> Dict[str, Any]:
"""Create one Recipe run after capability and manifest preflight."""
recipe_steps = list(normalized.get('configure') or []) + list(
@@ -171,6 +172,9 @@ class RecipeExecutionService:
'title': title or normalized.get('project') or 'Guided outcome',
'requirements': normalized.get('requires') or {},
'capabilities': normalized.get('capabilities') or [],
+ # Up-front non-secret inputs (validated by the API layer);
+ # consumed instead of pausing when their step is reached.
+ 'params': dict(params or {}),
},
'project_id': project.id,
'environment_id': environment.id if environment else None,
@@ -225,8 +229,20 @@ class RecipeExecutionService:
db.session.commit()
secret = None
if not secret:
- return cls._pause_for_handoff(job, state, completed, step, stream)
- outcome = {'accepted': True, 'input_key': step['input']['key']}
+ preset = cls._preset_param(plan, step)
+ if preset is not None:
+ # Non-secret input collected up-front (install
+ # drawer): store it as the handoff value so the
+ # run continues without pausing.
+ cls._store_handoff_secret(
+ job, step_id, preset,
+ user_id=job.requested_by, expires_at=None)
+ outcome = {'accepted': True, 'preset': True}
+ else:
+ return cls._pause_for_handoff(
+ job, state, completed, step, stream)
+ else:
+ outcome = {'accepted': True, 'input_key': step['input']['key']}
else:
context = RecipeStepContext(
job=job, project=project, environment=environment,
@@ -301,6 +317,16 @@ class RecipeExecutionService:
return {'success': False, 'error': f'Failed to resume Recipe: {exc}'}
return {**result, 'job_id': job.id, 'job': job.to_dict()}
+ @staticmethod
+ def _preset_param(plan: Dict[str, Any], step: Dict[str, Any]) -> Optional[str]:
+ """Return the up-front value for a handoff input, if one was supplied
+ with the run. Only non-secret inputs reach this path (the API layer
+ rejects presets targeting secret inputs)."""
+ params = ((plan.get('recipe') or {}).get('params')) or {}
+ key = (step.get('input') or {}).get('key')
+ value = params.get(key)
+ return str(value) if value not in (None, '') else None
+
@classmethod
def _pause_for_handoff(cls, job, state, completed, step, stream):
input_spec = step.get('input') or {}
diff --git a/backend/app/services/recipe_registry_service.py b/backend/app/services/recipe_registry_service.py
new file mode 100644
index 00000000..142f312b
--- /dev/null
+++ b/backend/app/services/recipe_registry_service.py
@@ -0,0 +1,150 @@
+"""Remote Recipe registry.
+
+Mirrors the theme_registry_service pattern (a recipe is data, not code — no
+zips, no sha256, no permissions): the registry is a curated ``index.json`` in
+the ``serverkit-recipes`` repo, submitted via PR, published on merge. Each
+entry points at an executable ``serverkit.yaml`` manifest that
+``RecipeExecutionService`` runs as a normal deployment job.
+
+Design rules (same as the other registries):
+ - Read-only discovery. Nothing here auto-installs; runs are explicit.
+ - Offline-tolerant. A failed fetch falls back to the last good cache, then to
+ the bundled index (``app/data/recipes_index.json``) — the catalog never
+ blanks.
+ - Configurable. ``SERVERKIT_RECIPES_REGISTRY_URL`` points at the live index.
+ Unset ⇒ the public registry; set-but-EMPTY ⇒ disabled (bundled only — also
+ how the test suite stays offline).
+"""
+import logging
+import os
+from urllib.parse import urljoin
+
+import requests
+
+from app.utils.remote_index import CachedRemoteIndex
+
+from app.exceptions import (
+ DependencyUnavailableError,
+ NotFoundError,
+)
+
+logger = logging.getLogger(__name__)
+
+_BUNDLED_INDEX = os.path.join(
+ os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'data', 'recipes_index.json'
+)
+
+# The curated public index. Default goes through serverkit.ai, which proxies
+# the raw-GitHub index and rewrites each entry's manifest path to an absolute
+# /recipes/file URL. Operators can also point SERVERKIT_RECIPES_REGISTRY_URL
+# straight at the raw index:
+# https://raw.githubusercontent.com/jhd3197/serverkit-recipes/main/index.json
+DEFAULT_REGISTRY_URL = 'https://serverkit.ai/recipes/index.json'
+
+_FIELDS = {
+ 'slug': '',
+ 'name': '',
+ 'version': '1.0.0',
+ 'category': '',
+ 'icon': '',
+ 'description': '',
+ 'author': '',
+ 'minutes': None,
+ 'featured': False,
+ 'requirements': {},
+ 'capabilities': [],
+ 'inputs': [],
+ 'handoffs': [],
+ 'steps': 0,
+ 'manifest': '', # relative path to the executable recipe.yaml
+}
+
+
+def _resolve_url(path, base_url):
+ if not path or not isinstance(path, str):
+ return path
+ if path.startswith('http://') or path.startswith('https://'):
+ return path
+ return urljoin(base_url, path) if base_url else path
+
+
+def _normalize(raw, base_url=None):
+ if not isinstance(raw, dict) or not raw.get('slug'):
+ return None
+ out = {k: raw.get(k, d) if raw.get(k, d) is not None else d for k, d in _FIELDS.items()}
+ for list_field in ('capabilities', 'inputs', 'handoffs'):
+ if not isinstance(out[list_field], list):
+ out[list_field] = []
+ if not isinstance(out['requirements'], dict):
+ out['requirements'] = {}
+ # Keep the resolved absolute URL to the executable manifest for runs.
+ out['_manifest_url'] = _resolve_url(out['manifest'], base_url)
+ return out
+
+
+def _read_index_payload(payload, base_url=None):
+ recipes = payload.get('recipes') if isinstance(payload, dict) else None
+ if not isinstance(recipes, list):
+ return []
+ return [r for r in (_normalize(x, base_url) for x in recipes) if r]
+
+
+_index = CachedRemoteIndex(
+ name='Recipes',
+ env_var='SERVERKIT_RECIPES_REGISTRY_URL',
+ default_url=DEFAULT_REGISTRY_URL,
+ normalize_fn=_read_index_payload,
+ bundled_path=_BUNDLED_INDEX,
+ bundled_base_url='https://raw.githubusercontent.com/jhd3197/serverkit-recipes/main/',
+ ttl=3600,
+ ttl_env_var='SERVERKIT_RECIPES_REGISTRY_TTL',
+ error_ttl=60,
+)
+
+# Test seams, matching the convention the other registry services use.
+_cache = _index._cache
+
+
+def refresh(force=False):
+ """Return registry entries, refreshing when the cache is stale. Never
+ raises — falls back to last-good cache, then the bundled index."""
+ return _index.get(force=force)
+
+
+def list_catalog():
+ """Registry entries for the catalog grid (display fields only)."""
+ return [{k: e[k] for k in _FIELDS} for e in refresh()]
+
+
+def get_entry(slug):
+ for e in refresh():
+ if e['slug'] == slug:
+ return e
+ return None
+
+
+def registry_source_label():
+ return _cache.get('source')
+
+
+def get_manifest_text(slug):
+ """Fetch a registry recipe's full serverkit.yaml text. Raises typed
+ application errors; normalization happens at the call site so parse errors
+ surface where the run is started."""
+ entry = get_entry(slug)
+ if entry is None:
+ raise NotFoundError('Recipe not found in the registry')
+ manifest_url = entry.get('_manifest_url')
+ if not manifest_url:
+ raise NotFoundError('Registry entry has no manifest file')
+ try:
+ resp = requests.get(manifest_url, timeout=15, headers={
+ 'Accept': 'text/plain',
+ 'User-Agent': 'ServerKit-Recipes/1.0',
+ })
+ resp.raise_for_status()
+ return resp.text
+ except Exception as e:
+ logger.warning('Fetching recipe %s failed (%s): %s', slug, manifest_url, e)
+ raise DependencyUnavailableError(
+ 'Could not download the recipe from the registry') from e
diff --git a/backend/tests/test_recipe_registry.py b/backend/tests/test_recipe_registry.py
new file mode 100644
index 00000000..8f9c69e7
--- /dev/null
+++ b/backend/tests/test_recipe_registry.py
@@ -0,0 +1,191 @@
+"""Recipe registry (serverkit-recipes catalog) — browse, fetch, and
+server-targeted runs with up-front params."""
+
+import pytest
+
+from app import db
+from app.models.deployment_job import DeploymentJob
+from app.services import recipe_registry_service
+from app.services.manifest_spec_service import ManifestSpecService
+from app.services.recipe_execution_service import (
+ RecipeExecutionService,
+ RecipeStepRegistry,
+)
+
+
+def project(app):
+ from app.models import Environment, Project
+ from app.services.workspace_service import WorkspaceService
+
+ workspace = WorkspaceService.ensure_default_workspace()
+ row = Project(workspace_id=workspace.id, name='Recipe test', slug='recipe-test')
+ db.session.add(row)
+ db.session.commit()
+ environment = Environment(
+ project_id=row.id, name='Production', slug='production', is_default=True)
+ db.session.add(environment)
+ db.session.commit()
+ return row
+
+
+def owner(app):
+ from app.models import User
+ row = User(
+ username='recipe-owner', email='[email protected]',
+ role=User.ROLE_ADMIN, is_active=True)
+ row.set_password('testpass')
+ db.session.add(row)
+ db.session.commit()
+ return row
+
+
[email protected](autouse=True)
+def _reset_registry_cache():
+ """The registry cache is module-level; clear it around each test."""
+ recipe_registry_service._cache.update(
+ {'ts': 0.0, 'entries': None, 'source': None}
+ )
+ yield
+ recipe_registry_service._cache.update(
+ {'ts': 0.0, 'entries': None, 'source': None}
+ )
+
+
[email protected](autouse=True)
+def _recipe_registry():
+ RecipeStepRegistry.clear()
+ yield
+ RecipeStepRegistry.clear()
+
+
+class _FakeResp:
+ def __init__(self, payload=None, text='', status_code=200):
+ self.payload = payload
+ self.text = text
+ self.status_code = status_code
+
+ def raise_for_status(self):
+ assert self.status_code == 200
+
+ def json(self):
+ return self.payload
+
+
+def _mock_remote(monkeypatch, manifest_text='version: 1'):
+ def fake_get(url, *a, **k):
+ if url.endswith('/index.json'):
+ return _FakeResp(payload={
+ 'recipes': [{
+ 'slug': 'remote-recipe', 'name': 'Remote recipe',
+ 'version': '9.9.9', 'manifest': 'recipes/remote/recipe.yaml',
+ }],
+ })
+ return _FakeResp(text=manifest_text)
+ monkeypatch.setattr(recipe_registry_service.requests, 'get', fake_get)
+ monkeypatch.setenv('SERVERKIT_RECIPES_REGISTRY_URL', 'https://fake.local/index.json')
+
+
+def test_bundled_catalog_served_when_registry_disabled(monkeypatch):
+ monkeypatch.setenv('SERVERKIT_RECIPES_REGISTRY_URL', '') # disabled → bundled
+ catalog = recipe_registry_service.list_catalog()
+ slugs = {e['slug'] for e in catalog}
+ assert {'minecraft-java', 'plex', 'jellyfin', 'vaultwarden', 'ollama'} <= slugs
+ minecraft = next(e for e in catalog if e['slug'] == 'minecraft-java')
+ assert minecraft['requirements']['cpuCores'] == 4
+ assert recipe_registry_service.get_entry(
+ 'minecraft-java')['_manifest_url'].endswith(
+ '/recipes/minecraft-java/recipe.yaml')
+ assert recipe_registry_service.registry_source_label() == 'bundled'
+
+
+def test_registry_lists_remote_entries_and_fetches_manifest(client, auth_headers,
+ monkeypatch):
+ _mock_remote(monkeypatch)
+ resp = client.get('/api/v1/recipes/registry', headers=auth_headers)
+ assert resp.status_code == 200
+ data = resp.get_json()
+ assert data['source'] == 'remote'
+ assert [e['slug'] for e in data['recipes']] == ['remote-recipe']
+
+ resp = client.get('/api/v1/recipes/registry/nope', headers=auth_headers)
+ assert resp.status_code == 404
+
+ resp = client.get('/api/v1/recipes/registry/remote-recipe', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['recipe']['slug'] == 'remote-recipe'
+ assert '_manifest_url' not in body['recipe']
+ assert body['manifest'] == 'version: 1'
+
+
+def test_run_requires_server_or_project(client, auth_headers):
+ response = client.post('/api/v1/recipes/runs', headers=auth_headers, json={})
+ assert response.status_code == 400
+ assert 'server_id' in response.get_json()['error']
+
+
+def test_params_reject_unknown_keys(client, auth_headers, project):
+ response = client.post('/api/v1/recipes/runs', headers=auth_headers, json={
+ 'project_id': project.id,
+ 'params': {'not_an_input': 'x'},
+ 'manifest': {
+ 'version': 1,
+ 'capabilities': ['handoff:text'],
+ 'configure': [{
+ 'id': 'ask', 'type': 'handoff', 'kind': 'text',
+ 'input': {'key': 'world_name', 'label': 'World name',
+ 'secret': False},
+ }],
+ },
+ })
+ assert response.status_code == 400
+ assert 'not_an_input' in response.get_json()['error']
+
+
+def test_params_reject_secret_inputs(client, auth_headers, project):
+ response = client.post('/api/v1/recipes/runs', headers=auth_headers, json={
+ 'project_id': project.id,
+ 'params': {'rcon_password': 'hunter2'},
+ 'manifest': {
+ 'version': 1,
+ 'capabilities': ['handoff:secret'],
+ 'configure': [{
+ 'id': 'ask', 'type': 'handoff', 'kind': 'secret',
+ 'input': {'key': 'rcon_password', 'label': 'RCON password'},
+ }],
+ },
+ })
+ assert response.status_code == 400
+ assert 'securely' in response.get_json()['error']
+
+
+def test_preset_params_satisfy_non_secret_handoffs(project, owner):
+ """A param supplied at start time is stored as the handoff value when its
+ step is reached — the run never pauses on it."""
+ calls = []
+
+ def apply_step(context):
+ calls.append(('apply', context.input('world_name')))
+ return {'ok': True}
+
+ RecipeStepRegistry.register('apply', 'test-run', apply_step)
+ normalized = ManifestSpecService.normalize({
+ 'version': 1, 'project': 'Preset test',
+ 'capabilities': ['handoff:text', 'apply:test-run'],
+ 'configure': [
+ {'id': 'ask-world', 'type': 'handoff', 'kind': 'text',
+ 'input': {'key': 'world_name', 'label': 'World name',
+ 'secret': False}},
+ {'id': 'run', 'type': 'apply', 'kind': 'test-run',
+ 'dependsOn': ['ask-world']},
+ ],
+ })
+ started = RecipeExecutionService.start(
+ project, normalized, user_id=owner.id,
+ params={'world_name': 'survival-01'}, wait=True)
+ assert started['success'] is True, started
+ job = DeploymentJob.query.get(started['job_id'])
+ assert job.status == 'succeeded'
+ assert calls == [('apply', 'survival-01')]
diff --git a/frontend/src/components/marketplace/marketTabs.jsx b/frontend/src/components/marketplace/marketTabs.jsx
index d8ac9096..76a449fd 100644
--- a/frontend/src/components/marketplace/marketTabs.jsx
+++ b/frontend/src/components/marketplace/marketTabs.jsx
@@ -1,11 +1,12 @@
-import { Puzzle, PackageCheck, Download } from 'lucide-react';
+import { Puzzle, PackageCheck, Download, ChefHat } from 'lucide-react';
// Shared sub-nav for the Extensions page group (Extensions / Installed /
-// Downloads). Rendered in each page's <PageTopbar tabs={MARKET_TABS}> — the
+// Recipes / Downloads). Rendered in each page's <PageTopbar tabs={MARKET_TABS}> �?" the
// top-bar layout replaces the old sidebar sub-menu (see docs/REDESIGN_MAP.md
-// §6 dec. 3). Installed is a real route (/extensions/installed) so it deep-links.
+// A6 dec. 3). Installed is a real route (/extensions/installed) so it deep-links.
export const MARKET_TABS = [
{ to: '/extensions', labelKey: 'common.labels.extensions', label: 'Extensions', end: true, icon: <Puzzle size={15} /> },
{ to: '/extensions/installed', labelKey: 'app.marketTabs.installed', label: 'Installed', icon: <PackageCheck size={15} /> },
+ { to: '/extensions/recipes', labelKey: 'app.marketTabs.recipes', label: 'Recipes', icon: <ChefHat size={15} /> },
{ to: '/downloads', labelKey: 'app.marketTabs.downloads', label: 'Downloads', icon: <Download size={15} /> },
];
diff --git a/frontend/src/components/services/serviceTabs.jsx b/frontend/src/components/services/serviceTabs.jsx
index ad12c507..4ce0ad8d 100644
--- a/frontend/src/components/services/serviceTabs.jsx
+++ b/frontend/src/components/services/serviceTabs.jsx
@@ -1,12 +1,13 @@
-import { Box, Plus, LayoutTemplate, Activity } from 'lucide-react';
+import { Box, Plus, LayoutTemplate, Activity, ChefHat } from 'lucide-react';
// Shared sub-nav for the Services page group (Services / New Service /
-// Templates / Deploy Activity). Rendered in each page's
+// Templates / Recipes / Deploy Activity). Rendered in each page's
// <PageTopbar tabs={SERVICE_TABS}> — the demo's top-bar layout replaces the old
// sidebar sub-menu (see docs/REDESIGN_MAP.md §6 decision 3).
export const SERVICE_TABS = [
{ to: '/services', labelKey: 'common.labels.services', label: 'Services', end: true, icon: <Box size={15} /> },
{ to: '/services/new', labelKey: 'app.serviceTabs.newService', label: 'New Service', icon: <Plus size={15} /> },
{ to: '/templates', labelKey: 'app.serviceTabs.templates', label: 'Templates', icon: <LayoutTemplate size={15} /> },
+ { to: '/recipes', labelKey: 'app.serviceTabs.recipes', label: 'Recipes', icon: <ChefHat size={15} /> },
{ to: '/deployments', labelKey: 'app.serviceTabs.deployActivity', label: 'Deploy Activity', icon: <Activity size={15} /> },
];
diff --git a/frontend/src/hooks/useRecipeCatalog.js b/frontend/src/hooks/useRecipeCatalog.js
new file mode 100644
index 00000000..bfe9af6d
--- /dev/null
+++ b/frontend/src/hooks/useRecipeCatalog.js
@@ -0,0 +1,59 @@
+import { useTranslation } from 'react-i18next';
+
+import { api } from '../services/api';
+import { useToast } from '../contexts/ToastContext';
+import { useServerMutation, useServerQuery } from './useServerQuery';
+
+// Data door for the Recipe catalog (serverkit-recipes registry). Pages render
+// from this hook; raw api.* calls and query-layer error presentation stay here.
+
+export function useRecipeCatalog() {
+ const { t } = useTranslation();
+ const toast = useToast();
+
+ const registryQuery = useServerQuery(
+ ['recipes', 'registry'],
+ () => api.getRecipeRegistry(),
+ {
+ // The backend serves last-good/bundled when upstream is down, so
+ // failures here are local (auth/network); surface once.
+ staleTime: 60_000,
+ onError: () => toast.error(
+ t('app.recipes.loadFailed', 'Could not load the recipe catalog'),
+ ),
+ },
+ );
+
+ const serversQuery = useServerQuery(
+ ['recipes', 'target-servers'],
+ () => api.getServers(),
+ { staleTime: 15_000 },
+ );
+
+ const startRun = useServerMutation(
+ (body) => api.startRecipeRun(body),
+ );
+
+ return {
+ recipes: registryQuery.data?.recipes ?? [],
+ source: registryQuery.data?.source ?? null,
+ isLoading: registryQuery.isLoading || serversQuery.isLoading,
+ servers: serversQuery.data?.servers ?? [],
+ startRun,
+ };
+}
+
+// Start one recipe run. Returns the deployment job id; errors are toasted by
+// the mutation wrapper so callers can just navigate on success.
+export async function runRecipe({ startRun, toast, t }, body, { serverName }) {
+ try {
+ const result = await startRun.mutateAsync(body);
+ toast.success(t('app.recipes.started', 'Recipe started on {{server}}.', {
+ server: serverName,
+ }));
+ return result.job_id;
+ } catch (err) {
+ toast.error(err.message || t('app.recipes.startFailed', 'Could not start the recipe'));
+ return null;
+ }
+}
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index 6c036e40..e0253ef6 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -3210,7 +3210,8 @@
},
"marketTabs": {
"downloads": "Downloads",
- "installed": "Installed"
+ "installed": "Installed",
+ "recipes": "Recipes"
},
"marketplace": {
"anUnsignedRelease": "{{value}} an unsigned release?",
@@ -4250,6 +4251,32 @@
"vault": "Vault",
"webhook": "Webhook"
},
+ "recipes": {
+ "askedDuringRun": "Asked for during the run",
+ "blocked": "This server does not meet the requirements above. Pick another server.",
+ "bundledSource": "Showing the bundled catalog — the live registry is unreachable right now.",
+ "cpu": "CPU",
+ "disk": "Disk",
+ "featured": "Featured",
+ "install": "Install",
+ "lede": "Ready-to-go installers that run as real operations — probe, derive, apply, verify. Secrets are asked for mid-run and kept in the vault.",
+ "loadFailed": "Could not load the recipe catalog",
+ "memory": "Memory",
+ "noHandoffs": "Nothing — this recipe runs unattended.",
+ "noServers": "No running servers. Start one first.",
+ "noneMatch": "No recipes match",
+ "noneMatchHint": "Try a different search or category.",
+ "preflight": "Preflight",
+ "runOn": "Run on",
+ "runRecipe": "Run recipe",
+ "runTitle": "Run {{name}}",
+ "searchPlaceholder": "Search recipes…",
+ "startFailed": "Could not start the recipe",
+ "started": "Recipe started on {{server}}.",
+ "stepsLine": "{{steps}} steps · {{handoffs}} secret ask{{plural}}",
+ "unavailable": "Recipe catalog unavailable",
+ "unavailableHint": "The registry could not be reached and no bundled copy is present."
+ },
"recycleBinTab": {
"couldNotLoadTheRecycleBin": "Could not load the recycle bin",
"daysSoTheyCanBePut": "days so they can be put back. Restoring returns the record itself — it does not re-apply configuration that was torn down at delete time (a domain’s vhost, for example).",
@@ -4464,6 +4491,7 @@
"notifications": "Notifications",
"projects": "Projects",
"queueBus": "Queue Bus",
+ "recipes": "Recipes",
"register": "Register",
"runningAlongsideAnotherPanel": "Running Alongside Another Panel",
"serverTemplates": "Server Templates",
@@ -5090,6 +5118,7 @@
"serviceTabs": {
"deployActivity": "Deploy Activity",
"newService": "New Service",
+ "recipes": "Recipes",
"templates": "Templates"
},
"serviceTypes": {
@@ -6686,7 +6715,7 @@
"warnings2": "Warnings ("
},
"walkthroughs": {
- "allRecipes": "All recipes",
+ "all": "All walkthroughs",
"checkStatus": "Check status",
"chooseServiceSource": "Choose where the code lives",
"chooseServiceSourceDescription": "Pick GitHub, another Git remote, a local path, or a ZIP upload.",
@@ -6712,7 +6741,6 @@
"openWizard": "Open wizard",
"pairAuthenticator": "Pair your authenticator",
"pairAuthenticatorDescription": "Scan the QR code, then enter the six-digit code from your app.",
- "recipes": "Recipes",
"reviewService": "Review the detected setup",
"reviewServiceDescription": "Confirm the name, runtime, build method, project, and environment.",
"startEnrollment": "Start enrollment",
@@ -6720,6 +6748,7 @@
"stepsMeta": "{{count}} steps · {{duration}}",
"stopShort": "Stop",
"threeMinutes": "About 3 minutes",
+ "title": "Walkthroughs",
"verifyAndSaveCodes": "Verify and save recovery codes",
"verifyAndSaveCodesDescription": "The guide verifies the live account status—it never stores your code or secret."
},
diff --git a/frontend/src/pages/Recipes.jsx b/frontend/src/pages/Recipes.jsx
new file mode 100644
index 00000000..32f1470b
--- /dev/null
+++ b/frontend/src/pages/Recipes.jsx
@@ -0,0 +1,377 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import {
+ Box, ChefHat, Play, Lock, Zap, Database, Globe, Shield, Search,
+ AlertTriangle, Check, X, Loader2,
+} from 'lucide-react';
+
+import { Drawer } from '../components/ds';
+import EmptyState from '../components/EmptyState';
+import FormField from '../components/FormField';
+import { runRecipe, useRecipeCatalog } from '../hooks/useRecipeCatalog';
+import { useToast } from '../contexts/ToastContext';
+import { formatBytes } from '../utils/formatBytes';
+
+// Recipe catalog (serverkit-recipes registry). A Recipe is a ready-to-go
+// installer: pick one, point it at a server, fill in the non-secret inputs,
+// run it. Secret inputs pause the run mid-way and arrive as handoffs in
+// Operations. This page only browses and starts — progress lives in the
+// deployment console like every other long operation.
+
+const ICONS = {
+ box: Box,
+ play: Play,
+ lock: Lock,
+ zap: Zap,
+ database: Database,
+ globe: Globe,
+ shield: Shield,
+};
+
+function RecipeIcon({ icon }) {
+ const Icon = ICONS[icon] || ChefHat;
+ return <Icon size={17} />;
+}
+
+const GB = 1024 * 1024 * 1024;
+
+function preflight(requirements, server) {
+ if (!server || !requirements) return [];
+ const rows = [];
+ if (requirements.cpuCores) {
+ rows.push({
+ key: 'cpu',
+ need: `${requirements.cpuCores} vCPU`,
+ have: server.cpu_cores ? `${server.cpu_cores} vCPU` : '—',
+ ok: !!server.cpu_cores && server.cpu_cores >= requirements.cpuCores,
+ });
+ }
+ if (requirements.memoryMB) {
+ rows.push({
+ key: 'mem',
+ need: formatBytes(requirements.memoryMB * GB, { decimals: 0 }),
+ have: formatBytes(server.total_memory, { decimals: 0 }),
+ ok: !!server.total_memory && server.total_memory >= requirements.memoryMB * GB,
+ });
+ }
+ if (requirements.diskGB) {
+ rows.push({
+ key: 'disk',
+ need: formatBytes(requirements.diskGB * GB, { decimals: 0 }),
+ have: formatBytes(server.total_disk, { decimals: 0 }),
+ ok: !!server.total_disk && server.total_disk >= requirements.diskGB * GB,
+ });
+ }
+ return rows;
+}
+
+const blockersOf = rows => rows.filter(r => !r.ok);
+
+export default function Recipes() {
+ const { t } = useTranslation();
+ const toast = useToast();
+ const navigate = useNavigate();
+ const { recipes, source, isLoading, servers, startRun } = useRecipeCatalog();
+
+ const [search, setSearch] = useState('');
+ const [category, setCategory] = useState('all');
+
+ // Install drawer state.
+ const [selected, setSelected] = useState(null);
+ const [targetId, setTargetId] = useState(null);
+ const [paramValues, setParamValues] = useState({});
+ const [starting, setStarting] = useState(false);
+
+ // Reset the drawer target once the server list arrives so the pre-selected
+ // server is always one that exists in the current workspace scope.
+ useEffect(() => {
+ if (!selected || targetId != null) return;
+ const running = servers.find(s => s.status === 'running');
+ setTargetId(running?.id ?? servers[0]?.id ?? null);
+ }, [selected, servers, targetId]);
+
+ const categories = useMemo(() => (
+ ['all', ...new Set(recipes.map(r => r.category).filter(Boolean))]
+ ), [recipes]);
+
+ const visible = useMemo(() => {
+ const q = search.trim().toLowerCase();
+ return recipes.filter(r => (
+ (category === 'all' || r.category === category)
+ && (!q || `${r.name} ${r.description}`.toLowerCase().includes(q))
+ ));
+ }, [recipes, search, category]);
+
+ const targetServer = useMemo(
+ () => servers.find(s => String(s.id) === String(targetId)) || null,
+ [servers, targetId],
+ );
+
+ const openInstall = useCallback((recipe) => {
+ setSelected(recipe);
+ setTargetId(targetServer?.id ?? servers.find(s => s.status === 'running')?.id ?? null);
+ setParamValues(Object.fromEntries(
+ (recipe.inputs || []).map(i => [i.key, i.placeholder || '']),
+ ));
+ }, [servers, targetServer]);
+
+ const selectedRows = useMemo(
+ () => preflight(selected?.requirements, targetServer),
+ [selected, targetServer],
+ );
+ const selectedBlockers = blockersOf(selectedRows);
+
+ const handleStart = async () => {
+ if (!selected || !targetServer) return;
+ setStarting(true);
+ const jobId = await runRecipe(
+ { startRun, toast, t },
+ {
+ registry_slug: selected.slug,
+ server_id: targetServer.id,
+ params: paramValues,
+ },
+ { serverName: targetServer.name },
+ );
+ setStarting(false);
+ if (!jobId) return;
+ setSelected(null);
+ navigate(`/deployments/${jobId}`);
+ };
+
+ return (
+ <div className="recipes-page">
+ <div className="recipes-page__head">
+ <p className="recipes-page__lede">
+ {t('app.recipes.lede', 'Ready-to-go installers that run as real operations — probe, derive, apply, verify. Secrets are asked for mid-run and kept in the vault.')}
+ </p>
+ <label className="recipes-page__search">
+ <Search size={14} />
+ <input
+ type="search"
+ value={search}
+ placeholder={t('app.recipes.searchPlaceholder', 'Search recipes…')}
+ onChange={e => setSearch(e.target.value)}
+ />
+ </label>
+ </div>
+
+ {categories.length > 1 && (
+ <div className="recipes-page__cats">
+ {categories.map(cat => (
+ <button
+ key={cat}
+ type="button"
+ className={`sk-pill${category === cat ? ' is-active' : ''}`}
+ onClick={() => setCategory(cat)}
+ >
+ {cat === 'all' ? t('common.labels.all', 'All') : cat}
+ </button>
+ ))}
+ </div>
+ )}
+
+ {isLoading ? (
+ <div className="recipes-page__loading"><Loader2 size={18} className="spin" /></div>
+ ) : !recipes.length ? (
+ <EmptyState
+ icon={AlertTriangle}
+ title={t('app.recipes.unavailable', 'Recipe catalog unavailable')}
+ description={t('app.recipes.unavailableHint', 'The registry could not be reached and no bundled copy is present.')}
+ />
+ ) : !visible.length ? (
+ <EmptyState
+ icon={ChefHat}
+ title={t('app.recipes.noneMatch', 'No recipes match')}
+ description={t('app.recipes.noneMatchHint', 'Try a different search or category.')}
+ />
+ ) : (
+ <div className="recipes-page__grid">
+ {visible.map(recipe => {
+ const handoffCount = (recipe.handoffs || []).length;
+ return (
+ <div className="recipe-card" key={recipe.slug}>
+ <div className="recipe-card__top">
+ <span className="recipe-card__ico"><RecipeIcon icon={recipe.icon} /></span>
+ <div className="recipe-card__id">
+ <div className="recipe-card__name">{recipe.name}</div>
+ <div className="recipe-card__meta mono">
+ v{recipe.version}{recipe.category ? ` · ${recipe.category}` : ''}
+ {recipe.minutes ? ` · ~${recipe.minutes} min` : ''}
+ </div>
+ </div>
+ {recipe.featured && (
+ <span className="sk-pill recipe-card__featured">
+ {t('app.recipes.featured', 'Featured')}
+ </span>
+ )}
+ </div>
+ <p className="recipe-card__desc">{recipe.description}</p>
+ <div className="recipe-card__reqs mono">
+ {(recipe.requirements?.cpuCores)
+ && <span>{recipe.requirements.cpuCores} vCPU</span>}
+ {(recipe.requirements?.memoryMB)
+ && <span>{formatBytes(recipe.requirements.memoryMB * GB, { decimals: 0 })}</span>}
+ {(recipe.requirements?.diskGB)
+ && <span>{formatBytes(recipe.requirements.diskGB * GB, { decimals: 0 })}</span>}
+ {(recipe.requirements?.igpu && recipe.requirements.igpu !== 'none')
+ && <span className={recipe.requirements.igpu === 'required' ? 'is-hard' : ''}>
+ iGPU {recipe.requirements.igpu}
+ </span>}
+ {(recipe.requirements?.gpu && recipe.requirements.gpu !== 'none')
+ && <span className={recipe.requirements.gpu === 'required' ? 'is-hard' : ''}>
+ GPU {recipe.requirements.gpu}
+ </span>}
+ </div>
+ <div className="recipe-card__foot">
+ <span className="recipe-card__steps mono">
+ {t('app.recipes.stepsLine', '{{steps}} steps · {{handoffs}} secret ask{{plural}}', {
+ steps: recipe.steps ?? '?',
+ handoffs: handoffCount || 0,
+ plural: handoffCount === 1 ? '' : 's',
+ })}
+ </span>
+ <button
+ type="button"
+ className="btn btn-primary btn-sm"
+ onClick={() => openInstall(recipe)}
+ >
+ <Play size={13} />
+ {t('app.recipes.install', 'Install')}
+ </button>
+ </div>
+ </div>
+ );
+ })}
+ </div>
+ )}
+
+ <Drawer
+ open={!!selected}
+ onOpenChange={open => { if (!open) setSelected(null); }}
+ title={selected ? t('app.recipes.runTitle', 'Run {{name}}', { name: selected.name }) : ''}
+ subtitle={selected ? `recipe ${selected.slug}@${selected.version}` : ''}
+ icon={selected ? <RecipeIcon icon={selected.icon} /> : null}
+ width={520}
+ >
+ {selected && (
+ <div className="recipe-install">
+ <FormField label={t('app.recipes.runOn', 'Run on')}>
+ <div className="recipe-install__servers card">
+ {servers.filter(s => s.status === 'running').map(server => (
+ <button
+ type="button"
+ key={server.id}
+ className={`recipe-install__server${String(targetId) === String(server.id) ? ' is-on' : ''}`}
+ onClick={() => setTargetId(server.id)}
+ >
+ <span className="recipe-install__radio" aria-hidden="true" />
+ <span className="recipe-install__srvname">{server.name}</span>
+ <span className="recipe-install__srvspec mono">
+ {server.cpu_cores ? `${server.cpu_cores} vCPU · ` : ''}
+ {formatBytes(server.total_memory, { decimals: 0 })}
+ </span>
+ {String(targetId) === String(server.id) && <Check size={15} />}
+ </button>
+ ))}
+ {!servers.some(s => s.status === 'running') && (
+ <p className="recipe-install__nosrv">
+ {t('app.recipes.noServers', 'No running servers. Start one first.')}
+ </p>
+ )}
+ </div>
+ </FormField>
+
+ {!!selectedRows.length && (
+ <FormField label={t('app.recipes.preflight', 'Preflight')}>
+ <div className="recipe-install__preflight card">
+ {selectedRows.map(row => {
+ const label = row.key === 'cpu'
+ ? t('app.recipes.cpu', 'CPU')
+ : row.key === 'mem'
+ ? t('app.recipes.memory', 'Memory')
+ : t('app.recipes.disk', 'Disk');
+ return (
+ <div key={row.key} className={`recipe-preflight${row.ok ? ' is-ok' : ' is-bad'}`}>
+ {row.ok ? <Check size={13} /> : <X size={13} />}
+ <span className="recipe-preflight__k">{label}</span>
+ <span className="recipe-preflight__need mono">{row.need}</span>
+ <span className="recipe-preflight__have mono">{row.have}</span>
+ </div>
+ );
+ })}
+ </div>
+ {!!selectedBlockers.length && (
+ <p className="recipe-install__blocked">
+ {t('app.recipes.blocked', 'This server does not meet the requirements above. Pick another server.')}
+ </p>
+ )}
+ </FormField>
+ )}
+
+ {!!(selected.inputs || []).length && selected.inputs.map(input => (
+ <FormField
+ key={input.key}
+ label={input.label}
+ htmlFor={`ri-${input.key}`}
+ hint={input.help}
+ >
+ <input
+ id={`ri-${input.key}`}
+ className="form-input"
+ value={paramValues[input.key] ?? ''}
+ placeholder={input.placeholder}
+ onChange={e => setParamValues(v => ({ ...v, [input.key]: e.target.value }))}
+ />
+ </FormField>
+ ))}
+
+ <FormField label={t('app.recipes.askedDuringRun', 'Asked for during the run')}>
+ {(selected.handoffs || []).length ? (
+ <div className="recipe-install__handoffs card">
+ {selected.handoffs.map(handoff => (
+ <div className="recipe-handoff-row" key={handoff.key}>
+ <Lock size={13} />
+ <span className="recipe-handoff-row__k">{handoff.label}</span>
+ {handoff.url && (
+ <a href={handoff.url} target="_blank" rel="noreferrer" className="recipe-handoff-row__url">
+ {handoff.url.replace(/^https?:\/\//, '')}
+ </a>
+ )}
+ </div>
+ ))}
+ </div>
+ ) : (
+ <p className="recipe-install__unattended">
+ {t('app.recipes.noHandoffs', 'Nothing — this recipe runs unattended.')}
+ </p>
+ )}
+ </FormField>
+
+ <div className="recipe-install__actions">
+ <button type="button" className="btn" onClick={() => setSelected(null)}>
+ {t('common.actions.cancel', 'Cancel')}
+ </button>
+ <button
+ type="button"
+ className="btn btn-primary"
+ disabled={!targetServer || !!selectedBlockers.length || starting}
+ onClick={handleStart}
+ >
+ {starting ? <Loader2 size={14} className="spin" /> : <Play size={14} />}
+ {t('app.recipes.runRecipe', 'Run recipe')}
+ </button>
+ </div>
+ </div>
+ )}
+ </Drawer>
+
+ {source === 'bundled' && !!recipes.length && (
+ <p className="recipes-page__source mono">
+ {t('app.recipes.bundledSource', 'Showing the bundled catalog — the live registry is unreachable right now.')}
+ </p>
+ )}
+ </div>
+ );
+}
diff --git a/frontend/src/routes/__tests__/routeManifest.test.mjs b/frontend/src/routes/__tests__/routeManifest.test.mjs
index 3628a989..a7b68e5b 100644
--- a/frontend/src/routes/__tests__/routeManifest.test.mjs
+++ b/frontend/src/routes/__tests__/routeManifest.test.mjs
@@ -13,7 +13,7 @@ import {
} from '../routeManifest.js';
test('core route paths and ids are unique', () => {
- assert.equal(CORE_ROUTES.length, 96, 'route changes must update the parity baseline intentionally');
+ assert.equal(CORE_ROUTES.length, 98, 'route changes must update the parity baseline intentionally');
assert.equal(new Set(CORE_ROUTES.map(({ id }) => id)).size, CORE_ROUTES.length);
assert.equal(new Set(CORE_ROUTES.map(({ path }) => path)).size, CORE_ROUTES.length);
});
diff --git a/frontend/src/routes/routeComponents.jsx b/frontend/src/routes/routeComponents.jsx
index 66490f54..55fdd993 100644
--- a/frontend/src/routes/routeComponents.jsx
+++ b/frontend/src/routes/routeComponents.jsx
@@ -38,6 +38,7 @@ export const ROUTE_COMPONENTS = Object.freeze({
PublicStatusPage: lazy(() => import('../pages/PublicStatusPage')),
QueueDetail: lazy(() => import('../pages/QueueDetail')),
QueueOperations: lazy(() => import('../pages/QueueOperations')),
+ Recipes: lazy(() => import('../pages/Recipes')),
Register: lazy(() => import('../pages/Register')),
Security: lazy(() => import('../pages/Security')),
ServerDetail: lazy(() => import('../pages/ServerDetail')),
diff --git a/frontend/src/routes/routeManifest.js b/frontend/src/routes/routeManifest.js
index 2ca96da9..c1bd249a 100644
--- a/frontend/src/routes/routeManifest.js
+++ b/frontend/src/routes/routeManifest.js
@@ -36,6 +36,7 @@ export const CORE_ROUTES = Object.freeze([
{ id: 'templates', path: '/templates', placement: 'dashboard', group: 'services', component: 'Templates', titleKey: 'app.routeManifest.templates', title: 'Templates' },
{ id: 'deployments', path: '/deployments', placement: 'dashboard', group: 'services', component: 'Deployments', titleKey: 'app.routeManifest.deploymentActivity', title: 'Deployment Activity' },
{ id: 'deploy-console', path: '/deployments/:jobId', placement: 'dashboard', group: 'services', component: 'DeployConsole', titleKey: 'app.routeManifest.deploymentActivity', title: 'Deployment Activity' },
+ { id: 'recipes', path: '/recipes', placement: 'dashboard', group: 'services', component: 'Recipes', titleKey: 'app.routeManifest.recipes', title: 'Recipes' },
{ id: 'service-detail', path: '/services/:id', placement: 'dashboard', component: 'ServiceDetail', titleKey: 'common.labels.services', title: 'Services' },
{ id: 'service-detail-tab', path: '/services/:id/:tab', placement: 'dashboard', component: 'ServiceDetail', titleKey: 'common.labels.services', title: 'Services' },
{ id: 'service-detail-section', path: '/services/:id/:tab/:section', placement: 'dashboard', component: 'ServiceDetail', titleKey: 'common.labels.services', title: 'Services' },
@@ -84,6 +85,7 @@ export const CORE_ROUTES = Object.freeze([
{ id: 'extensions', path: '/extensions', placement: 'dashboard', group: 'marketplace', component: 'Marketplace', titleKey: 'common.labels.extensions', title: 'Extensions' },
{ id: 'installed-extensions', path: '/extensions/installed', placement: 'dashboard', group: 'marketplace', component: 'Marketplace', titleKey: 'app.routeManifest.installedExtensions', title: 'Installed Extensions' },
+ { id: 'marketplace-recipes', path: '/extensions/recipes', placement: 'dashboard', group: 'marketplace', component: 'Recipes', titleKey: 'app.routeManifest.recipes', title: 'Recipes' },
{ id: 'downloads', path: '/downloads', placement: 'dashboard', group: 'marketplace', component: 'Downloads', titleKey: 'app.routeManifest.downloads', title: 'Downloads' },
{ id: 'legacy-marketplace', path: '/marketplace', placement: 'dashboard', redirect: '/extensions' },
{ id: 'legacy-marketplace-installed', path: '/marketplace/installed', placement: 'dashboard', redirect: '/extensions/installed' },
diff --git a/frontend/src/services/api/index.js b/frontend/src/services/api/index.js
index 7098e243..bbb2e272 100644
--- a/frontend/src/services/api/index.js
+++ b/frontend/src/services/api/index.js
@@ -53,6 +53,7 @@ import * as recycleBinMethods from './recycleBin.js';
import * as errorLogMethods from './errorLogs.js';
import * as walkthroughMethods from './walkthroughs.js';
import * as diskMethods from './disk.js';
+import * as recipeMethods from './recipes.js';
class ApiService extends ApiClient {
constructor() {
@@ -113,6 +114,7 @@ class ApiService extends ApiClient {
errorLogMethods,
walkthroughMethods,
diskMethods,
+ recipeMethods,
];
for (const mod of modules) {
for (const [key, fn] of Object.entries(mod)) {
diff --git a/frontend/src/services/api/recipes.js b/frontend/src/services/api/recipes.js
new file mode 100644
index 00000000..dc26034c
--- /dev/null
+++ b/frontend/src/services/api/recipes.js
@@ -0,0 +1,21 @@
+// Recipe registry API (the serverkit-recipes catalog) + run start.
+// Browsing is read-only and offline-tolerant on the backend (bundled index
+// fallback); starting a run is the same admin-gated deployment job surface as
+// any other operation.
+
+// Browse the curated catalog. Returns { recipes: [...], source }.
+export async function getRecipeRegistry() {
+ return this.request('/recipes/registry');
+}
+
+// One catalog entry + its full executable manifest text.
+export async function getRecipeRegistryEntry(slug) {
+ return this.request(`/recipes/registry/${encodeURIComponent(slug)}`);
+}
+
+// Start a recipe run. Body: { registry_slug | content | manifest,
+// server_id | project_id, params?, slug?, title? }. Secret inputs are NOT
+// params — they arrive as mid-run handoffs.
+export async function startRecipeRun(body) {
+ return this.request('/recipes/runs', { method: 'POST', body });
+}
diff --git a/frontend/src/styles/main.scss b/frontend/src/styles/main.scss
index e78a3212..f2c30a1d 100644
--- a/frontend/src/styles/main.scss
+++ b/frontend/src/styles/main.scss
@@ -155,4 +155,5 @@
@import 'pages/_telemetry';
@import 'pages/_jobs';
@import 'pages/_errors';
+@import 'pages/_recipes';
@import 'pages/_test-sandbox';
diff --git a/frontend/src/styles/pages/_recipes.scss b/frontend/src/styles/pages/_recipes.scss
new file mode 100644
index 00000000..de7f8cc3
--- /dev/null
+++ b/frontend/src/styles/pages/_recipes.scss
@@ -0,0 +1,343 @@
+// Recipe catalog (serverkit-recipes registry) — cards grid + install drawer.
+
+.recipes-page {
+ max-width: 1320px;
+ margin: 0 auto;
+ padding: 22px 30px 60px;
+
+ &__head {
+ display: flex;
+ align-items: flex-end;
+ gap: $spacing-lg;
+ margin-bottom: $spacing-md;
+ }
+
+ &__lede {
+ flex: 1;
+ min-width: 0;
+ margin: 0;
+ color: var(--text-secondary);
+ font-size: 13px;
+ line-height: 1.55;
+ max-width: 640px;
+ }
+
+ &__search {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ width: 260px;
+ height: 34px;
+ padding: 0 10px;
+ border: 1px solid var(--border-color);
+ border-radius: $radius-md;
+ background: var(--bg-card);
+ color: var(--text-tertiary);
+
+ input {
+ flex: 1;
+ min-width: 0;
+ border: none;
+ outline: none;
+ background: transparent;
+ color: var(--text-primary);
+ font-size: 13px;
+ }
+ }
+
+ &__cats {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 8px;
+ margin-bottom: $spacing-md;
+
+ .sk-pill {
+ cursor: pointer;
+ opacity: 0.72;
+
+ &.is-active {
+ opacity: 1;
+ border-color: var(--primary-color);
+ color: var(--primary-color);
+ }
+ }
+ }
+
+ &__grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+ gap: $spacing-md;
+ }
+
+ &__loading {
+ display: flex;
+ justify-content: center;
+ padding: 80px 0;
+ color: var(--text-tertiary);
+ }
+
+ &__source {
+ margin-top: $spacing-md;
+ text-align: center;
+ font-size: 11.5px;
+ color: var(--text-ghost);
+ }
+}
+
+.recipe-card {
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+ padding: $spacing-md;
+ border: 1px solid var(--border-color);
+ border-radius: $radius-lg;
+ background: var(--bg-card);
+
+ &__top {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ }
+
+ &__ico {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 34px;
+ height: 34px;
+ flex-shrink: 0;
+ border-radius: $radius-md;
+ background: color-mix(in srgb, var(--primary-color) 12%, transparent);
+ color: var(--primary-color);
+ }
+
+ &__id {
+ flex: 1;
+ min-width: 0;
+ }
+
+ &__name {
+ font-weight: 600;
+ font-size: 14px;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ }
+
+ &__meta {
+ font-size: 11px;
+ color: var(--text-tertiary);
+ margin-top: 1px;
+ }
+
+ &__featured {
+ flex-shrink: 0;
+ }
+
+ &__desc {
+ margin: 0;
+ font-size: 12.5px;
+ line-height: 1.5;
+ color: var(--text-secondary);
+ // Two-line clamp keeps every card the same height.
+ display: -webkit-box;
+ -webkit-line-clamp: 2;
+ -webkit-box-orient: vertical;
+ overflow: hidden;
+ }
+
+ &__reqs {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 6px;
+
+ span {
+ padding: 2px 8px;
+ border-radius: $radius-sm;
+ border: 1px solid var(--border-color);
+ font-size: 10.5px;
+ color: var(--text-tertiary);
+
+ &.is-hard {
+ color: var(--amber);
+ border-color: color-mix(in srgb, var(--amber) 45%, transparent);
+ }
+ }
+ }
+
+ &__foot {
+ display: flex;
+ align-items: center;
+ gap: $spacing-sm;
+ margin-top: auto;
+ padding-top: 4px;
+ }
+
+ &__steps {
+ flex: 1;
+ min-width: 0;
+ font-size: 11px;
+ color: var(--text-ghost);
+ }
+}
+
+.recipe-install {
+ display: flex;
+ flex-direction: column;
+ gap: $spacing-sm;
+
+ .form-label {
+ display: block;
+ font-size: 12.5px;
+ font-weight: 600;
+ margin-bottom: 6px;
+ }
+
+ .form-hint {
+ margin: 4px 0 0;
+ font-size: 12px;
+ color: var(--text-tertiary);
+ }
+
+ .form-input {
+ width: 100%;
+ height: 36px;
+ padding: 0 10px;
+ border: 1px solid var(--border-color);
+ border-radius: $radius-md;
+ background: var(--bg-input, var(--bg-card));
+ color: var(--text-primary);
+ font-size: 13px;
+ }
+
+ &__servers {
+ overflow: hidden;
+ padding: 0;
+ }
+
+ &__server {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ width: 100%;
+ padding: 10px 12px;
+ border: none;
+ border-bottom: 1px solid var(--border-color);
+ background: transparent;
+ color: var(--text-primary);
+ cursor: pointer;
+ text-align: start;
+
+ &:last-child { border-bottom: none; }
+
+ &:hover { background: var(--bg-hover, rgba(128, 128, 128, 0.06)); }
+
+ &.is-on {
+ background: color-mix(in srgb, var(--primary-color) 8%, transparent);
+
+ svg { color: var(--primary-color); }
+ }
+ }
+
+ &__radio {
+ width: 14px;
+ height: 14px;
+ flex-shrink: 0;
+ border-radius: 50%;
+ border: 1.5px solid var(--border-color);
+
+ .is-on & {
+ border-color: var(--primary-color);
+ box-shadow: inset 0 0 0 3.5px var(--primary-color);
+ }
+ }
+
+ &__srvname {
+ flex: 1;
+ min-width: 0;
+ font-size: 13px;
+ font-weight: 550;
+ }
+
+ &__srvspec {
+ font-size: 11px;
+ color: var(--text-tertiary);
+ }
+
+ &__nosrv {
+ margin: 0;
+ padding: 12px;
+ font-size: 12.5px;
+ color: var(--text-tertiary);
+ }
+
+ &__preflight {
+ overflow: hidden;
+ padding: 0;
+ }
+
+ &__blocked {
+ margin: 8px 0 0;
+ font-size: 12px;
+ color: var(--red);
+ }
+
+ &__handoffs {
+ overflow: hidden;
+ padding: 0;
+ }
+
+ &__actions {
+ display: flex;
+ justify-content: flex-end;
+ gap: 8px;
+ padding-top: $spacing-sm;
+ }
+}
+
+.recipe-preflight {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 8px 12px;
+ border-bottom: 1px solid var(--border-color);
+ font-size: 12.5px;
+
+ &:last-child { border-bottom: none; }
+
+ &.is-ok svg { color: var(--green); }
+ &.is-bad svg { color: var(--red); }
+
+ &__k {
+ flex: 1;
+ min-width: 0;
+ }
+
+ &__need,
+ &__have {
+ font-size: 11px;
+ color: var(--text-tertiary);
+ min-width: 64px;
+ text-align: end;
+ }
+}
+
+.recipe-handoff-row {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 8px 12px;
+ border-bottom: 1px solid var(--border-color);
+ font-size: 12.5px;
+
+ &:last-child { border-bottom: none; }
+
+ svg { color: var(--amber); flex-shrink: 0; }
+
+ &__k { flex: 1; min-width: 0; }
+
+ &__url {
+ font-size: 11px;
+ color: var(--primary-color);
+ }
+}