Skip to content

plugins.mdx

Latest commit

 

History

History
112 lines (85 loc) · 7.77 KB

plugins.mdx

File metadata and controls

112 lines (85 loc) · 7.77 KB
Raw
title Plugins
description How sitectl plugins extend the core CLI with stack-specific workflows and create flows.

Plugins extend sitectl with commands and workflows specific to the technology stack your site runs on.

General Docker operations stay in the core CLI. Use sitectl compose for context-aware Docker Compose commands and sitectl port-forward for loopback-only access to internal services on local or remote contexts. Plugins add stack-specific value on top of that foundation: create definitions, application CLIs, API helpers, sync workflows, migrations, diagnostics, and other project-specific operations.

How discovery works

sitectl discovers plugins by searching your $PATH for binaries named sitectl-<plugin>. When you run a direct plugin command such as sitectl drupal drush, sitectl finds sitectl-drupal on your path and delegates the subcommand to it, passing through flags and context automatically.

This means installing a compatible plugin is as simple as putting its binary on your path. No registration file is needed. Core and plugin binaries are released separately, so keep the minimum versions described in Install and Upgrade aligned.

Command routing

Plugins expose two kinds of behavior:

  • Direct plugin commands use the plugin namespace, such as sitectl drupal drush, sitectl isle sync fcrepo, or sitectl wp cache flush.
  • Core workflow commands stay in the core namespace and dispatch to the active context's plugin over RPC. This includes sitectl create, sitectl validate, sitectl healthcheck, sitectl verify, sitectl debug, sitectl set, sitectl converge, and sitectl component describe.

Plugin pages document the canonical command path. Older namespace-shaped compatibility commands are not listed as separate docs pages.

Plugin hierarchy

Plugins can include other plugins. sitectl-isle includes sitectl-drupal because every Islandora site is also a Drupal site.

Shared, self-contained services are different. Services such as Traefik, MariaDB, Solr, Valkey, and Memcached are cross-cutting enough to live in the core sitectl command namespace. Operators still use service-oriented commands such as sitectl mariadb backup, but the command comes from core rather than an included service plugin.

The active context's plugin field determines which plugin is responsible for a given site. Commands like sitectl debug, sitectl validate, sitectl healthcheck, sitectl verify, and sitectl converge use this to route plugin-specific work automatically.

For first-class application plugins, build, init, up, down, logs, status, and rollout behavior generally stay in core sitectl compose and related core workflow commands. The plugin namespace is for app-specific operations, not thin aliases over shared lifecycle.

Core service commands

Self-contained services may still run as standalone Compose projects, but their shared command surface belongs to core sitectl. Start with the Core service commands landing page when the operation is about Traefik, MariaDB, Solr, Valkey, Memcached, or another reusable service inside a stack.

Core `sitectl mariadb` operations for backups, restores, sync, and MariaDB service helpers. Core `sitectl memcached` operations and reusable cache service helpers. Core `sitectl solr` operations and reusable Solr service helpers. Core `sitectl traefik` service inspection. Public ingress settings are owned by each app plugin's `ingress` component. Core `sitectl valkey` operations and reusable cache service helpers.

Application plugins

Drupal-oriented workflows: drush execution, user login links, database and config sync between environments. Islandora workflows from `sitectl-isle v1.0.0`: guided site creation, component and feature-bundle management, Fedora and Blazegraph sync, and migration utilities. Includes the Drupal plugin. LibOps platform workflows from the `sitectl-libops` plugin: authentication, organizations, projects, sites, access controls, domains, hosted templates, and Task Agent tasks. WordPress workflows: template creation, WP-CLI, Composer, plugin/theme maintenance, cache, and database helpers. Open Journal Systems workflows: template creation, OJS PHP tools, PKP tools, scheduled tasks, jobs, and import/export helpers. Omeka Classic workflows: template creation and REST API helpers for collection, item, file, tag, user, and metadata operations. Omeka S workflows: template creation and REST API helpers for resources, media, sites, modules, and vocabularies. ArchivesSpace workflows: template creation, API helpers, search, job inspection, diagnostics, and container script wrappers.

Assigning a plugin to a context

When you create or configure a context, you specify which plugin owns it. This is stored in the context's plugin field. Only commands from that plugin (and any plugins it includes) are valid against that context.

For example, a context with plugin: isle accepts ISLE direct commands such as sitectl isle sync fcrepo and Drupal direct commands such as sitectl drupal drush, because the Islandora plugin includes Drupal. Core workflow commands such as sitectl validate and sitectl set fcrepo off dispatch to the Islandora plugin through that same context.

Composition matrix

First-class application plugins follow these composition rules:

  • Web applications use Traefik for ingress.
  • LAMP-style applications include MariaDB by default.
  • Drupal and ArchivesSpace include Solr by default because their templates ship search enabled.
  • Shared service commands come from core sitectl, not from app plugin includes.
  • Traefik edge settings, including TLS mode, domain, trusted proxies, upload limits, and read timeout, are first-class ingress component options.
App plugin Default compose project Default services Included plugins
archivesspace ./archivesspace ArchivesSpace, Traefik, MariaDB, Solr none
drupal ./drupal Drupal, Traefik, MariaDB, Solr none
isle Chosen during create Islandora Drupal stack with MariaDB, Solr, Traefik, git-root codebase, and local Triplet; Fedora and Blazegraph are selectable and default to superseded/disabled drupal
ojs ./ojs OJS, Traefik, MariaDB none
omeka-classic ./omeka-classic Omeka Classic, Traefik, MariaDB none
omeka-s ./omeka-s Omeka S, Traefik, MariaDB none
wp ./wp WordPress, Traefik, MariaDB none

Application compose projects remain standalone repositories. App plugins own create definitions and app-specific workflows; core sitectl owns shared lifecycle, service operations, and helpers.