LibOps ISLE Template

The LibOps ISLE Template is a fork of ISLE Site Template that's been customized using sitectl-isle components. It includes Drupal, Traefik, MariaDB, Solr, ActiveMQ, Alpaca, and LibOps derivative services.

Docs:

• Managed application architecture
• ISLE sitectl plugin

Requirements

• sitectl installed on the host that will run the site.
• sitectl-isle installed for ISLE create, validation, healthcheck, and helper commands.
• sitectl-drupal installed because ISLE includes the Drupal plugin surface.
• Docker with the Compose v2 plugin installed on the same host.

Quick start

Create a new ISLE site from this template:

sitectl create isle/default \
  --template-repo https://github.com/libops/isle \
  --path ./my-isle-site \
  --type local \
  --checkout-source template \
  --default-context

The site is served through Traefik at http://localhost by default.

Local image build

The drupal service builds this checkout on top of the LibOps Islandora base image. The Dockerfile copies Composer lockfiles and assets before local recipes, modules, themes, config, and rootfs additions so Docker can reuse dependency layers when only site customizations change. During sitectl create, initialization prepares secrets, certificates, ownership, and rootfs permissions; the normal create build phase then builds the image once. Local builds use the platform selected by the Docker CLI and do not push images.

Docker Compose derives the project name from the checkout directory, so independent forks do not share containers, networks, or named volumes by default. Set COMPOSE_PROJECT_NAME explicitly when a stable name is required. If an existing checkout previously relied on this template's fixed isle-site-template project name, set COMPOSE_PROJECT_NAME=isle-site-template before starting it to keep using its existing named volumes, or migrate those volumes deliberately.

Basic Operations

Run these from the generated checkout, or add --context <name> when operating from elsewhere.

Start or update the stack with sitectl compose:

sitectl compose up --remove-orphans -d

Check the site and context configuration with sitectl healthcheck and sitectl validate:

sitectl healthcheck
sitectl validate

Update the application base tag or pin that base by digest with sitectl image:

sitectl image set --tag drupal=nginx-1.30.3-php84 --tag solr=9 --tag alpaca=2.4
sitectl image set --build-arg drupal.BASE_IMAGE=libops/islandora:nginx-1.30.3-php84@sha256:...

Enable local development bind mounts with sitectl set:

sitectl set dev-mode enabled

Publish a domain, switch HTTP/TLS mode, configure Let's Encrypt, trust upstream proxies, or tune upload limits with the ingress component:

sitectl set ingress enabled --mode https-custom --domain islandora.localhost
sitectl set ingress enabled --mode https-letsencrypt --domain islandora.example.org --acme-email [email protected]
sitectl set ingress enabled --trusted-ip 203.0.113.10/32 --max-upload-size 2G --upload-timeout 10m

sitectl set applies the requested component change immediately. Use sitectl converge when you want an interactive review of the complete component state.

MergePDF and hOCR Search are feature bundles: each component owns its Compose, Drupal configuration, and Composer requirements as one reviewable change. Both are enabled and reconciled during sitectl create. Existing installations can adopt or repair them explicitly:

sitectl set mergepdf enabled --islandora-tag 6.3.19
sitectl set hocr-search enabled

The MergePDF bundle writes ISLANDORA_TAG to the selected Compose environment file and requires islandora/alpaca:6.3.19 or newer when the upstream Alpaca image is selected. The LibOps Alpaca image remains a supported compatible implementation. hOCR Search requires islandora/solr:4.2.1 or a compatible LibOps Solr image.

The ingress component writes INGRESS_HOSTNAMES as comma-separated hostnames and INGRESS_SCHEME as http or https into the app container. Runtime config is rendered from those values during container startup, so generated sites should not carry separate app URL env vars for the same public route.

Enable ISLE bot mitigation with sitectl set:

sitectl set bot-mitigation on

See the ISLE sitectl plugin docs for Fedora, Blazegraph, IIIF, derivative microservices, cache, sync, migration, ingress, and bot mitigation details.

Makefile

The Makefile is intentionally small. It only keeps ISLE-specific targets that are not core sitectl operations:

make demo-objects
make sync-solr-conf
make create-starter-site-pr
make clean

Use sitectl compose ... and sitectl set ... directly for normal stack operations.

Template notes

This template starts from the upstream ISLE Site Template and applies LibOps defaults:

• Drupal codebase at the repository root.
• Fedora replaced with Drupal private files by default.
• Blazegraph removed by default.
• Cantaloupe replaced with Triplet.
• LibOps images for the application services.

Only MariaDB and the one-shot database-init service receive DB_ROOT_PASSWORD. The initializer idempotently creates the Drupal database and scoped user before the app starts; the long-running Drupal service receives only DRUPAL_DEFAULT_DB_PASSWORD as DB_PASSWORD. Optional components that need their own database follow the same scoped-credential boundary. Initialization also generates the dormant TOMCAT_ADMIN_PASSWORD credential so enabling Fedora later never falls back to a baked-in default.

ActiveMQ, Alpaca, and Drupal share the generated ACTIVEMQ_PASSWORD through service-specific secret targets. Drupal receives it as DRUPAL_DEFAULT_BROKER_PASSWORD together with the non-secret admin broker username, so the rendered Islandora settings use authenticated STOMP rather than relying on a broker default.

License

The Docker Compose template and LibOps-specific setup in this repository are licensed under the MIT License. The upstream Islandora starter site is licensed separately under the GNU General Public License v2; see LICENSE.islandora-starter-site.

Attribution

Forked from https://github.com/Islandora-Devops/isle-site-template