Extensions
An extension is an optional feature installed as its own package. It brings its own pages, API routes and permissions. Installing the package is not enough: a platform admin switches the extension on in Settings → Extensions. The switch applies to every organization at once and needs no restart.
Plugins are different: a plugin adds a type to something the platform already has (a secret backend, an inventory provider) and works as soon as it is installed. See Installed Plugins.
The API ships with one extension, off by default:
| Extension | What it adds |
|---|---|
Container registry (registry) | The platform registry: container steps keep copies of the images they pull and push the images they build, and Artifacts → Container Images browses, deletes, imports and downloads them. Needs the registry compose overlay and HEGEMONY_REGISTRY_TOKEN_KEY. |
Settings → Extensions
The page lists every extension installed in the API environment:
- Name, id and version, with the package it came from.
- State: Enabled, Disabled, or Refused.
- Who last switched it, and when.
Platform operators and platform admins can open the page (the plugin:view permission). Only platform admins can switch an extension (extension:manage); for everyone else the buttons are locked.
Enabling
Enable runs the extension's own setup first (it may create a key or a bucket, say). If the setup fails, the page shows the error and the extension stays disabled. Once enabled, its menu entries appear in the sidebar for everyone whose role allows them.
With several API replicas, every replica follows the switch, background work included: at once on PostgreSQL, otherwise within HEGEMONY_EXTENSION_RECONCILE_SECONDS (default 10). No restart is needed.
Enabling at deployment
HEGEMONY_EXTENSIONS_ENABLE names extensions, by id and comma-separated (registry), to switch on when the API starts. It is for a deployment that wants an extension on from its first start, without an admin clicking Enable:
- Only an extension that was never switched is switched on. Once a platform admin, or an earlier start, has switched it, that switch wins: an extension an admin disabled stays disabled across restarts.
- It runs the same setup as Enable. If the setup fails, the extension stays disabled, the API log says why, and the next start tries again.
- The page and the audit log show it as switched by
HEGEMONY_EXTENSIONS_ENABLE(actorsystem:extensions-enable). - An id that is not installed, or an extension that is refused, is named in the API log and skipped; the API still starts.
The registry compose overlay sets it to registry unless you set it yourself (see Container registries).
Disabling
Disable asks for confirmation. The extension's pages leave the menu and its API answers 404 (Not Found) for everyone, in every organization, until it is enabled again. What the extension stored stays, unless its own clean-up removes it.
Refused extensions
The platform refuses an extension that does not fit: one written for another version of the extension interface, one whose permissions or routes clash with the platform's or another extension's, or one whose package fails to load. A refused extension is not loaded at all. The page shows why, and it has no switch until its package is fixed and the API restarted.
An extension can also be refused because its database tables are not upgraded yet ("its tables are at revision …, not its newest …"). This happens after installing or upgrading an extension's package without running the migrate command. Run it (task db:migrate, or docker compose run --rm migrate), then restart the API. The migrate command upgrades the platform's tables and every installed extension's.
Extension pages
An enabled extension's pages open from the sidebar. An entry can join an existing group (Artifacts, Inventory, …) or a group of its own above Settings. The pages live under /x/<extension>/<page> and look like the platform's own:
- a table of items, where a row can open a detail page and carry buttons. A long digest in a table (
sha256:…) shows by its start and end: hover over it to see it whole, or use the copy button next to it; - a detail view of one item, with buttons that act on it;
- a form that sends what you enter, or uploads a file you choose, with a progress bar.
Some buttons download a file (an archive, an export). A page that follows something in progress, such as a list of uploads, refreshes on its own while it is open. A button that does not apply to a row (a download for a job that has not finished, say) is not shown on that row. A form's button likewise shows only once what it needs is filled in or allowed.
Each page and button follows your permissions, like the rest of the web app: a menu entry is hidden when you may not open its page, and a button you may not use is locked, with the reason in its tooltip. A row opens its detail page only when you may open that page. Buttons that delete always ask first: the platform refuses an extension whose delete button would not.
A link to a page of an extension that is not enabled shows "Page not available".
For developers
How to write an extension, and what the platform checks before it accepts one: Extension Development.