> ## Documentation Index
> Fetch the complete documentation index at: https://sitectl.libops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Islandora plugin

> Islandora sitectl workflows including guided site creation, component management, Fedora and Blazegraph sync, and migration utilities.

export const Compose = () => <Tooltip headline="Compose" tip={<>
        Docker Compose is Docker's tool for defining and running multi-container applications.{" "}
        <a href="https://docs.docker.com/compose/">https://docs.docker.com/compose/</a>.
      </>}>
    <>
      <Icon icon="docker" />
      {" "}
      Compose
    </>
  </Tooltip>;

The Islandora plugin adds Islandora-specific behavior on top of the core sitectl workflow. The plugin binary is `sitectl-isle`. Direct plugin commands live under `sitectl isle` for ISLE-only operations such as cache warming, migration helpers, and fcrepo sync. Create, validate, healthcheck, verify, debug, set, converge, and component inspection are core sitectl commands that dispatch to the Islandora plugin through the active context.

Because every Islandora site is also a Drupal-backed stack, the Islandora plugin includes the Drupal plugin. Shared service commands for MariaDB, Solr, and Traefik come from core `sitectl` and work against Islandora contexts automatically.

## Create

Start a new Islandora site from the [LibOps ISLE template](https://github.com/libops/isle):

```bash theme={null}
sitectl create isle
```

The create flow:

<Steps>
  <Step title="Clone the template">
    `sitectl-isle v1.0.1` clones `libops/isle` from its reviewed `v1.0.0` template ref into your chosen directory. Pass `--template-repo` and `--template-branch` to use a different reviewed source. The template has since published `v1.1.0`; selecting that newer ref is an explicit downstream update until a later plugin release advances its default.
  </Step>

  <Step title="Configure a context">
    sitectl creates a local sitectl context for the new project directory.
  </Step>

  <Step title="Answer component questions">
    sitectl asks about each application component that requires a decision at create time, including fcrepo, Blazegraph, and IIIF. Cross-domain feature bundles can be selected with create flags. You can answer interactively or pre-supply answers with flags.
  </Step>

  <Step title="Apply component state">
    sitectl writes the <Compose /> file and Drupal config changes that reflect your component choices, so the first `docker compose up` starts the stack you asked for.
  </Step>
</Steps>

After create completes, review the generated changes and add your own Git remote before committing the checkout.

The LibOps template defaults to a git-root Drupal codebase, Fedora superseded by Drupal private files, Blazegraph disabled, Triplet running locally, and the mergepdf and hOCR-search feature bundles enabled. Interactive create prompts let you opt into Fedora or Blazegraph and choose another IIIF implementation; create flags can override either feature-bundle default.

## Component status

See which components are registered and how the project is currently configured:

```bash theme={null}
sitectl component describe
sitectl component describe --path /path/to/project
```

`sitectl component describe` is a core command that dispatches to the Islandora plugin based on the active context. See [Components](/components) for a full explanation of what each status value means.

## Managed components

The Islandora plugin currently manages these application components directly:

| Component                                                                          | What it controls                                                                                                                                                  | Common commands                                                                               |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [`fcrepo`](/plugins/isle/fcrepo)                                                   | Fedora Commons service, volume, Drupal Fedora config, and filesystem migration guidance.                                                                          | `sitectl set fcrepo enabled` or `sitectl set fcrepo superseded --isle-file-system-uri public` |
| [`blazegraph`](/plugins/isle/blazegraph)                                           | Blazegraph service, triplestore volume, Alpaca triplestore indexing, and Drupal triplestore actions.                                                              | `sitectl set blazegraph enabled` or `sitectl set blazegraph disabled`                         |
| [`iiif`](/plugins/isle/iiif)                                                       | The IIIF image server implementation: Cantaloupe or Triplet.                                                                                                      | `sitectl set iiif cantaloupe` or `sitectl set iiif triplet`                                   |
| [`iiif-topology`](/plugins/isle/iiif)                                              | Whether IIIF runs in this Compose project or behind an external upstream.                                                                                         | `sitectl set iiif-topology distributed --iiif-upstream-url https://iiif.example.edu`          |
| `codebase`                                                                         | Whether the Composer-owned Drupal application uses the default repository-root layout or an intentional nested layout.                                            | `sitectl set codebase git-root` or `sitectl set codebase nested`                              |
| `ingress`                                                                          | Traefik mode, domain, TLS certificate strategy, Drupal URL/HTTPS settings, trusted proxy IPs, and upload/read timeout settings.                                   | `sitectl set ingress enabled --mode https --domain islandora.example.org`                     |
| `dev-mode`                                                                         | Local `docker-compose.override.yml` bind mounts, UID propagation, ISLE development routers, and optional `cli-sandbox` assistant wiring for editable Drupal code. | `sitectl set dev-mode --assistant --harness codex` or `sitectl set dev-mode disabled`         |
| [`mergepdf`, `hocr-search`](/plugins/isle/feature-bundles)                         | Complete application features across Compose, Drupal config, and Composer where needed.                                                                           | `sitectl set mergepdf enabled` or `sitectl set hocr-search enabled --hocr-term-id 56`         |
| [`fits`, `crayfits`, `homarus`, `houdini`, `hypercube`](/plugins/isle/derivatives) | Whether each derivative microservice runs in this Compose project or uses the managed LibOps endpoint.                                                            | `sitectl set homarus distributed` or `sitectl set homarus enabled`                            |

Review component changes through version control before promoting them. Some file mutations can run against remote contexts for QA or recovery, but the normal path is still to run them against the checkout you intend to commit.

If a checkout has a dev-mode override generated by an older plugin release, rerun `sitectl set dev-mode enabled` (including any assistant flags you use). This regenerates Traefik development wiring with file-provider routes and removes the obsolete Docker-provider flags.

## Updating ISLE

ISLE records each container image directly in Compose as a reviewed reference and
retains an immutable digest where one is tracked. A shared environment tag is not
an update interface. This also applies to Traefik: let `sitectl bump` propose its
tracked Compose update with the other images instead of editing a separate runtime
override.

Use this operator sequence:

1. In a development checkout, run `sitectl bump` with the intended update level and
   `--dry-run`, then run the reviewed bump without `--dry-run`. Read every
   intervening release note when crossing a major version.
2. If Drupal dependencies need a targeted authoring change, enable dev mode and use
   `sitectl drupal composer`; commit both Composer manifests. If Search API Solr
   changed, refresh and review the tracked Solr configuration in development.
3. Test the branch, including any component migration named by the release notes.
   Before production rollout, back up MariaDB, Drupal public/private files, and any
   enabled Fedora or Blazegraph state, and test the restore path.
4. Merge the reviewed source changes and run `sitectl deploy`. It pulls images and
   rebuilds the Islandora/Drupal image while the current stack is online, then runs
   the ordered down/up rollout. The Drupal gate waits for installation and runs
   `drush updb -y` and `drush cr`; either failure stops the deploy before the final
   bounded full-stack start.
5. Run `sitectl mariadb upgrade` after a MariaDB image change. Import reviewed
   Drupal config-sync changes explicitly with `sitectl drupal drush cim -y`.
6. After configuration import, refresh the Drupal Solr config with `--reindex` when
   Solr, Search API Solr, or search-related Drupal configuration changed. The refresh
   is a no-op when generated, tracked, and runtime configuration already match.
   Finish with `sitectl healthcheck`, `sitectl verify`, and site-specific smoke tests
   before discarding backups.

Deploy runs database updates and cache rebuilds, but it does not import Drupal
configuration or reindex Solr. Keep those as explicit, observable gates. Complete
component-specific migration guidance before removing a repository or triplestore
service.

## Shared services and ingress

Islandora contexts use core service commands for shared infrastructure such as MariaDB, Solr, and Traefik status. Use the `ingress` component for TLS mode, domain, Cloudflare Origin CA, Let's Encrypt, custom certificates, mkcert development certificates, trusted proxies, and upload/read timeout settings. The Islandora plugin supplies Drupal-specific route and override wiring where the stack needs it.

## Component set

Turn a component on or off:

```bash theme={null}
sitectl set fcrepo off
sitectl set blazegraph on --yolo
sitectl set iiif triplet
sitectl set iiif-topology distributed --iiif-upstream-url https://iiif.example.edu
sitectl set fits distributed
sitectl set crayfits distributed
sitectl set homarus distributed
sitectl set houdini distributed
sitectl set hypercube distributed
sitectl set mergepdf enabled
sitectl set hocr-search enabled --hocr-term-id 56
```

sitectl updates the relevant <Compose /> files and Drupal config sync files, then prompts for confirmation. Pass `--yolo` to skip confirmation in automation.

Use `enabled` to move a distributed derivative service back into the base Compose stack, for example `sitectl set homarus enabled`.

See [derivative microservices](/plugins/isle/derivatives) for the managed endpoint list and [feature bundles](/plugins/isle/feature-bundles) for cross-domain ownership and rollout guidance.

## Sync

Copy the fcrepo database from one context to another:

```bash theme={null}
sitectl isle sync fcrepo --source museum-prod --target museum-local
```

This backs up fcrepo on the source, stages the artifact, and imports it into the target.

## Validate

Check that the active context's project configuration is valid:

```bash theme={null}
sitectl validate
```

## Verify

After the site is online or after a site update, run verification checks for the
Islandora stack. These checks are meant for CI and update validation: basic
runtime status plus Islandora-specific functionality that should keep working.

```bash theme={null}
sitectl verify
sitectl verify --fcrepo off --iiif triplet --bot-mitigation on
```

Use `--demo-objects` only against disposable CI, preview, development, or staging
sites because it creates demo content before checking that repository storage
grew.

## Drupal commands

Because the Islandora plugin includes the Drupal plugin, all `sitectl drupal` commands work against Islandora contexts:

```bash theme={null}
sitectl drupal composer install
sitectl drupal drush cr
sitectl drupal solr-config refresh --reindex
sitectl drupal sync database --source museum-prod --target museum-local
sitectl drupal login
```