Managing Plugins

Plugin management is an admin-only feature. Access it via Admin → Plugins in the top navigation.

Installing a Plugin

  1. Open Admin → Plugins.
  2. Click Upload Plugin.
  3. Select the plugin ZIP file from your computer.
  4. The app validates the ZIP:
    • plugin.json must be present at the root.
    • All required fields (id, name, version) must be present.
    • The id must match the ZIP filename prefix.
    • If min_app_version is set, the running Polyphony version must meet or exceed it.
    • All DB table names in the backend must be prefixed plugin_{id}_.
  5. If validation passes, the app extracts files, runs DB migrations, mounts the backend router, and registers the frontend routes.

The plugin is active immediately after a successful install. Its menu items appear in the navigation for all users with the specified roles.

If the install fails, no files are written and no migrations are run.

Plugin List

The plugin list shows all installed plugins with:

ColumnDescription
NameDisplay name from plugin.json
IDUnique slug (e.g. my-forum)
VersionSemver version string
StatusActive or Deactivated
ActionsConfigure, Deactivate / Reactivate, Uninstall

Configuring a Plugin

Plugins that declare a config_schema in their manifest expose a settings form in the admin panel.

  1. Click Configure next to the plugin.
  2. Edit the values in the generated form.
  3. Click Save. Settings take effect immediately — no restart required.

Settings are stored in the core database and are not affected by deactivating or reactivating a plugin.

Deactivating a Plugin

Deactivating a plugin unloads its backend router and hides its menu items. All data in the plugin's database tables is preserved.

  1. Click Deactivate next to the plugin.
  2. The plugin status changes to Deactivated.

Deactivation is reversible. Click Reactivate to re-mount the router and restore menu items. No migrations are run on reactivation (the schema is unchanged).

Use deactivation when you need to temporarily disable a plugin without losing its data.

Uninstalling a Plugin

Warning: Uninstalling a plugin permanently deletes all data in its database tables. This action cannot be undone.

  1. Click Uninstall next to the plugin.
  2. Confirm the action in the dialog that appears.
  3. The app drops all tables prefixed plugin_{id}_, deletes the plugin source folder, and removes the plugin record from the database.

After uninstall, the plugin no longer appears in the list. To use it again you must re-install from the ZIP and all previously stored data will be gone.

Troubleshooting

Install fails with "table name must be prefixed"

The plugin's SQLAlchemy models define a table whose name does not start with plugin_{id}_. Contact the plugin author to fix the model definition.

Install fails with "app version too old"

The plugin requires a newer version of Polyphony than the one currently running. Upgrade Polyphony or ask the plugin author for a version compatible with your installation.

Plugin installed but menu items do not appear

Check that the roles listed in menu_items match the role of the logged-in user (annotator, researcher, or admin). Also verify the plugin status is Active, not Deactivated.

Backend endpoints return 500

Check the application logs. Plugin errors are caught and returned as HTTP 500 without crashing the app, so a detailed traceback will appear in the server log.

Frontend routes show a blank error boundary

The plugin's JS bundle failed to load or threw an exception during render. Open the browser console for details. Each plugin's route tree is isolated in a React ErrorBoundary, so other parts of the application are unaffected.