Skip to main content
An ISLE feature bundle is a component that coordinates every tracked part of one application feature. It is different from a service-topology component: adding a container alone would leave Drupal unaware of the capability. The first bundles are mergepdf and hocr-search. Feature-bundle changes are local-checkout operations. Run them in the downstream site repository, review the resulting diff, commit it, and promote it through the site’s normal deployment process. See Components for the shared component workflow and status meanings.

​
Commands and create options

Enable or disable a bundle in an existing checkout:
MergePDF uses the explicit image reference tracked in Compose. Update that dependency through sitectl bump and review the literal image change with the rest of the site. --hocr-term-id must be the positive Drupal taxonomy term ID whose external URI is https://discoverygarden.ca/use#hocr; the template default is 56, but a downstream site’s term ID can differ. The same choices can be made non-interactively during create:
Both feature bundles are enabled in the v1 ISLE defaults. Pass disabled for either component when creating a site that should omit it. The recreate command emitted by sitectl retains the selected states and enabled-only option values. Inspect the current files before or after a change:

​
Compatibility checks

Sitectl validates the complete target state before writing feature-bundle files.

​
mergepdf

The project must have:
  • a top-level x-common mapping carrying the &common YAML anchor;
  • top-level secret declarations named CERT_PUBLIC_KEY, CERT_AUTHORITY, JWT_ADMIN_TOKEN, and JWT_PUBLIC_KEY; and
  • an alpaca service with an image.
The tracked MergePDF and Alpaca image references must be from compatible release lines. Review them together when a dependency bump changes either image. A downstream image can carry the required support independently, but the downstream owner is responsible for certifying that compatibility. The bundle consumes the existing common anchor and secret declarations. It does not create them or change the Alpaca service. The project must have a solr service using one of these supported image contracts:
  • islandora/solr:4.2.1 or newer;
  • libops/solr; or
  • ghcr.io/libops/solr.
Sitectl rejects an unknown Solr repository rather than assuming its schema supports hOCR. It also requires valid composer.json and Drupal config-sync inputs, and the selected hOCR term ID must be a positive integer.

​
File ownership

The ownership boundary determines what a later set or converge can repair or replace. Whole-file and whole-service assets are canonical: downstream edits inside them can be overwritten. Narrow mutations preserve unrelated keys and neighboring sequence entries.

​
mergepdf ownership

On initial enable, the bundle creates the complete services.mergepdf block in docker-compose.yml, including the direct default image islandora/mergepdf:6.3.19, common service settings, and required certificate and JWT secrets. After that, the image reference is dependency-managed: sitectl bump can replace it with another compatible, explicit islandora/mergepdf reference, and component inspection or convergence preserves that reviewed update. The bundle continues to own the remaining service shape. It also owns the complete Drupal config-sync file system.action.paged_content_created_aggregated_pdf.yml. The top-level common mapping, secret declarations, Alpaca service, secret values, and existing generated PDFs remain downstream-owned. This bundle does not change Composer requirements.

​
hOCR-search ownership

The bundle owns these complete Drupal config-sync files:
  • search_api_solr.solr_field_type.islandora_hocr_und_7_0_0.yml
  • search_api_solr.solr_request_handler.request_handler_select_islandora_hocr_7_0_0.yml
  • system.action.get_hocr_from_image.yml
  • views.view.search_in_hocr.yml
It owns only the following units in existing Drupal configuration: On disable, the bundle restores the starter template’s IIIF tile-field selections instead of deleting those pre-existing fields. It refuses to replace an unexpected downstream tile-field value with that baseline. In composer.json, the bundle owns only these top-level require entries:
The bundle validates the Solr service image but does not rewrite the Solr service. All other Compose, Drupal, and Composer fields remain downstream-owned.

​
Idempotency and drift

Running the same sitectl set command again is idempotent after the checkout matches the selected disposition. Sitectl preflights the target inputs before changing any bundle files, so a missing prerequisite or incompatible image fails before a partial feature transition begins. For an enabled MergePDF bundle, rerunning set or converge preserves a compatible direct islandora/mergepdf image reference installed by a reviewed dependency bump. sitectl component describe derives state from the current checkout. A component is drifted when only part of its selected contract remains or a canonical owned asset was edited. Use verbose describe output to inspect the failed checks, then rerun the appropriate set command or use sitectl converge --component <name> to repair the owned state.
Repairing drift can replace a whole-owned service or config file. If a downstream fork intentionally changed one of those assets, either move the customization outside the owned boundary or stop reconciling that component before accepting a repair.

​
Enable rollout

1

Prepare the downstream change

Work on a branch in a clean local checkout. Back up the database and application files, confirm the active sitectl context, and run verbose component inspection. For hOCR, verify the taxonomy term ID for https://discoverygarden.ca/use#hocr before selecting it.
2

Apply and review

Run the appropriate sitectl set ... enabled command. Review every changed tracked file. The site owner, not sitectl, decides whether the generated diff is suitable for that fork.
3

Resolve Composer dependencies

For hOCR, enable dev mode and update the two owned packages:
Commit the resulting composer.lock. Sitectl changes composer.json; it does not fabricate or update the lock file. Mergepdf has no Composer step.
4

Deploy and import configuration

Run sitectl deploy from the reviewed manifest and lock file, then import the changed Drupal configuration with sitectl drupal drush cim -y. Sitectl edits config-sync source; deploy does not import configuration into the live Drupal database.
5

Backfill existing content

For mergepdf, backfill aggregated PDFs for existing paged content when required. For hOCR, run sitectl drupal solr-config refresh --reindex to refresh the runtime configuration, then generate hOCR derivatives for existing images so the new field and search views can contain existing content. Reindex again through the Search API administration page or the site’s established Drush indexing workflow after the derivative backfill. Derivative backfills remain site-specific and are not run automatically.
6

Verify and promote

Run sitectl validate and the site’s application smoke tests. Commit the source, lock, and config changes together before promoting them to another environment.

​
Disable rollout

Run sitectl set mergepdf disabled or sitectl set hocr-search disabled on a reviewed branch, then repeat the build, deploy, and Drupal config-import workflow. When disabling hOCR, update and commit composer.lock after sitectl removes the two owned requirements from composer.json. Disabling a bundle removes its owned service, files, fields, and requirements; it does not erase produced data. Existing aggregated PDFs remain after disabling mergepdf. Existing hOCR derivatives and Solr data remain after disabling hOCR, so clear or reindex stale hOCR search data according to the site’s retention policy. Use the site’s tested module-uninstall and config-import order when removing hOCR from a running installation.

​
Downstream fork boundary

The template and plugin provide a repeatable source transition, not a controller for the live site. The downstream repository owns its Git history, composer.lock, deployment approval, database/config import, backfill, reindex, and data-retention decisions. Sitectl owns only the fields listed above while an operator chooses to use the component. Do not treat .libops/template.lock.yaml as component desired state. .libops/site.yaml owns component selections; the template lock records template provenance. Do not expect a future plugin release to merge arbitrary downstream customizations. Keep changes outside the documented ownership units, review component diffs like application migrations, and commit the result in the fork. Developers adding another cross-domain bundle should follow the component ownership contract.