Plugins

Docleus uses plugins for most product features. The core provides the kernel, storage, content log, authorization, rendering, jobs, HTTP, installation, and site services. Editors, block types, themes, search, collaboration, change requests, OIDC, S3 storage, Mermaid, and llms.txt are plugins.

Default bundle

OIDC and S3 are installed but disabled until configured.

Enablement levels

Plugins are installed once for the instance. They are then enabled for organizations and optionally overridden for spaces.

• Instance: administrators install, uninstall, and inspect plugins under Instance settings > Installed plugins.
• Organization: organization admins choose which installed plugins the organization uses under Settings > Plugins. Organizations created through the editor start with every installed plugin enabled.
• Space: space admins can inherit the organization setting or explicitly turn a plugin on or off under Space settings > Plugins.

Enablement filters the events and UI a plugin receives. It is not a security sandbox.

Install a plugin

An instance administrator can install a plugin from:

• An uploaded npm pack tarball (.tgz).
• A path available inside the server container.
• A Git URL and ref.

Git installs are cloned shallowly. If the package does not contain a build, Docleus installs dependencies with pnpm install --frozen-lockfile and runs pnpm build. Uploaded tarballs must be self-contained and include every entry named by docleus.plugin.json.

Runtime installation does not require restarting the container. Installed files are stored under /data/plugins, and the deployment configuration records their version, source, and checksum so they load again after restart.

A plugin whose engines.docleus range does not include the platform version is rejected at install time and blocks boot if a later platform upgrade makes it incompatible.

Plugin trust

Plugins run in the Docleus process with full instance access. They are not isolated from the database, file system, other organizations, or other plugins. There is no capability sandbox or safe mode.

Install only plugins from sources you trust and pin a version or commit. Before installing a third-party plugin:

• Review its source and build output.
• Confirm its license is acceptable for your deployment.
• Check its engines.docleus compatibility range.
• Install it in a test instance before production.

To recover from a faulty plugin, remove its row from /data/docleus.yaml and restart the container. If the plugin prevents boot, this can be done before the next start.

Disable or uninstall

Turning a plugin off for an organization or space preserves its stored content. Blocks whose type is no longer available appear as read-only placeholders and are saved unchanged.

Uninstalling a plugin is instance-wide and removes its installation and settings. Content that depends on its block types remains stored, but editing and rendering those blocks require the plugin to be installed and enabled again.

Plugin development

Plugins use the public @docleus/sdk. First-party features use the same plugin extension points available to third parties. The SDK is experimental before 1.0, so pin compatible versions and test plugins against each Docleus upgrade.

The plugin template is a separate repository in the Docleus organization. Use the workspace compatibility check before upgrading a plugin bundle.