Skip to content

Using Plugins

Jump to bottom
Doug edited this page Jun 24, 2026 · 5 revisions

Using Plugins

For operators running a self-hosted GDX instance. How to install, enable, and update third-party modules.

The model: install ≠ enable

  • Install makes a plugin available (its code is present on the box).
  • Enable turns an installed plugin on for the tenant.

You vet what you install — there's no central registry or signing. A plugin runs with backend access, confined to the plugin-host container (not the core app). Treat installing one like adding a dependency.

Installing

Two routes:

A) In-app (owner-only)

Register the package, then restart the plugin-host to apply:

# record intent (owner JWT)
curl -X POST https://your-host/api/admin/plugins \
  -H "Authorization: Bearer $OWNER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"package": "gdx-plugin-foo", "version": "0.1.0"}'

# apply: restart plugin-host — it pip-installs registered packages into the
# /plugins volume and discovers them. The core app keeps serving throughout.
docker compose -p gdx restart plugin-host

GET /api/admin/plugins lists the registry; DELETE /api/admin/plugins/<package> removes an entry.

Auto-restart-on-install (so you don't run the restart by hand) is future work — see the Home page's "known gaps".

B) Host-side (bake into the image)

FROM ghcr.io/freeperro/gdx_dispatch:1.0.0
RUN pip install gdx-plugin-foo gdx-plugin-bar

Enabling

Enabling is a per-tenant module grant (owner-only). An installed-but-not-enabled plugin returns 403 until granted. Until the Settings toggle ships, grant via the module-grants mechanism (a company_module_grants row keyed by the plugin's key).

Updating

Plugins are versioned pip packages — update by registering a newer version (in-app) or bumping the version in your Dockerfile (host-side), then restarting plugin-host. Core-app updates are separate; see the project README's Updating section.

Operational notes

  • The /plugins volume must be writable by the plugin-host runtime user, or the in-app pip install fails with a permission error.
  • A plugin crash/leak is contained to plugin-host; the core app is unaffected.

Reference

Clone this wiki locally