Phase: N (End-User Documentation) Step: N.14 Since: 0.18.0
TL;DR
The plugin catalog is a hub-hosted, browsable list of curated plugins — each signature-verified against the Phlix hub's published keys. Browse to Settings → Plugins → Browse Catalog, pick a plugin, click Install, and the verified plugin lands in one click. Catalog plugins carry SHA256 signatures and are moderated by the hub team, so you don't need to manage your own trusted-key allowlist for community plugins.
1. What Is the Plugin Catalog
The catalog is a JSON endpoint served by the Phlix hub (https://catalog.phlix.media/v1/plugins or similar), listing every community plugin that has passed hub moderation and carries a valid signature from a registered author. Operators can browse by plugin type, search by name, and install in one click. The catalog replaces manual URL pasting for operators who prefer curated plugins.
Plugin types available in the catalog: metadata-provider, auth-provider, notifier, scrobbler, tuner, transcoder-hook, ui-theme, library-type, subtitle-provider, arr-integration, analytics-sink.
2. Browse and Install from the Web UI
- Browse to Settings → Plugins (or
/admin/plugins). - Click Browse Catalog (or navigate directly to
/admin/plugins/catalog). - Use the type filter dropdown to narrow by category (
metadata-provider,auth-provider,notifier,scrobbler,tuner,transcoder-hook,ui-theme, etc.). - Click a plugin card to expand its detail panel: description, author, version,
phlix_min_server_version, signature status. - Click Install on the chosen plugin.
- The plugin is downloaded, signature-verified, and staged automatically.
- It lands disabled in the plugins table — flip the toggle to enable.
Screenshot placeholder: [screenshot: plugin catalog browse view with type filter and install button]
3. Enabling and Configuring
After install:
- Enable: flip the toggle in Settings → Plugins table.
- Configure: click the wrench icon to open the plugin's settings form. Settings vary by plugin type:
| Plugin Type | Typical Config Fields |
|---|---|
metadata-provider | API key, endpoint URL |
auth-provider | Provider URL, client ID/secret, scopes |
notifier | Webhook URL, channel/room, auth token |
scrobbler | Service credentials |
tuner | Device ID, lineup URL |
transcoder-hook | Priority, encoding profile |
ui-theme | No required config — applies immediately on enable |
Settings are persisted in the plugins.settings_json column. Each plugin exposes its own fields as declared in its plugin.json settings block.
4. Updating Catalog Plugins
When a catalog plugin ships a new version:
- A badge appears on the plugin card in the catalog view.
- The Update button triggers
installagain; the loader replaces on-disk files and retainsenabledstate andsettings_json. - After update, the plugin auto-re-attaches on the next server restart (or immediately if it does not require restart — see Failure 3 below).
5. Removing a Catalog Plugin
Same as URL-installed plugins: Settings → Plugins → toggle Disable → click Uninstall. This removes the on-disk files and the database row. Catalog browsing state is preserved (the plugin remains browsable in the catalog; you can reinstall).
6. What Can Go Wrong
Failure 1: Version Incompatibility
Symptom: "This plugin requires phlix-server ≥ 1.2.0; you are running 1.1.4" shown in the catalog detail panel.
Cause: Running server is older than the plugin's phlix_min_server_version.
Fix: Upgrade phlix-server before installing. The catalog shows compatibility info before you install — pay attention to the version badge.
Failure 2: Signature Verification Failure
Symptom: Install fails with "Signature verification failed."
Cause: Plugin tarball was corrupted during download, or hub moderation was bypassed.
Fix: Report to hub moderation at github.com/detain/phlix-plugin-catalog. Do not bypass the signature check manually.
Failure 3: Plugin Requires Restart
Symptom: Plugin is enabled but its hooks do not fire (e.g., transcoder-hook never intercepts a transcode).
Cause: Plugin registers event listeners only at container boot, not on enable.
Fix: Restart phlix-server:
systemctl restart phlix
# or
php bin/phlix restartThe plugin auto-re-attaches on boot for enabled plugins.
Failure 4: ui-theme CSS Breaks Web Portal
Symptom: Web portal blank or partially styled after enabling a ui-theme.
Cause: Theme uses CSS selectors that conflict with the current portal DOM structure.
Fix: Disable immediately via CLI:
curl -sS -X POST https://phlix.example.com/api/v1/admin/plugins/<name>/disable \
-H "Authorization: Bearer $TOKEN"Then contact the plugin author with your Phlix server version and portal DOM details.
7. Next Steps
- Install from URL — for plugins not yet in the catalog, or for testing unreleased versions
- Trusted plugin list — how the hub's signature allowlist works and how to request plugin listing
- Plugin developer guide — for plugin authors; learn how to publish a plugin to the catalog
- Plugin catalog source — file an issue or PR to add or update a community plugin listing