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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
docs(registries): write down the test for what earns a registry
Juan Denis593dd11a8b13
diff --git a/README.md b/README.mdindex d8e882f2..f530baaa 100644--- a/README.md+++ b/README.md@@ -327,6 +327,8 @@ Full history: [ROADMAP.md](ROADMAP.md)| [Extensions Registry](https://github.com/jhd3197/serverkit-extensions) | The curated extension marketplace `index.json` — separate repo || [Theming](docs/THEMING.md) | Build & share panel themes — token reference, Theme Studio, and the submit flow || [Themes Registry](https://github.com/jhd3197/serverkit-themes) | The curated community themes registry — separate repo |+| [Templates Registry](https://github.com/jhd3197/serverkit-templates) | The curated app template catalog `index.json` — separate repo |+| [Registries](docs/REGISTRIES.md) | Which catalogs are published as registries, and the test for whether a new one should be || [Agent Pairing](docs/pairing.md) | Secure short-code agent enrollment || [API Reference](docs/API.md) | REST API endpoints || [New Features](docs/NEW_FEATURES.md) | Endpoint & page reference for the latest `dev` features |diff --git a/docs/REGISTRIES.md b/docs/REGISTRIES.mdnew file mode 100644index 00000000..08163a99--- /dev/null+++ b/docs/REGISTRIES.md@@ -0,0 +1,96 @@+# Registries++ServerKit publishes some of its catalogs as standalone repositories that panels+read over the network, so entries can ship without a panel release. Three exist+today:++| Registry | Repo | Bundled in the panel? |+|---|---|---|+| Extensions | [`serverkit-extensions`](https://github.com/jhd3197/serverkit-extensions) | builtins only; the rest install on demand |+| Themes | [`serverkit-themes`](https://github.com/jhd3197/serverkit-themes) | 17 bundled, gallery adds more |+| App templates | [`serverkit-templates`](https://github.com/jhd3197/serverkit-templates) | all 106 bundled, registry adds/updates |++This document exists because "should X be a registry too?" is a question that+otherwise gets re-asked every few months. Most of the time the answer is no.++## The test++A catalog earns a registry only when **all three** hold:++1. **It changes faster than the panel releases.** If new entries naturally+ arrive with the feature work that consumes them, a registry buys nothing.+2. **It is data, not code.** A new entry must work on an *existing* panel with+ no code change. If using it requires a new service method, a new job kind, or+ a new UI surface, it is code wearing a catalog's clothes.+3. **Someone outside the release cycle would contribute.** If only the+ maintainers will ever add entries, a directory in this repo is simpler and+ reviews the same way.++Fail any one, and extraction adds a network dependency, a second release+process, and a version-skew surface in exchange for nothing.++### The failure mode to avoid++The expensive mistake is extracting a catalog that fails test 2. Panels that+have not upgraded keep reading the registry forever. Publish an entry that needs+new panel code, and every old panel either ignores it (best case) or shows a+broken item it cannot install (worst). At that point the registry needs its own+`min_panel_version` gate — which is exactly why `serverkit-extensions` has one,+and exactly the complexity you do not want unless the catalog earns it.++## Why the three qualified++- **Extensions** are independently versioned code artifacts with permissions and+ a `min_panel_version` gate. They are the archetype: third-party authored,+ released on their own cadence, installed at runtime.+- **Themes** are pure token maps — data by construction, contributed by people+ who will never open a panel PR, and worthless if shipping one requires a+ release.+- **App templates** are declarative Compose specs. New self-hosted apps appear+ constantly and each is ~2 KB of YAML that an existing panel already knows how+ to install. `TemplateService` has always resolved+ `<repo_url>/index.json` + `<repo_url>/templates/<id>.yaml`; the registry is+ just the other end of a contract the panel already had.++Note the pattern: **bundled and registry are not exclusive.** Templates and+themes ship inside the panel *and* have a registry. The bundle is the offline+floor — air-gapped installs, fresh installs with no network, and any day+GitHub is unreachable — while the registry is the growth path. Only extensions+lean on the registry as the primary source, because they are large and optional+by nature.++## What was assessed and rejected++| Catalog | Where | Verdict |+|---|---|---|+| Server templates | `ServerTemplateService.TEMPLATE_LIBRARY` | **No.** 12 entries, stable, and operators already create their own via `create_template()` into the DB. The library is a seed, not a catalog. |+| Notification events | `app/notifications/catalog.py` | **No.** Fails test 2 — an event type is only real if panel code emits it. A registry entry with no emitter is a dead row. |+| AI providers | `ai_service.CURATED_PROVIDERS` | **No.** Each entry is bound to a Prompture driver; adding one without the driver produces a provider that cannot connect. |+| DB tuning settings | `db_config_tuner_service.CURATED_SETTINGS` | **No.** Fails test 3 — tuning knobs track the engines the panel supports, and only maintainers will touch them. |+| Sanitization profiles | `models/sanitization_profile.BUILTIN_PROFILES` | **No.** Consumed by code paths that must understand each profile. |+| Agent survey probes | `app/data/survey_probe_catalog.yaml` | **No.** A probe is only meaningful if the agent implements its kind, so it is gated by the agent's release, not the panel's. |+| Build packs | `buildpack_service` | **No.** Not a catalog at all — it generates Dockerfiles and compose from a build plan. That is code. |++## Open candidate: malware signatures++**YARA rules are the one remaining catalog that passes all three tests, and they+have no update path today.**++`YaraScanService.BUILTIN_RULES` (16 curated rules, mirrored in+`yara_rules/webshells.yar`) ships inside the panel and changes only when the+panel is released. Webshell signatures are the textbook case for out-of-band+updates — a new obfuscation family is worth pushing the day it is seen, not the+next release.++This matters more than it used to. The container image now builds **without+ClamAV by default** (`ARG INSTALL_CLAMAV=false` — see the `Dockerfile`), and+ClamAV was the component with a self-updating signature feed via `freshclam`.+In a default container, YARA is the *only* malware detection, and its rules are+frozen at release time.++Operators can already drop custom `.yar` files into+`YaraScanService.CUSTOM_RULES_DIR` (`/var/serverkit/security/yara-custom`, real+`yara` CLI required), so the local extension point exists. What is missing is a+curated upstream feed that updates itself.++Not built. Noted here so the decision is deliberate rather than forgotten.