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.

Status: pending. The install/enable flow (steps 3 & 5) is not built yet. This page documents the intended operator experience so it's ready when the code lands; it will be marked implemented as each piece ships.

The model: install ≠ enable

  • Install — makes a plugin available. Two routes:
    • In-app (pending, step 5): owner enters a package name + version in System Admin → Plugins; the plugin-host pip-installs it onto a persistent volume and restarts itself. The core app keeps serving throughout.
    • Host-side: bake it into your image with a thin Dockerfile — 
      FROM ghcr.io/freeperro/gdx_dispatch:1.0.0
RUN pip install gdx-plugin-foo gdx-plugin-bar
  • Enable — turns an installed plugin on, per the usual module system. A single owner-only toggle; no restart.

You vet what you install. There is 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 any dependency.

Updating plugins

Plugins are versioned pip packages. Updating is the same as installing a newer version (in-app: change the version and let plugin-host reconcile; host-side: bump the version in your Dockerfile and rebuild). Core-app updates are separate — see the project README's Updating section.

Reference

  • Architecture & rationale: ADR-013

Clone this wiki locally