Deploying Islandora

Introduction

Islandora is an open-source digital repository framework that combines Drupal, Fedora, and a suite of microservices to enable the creation, management, and preservation of digital collections. ISLE (ISLandora Enterprise) is the Docker-based deployment method that packages the entire Islandora stack into a set of containers that are easy to install, configure, and maintain.

Developed by a community of libraries, archives, and museums, Islandora provides institutions with the tools to build robust digital repositories for managing complex digital assets including images, audio, video, PDFs, and compound objects. The platform leverages Drupal’s powerful content management capabilities while utilizing Fedora for standards-based digital object storage.

Key highlights of Islandora:

Drupal Foundation: Built on Drupal 10 for flexible content modeling and user interface customization
Fedora Repository: Standards-based digital object storage with preservation capabilities
Microservices Architecture: Modular services for derivatives, OCR, and media processing
Linked Data Support: Native support for RDF and linked data standards
IIIF Compliance: International Image Interoperability Framework for image delivery
Solr Search: Powerful faceted search and discovery
Flexible Content Models: Support for various digital object types and relationships
Preservation Ready: Built-in support for digital preservation workflows
Community Driven: Active open-source community with regular updates
Institutional Scale: Designed for libraries, archives, and cultural heritage organizations

This guide walks through deploying Islandora using ISLE on Klutch.sh, configuring the component services, and setting up the platform for production use.

Why Deploy Islandora on Klutch.sh

Deploying Islandora on Klutch.sh provides several advantages for digital repository management:

Simplified Deployment: ISLE packages Islandora’s complex stack into Docker containers that Klutch.sh can deploy automatically. Push to GitHub, and your repository deploys.

Persistent Storage: Attach persistent volumes for Fedora objects, Drupal files, and database storage. Your digital collections survive container updates.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your repository.

GitHub Integration: Connect your ISLE configuration repository for automated deployments when you update configurations.

Scalable Resources: Allocate CPU and memory appropriate for your collection size and expected traffic.

Environment Variable Management: Securely store database credentials and API keys through Klutch.sh’s environment system.

Custom Domains: Use your institution’s domain for a professional repository presence.

Always-On Availability: Your digital repository remains accessible 24/7 for researchers and the public.

Prerequisites

Before deploying Islandora on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your ISLE configuration
Basic familiarity with Docker and containerization concepts
Understanding of Drupal administration
(Optional) A custom domain for your repository

Understanding Islandora Architecture

ISLE deploys multiple interconnected containers:

Drupal: The main web application providing user interface, content management, and API endpoints.

Fedora: Repository service storing digital objects and their metadata in a standards-compliant manner.

Solr: Search index providing faceted search and discovery capabilities.

Alpaca: Message broker connecting Drupal to microservices for derivative generation.

Crayfish: Suite of microservices handling image processing, PDF generation, and OCR.

Database: MariaDB/MySQL storing Drupal configuration and content metadata.

Traefik: Reverse proxy handling routing between services.

Preparing Your Repository

To deploy Islandora on Klutch.sh, fork or clone the official ISLE repository.

Repository Structure

isle-dc/
├── Dockerfile
├── docker-compose.yml
├── .env
├── certs/
├── config/
│   ├── drupal/
│   ├── fedora/
│   └── solr/
└── README.md

Creating a Custom Dockerfile

For Klutch.sh deployment, create a consolidated Dockerfile:

FROM islandora/drupal:latest

# Set environment variables
ENV DRUPAL_DEFAULT_PROFILE=standard
ENV DRUPAL_DEFAULT_SITE_ADMIN_PASSWORD=${ADMIN_PASSWORD}

# Configure for production
ENV PHP_MEMORY_LIMIT=512M
ENV PHP_MAX_EXECUTION_TIME=300

# Expose Drupal port
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=180s --retries=5 \
  CMD curl -f http://localhost/ || exit 1

Environment Variables Reference

Variable	Required	Default	Description
`DRUPAL_DEFAULT_SITE_URL`	Yes	-	Public URL of your Islandora instance
`DRUPAL_DEFAULT_SITE_ADMIN_PASSWORD`	Yes	-	Admin password for Drupal
`MYSQL_HOST`	Yes	-	Database host address
`MYSQL_DATABASE`	Yes	-	Database name
`MYSQL_USER`	Yes	-	Database username
`MYSQL_PASSWORD`	Yes	-	Database password
`FEDORA_URL`	Yes	-	URL of Fedora repository service
`SOLR_URL`	Yes	-	URL of Solr search service

Deploying Islandora on Klutch.sh

Deploying a full Islandora stack requires multiple services. Follow these steps:

Fork the ISLE Repository

Fork or clone the official ISLE repository:

git clone https://github.com/Islandora-Devops/isle-dc.git
cd isle-dc

Configure Environment

Create your environment configuration:

cp sample.env .env

Edit the .env file with your settings.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “islandora” or “digital-repository”.

Deploy Supporting Services

Islandora requires several supporting services. Deploy each as a separate app:

MariaDB: Database for Drupal
Fedora: Digital object repository
Solr: Search and indexing

Deploy the Drupal Application

Create the main Drupal/Islandora app:

Connect your GitHub repository
Select the ISLE repository
Configure HTTP traffic on port 80

Set Environment Variables

Configure the required environment variables:

Variable	Value
`DRUPAL_DEFAULT_SITE_URL`	`https://your-app-name.klutch.sh`
`DRUPAL_DEFAULT_SITE_ADMIN_PASSWORD`	Your secure admin password
`MYSQL_HOST`	Your MariaDB service address
`MYSQL_DATABASE`	`drupal`
`MYSQL_USER`	Your database username
`MYSQL_PASSWORD`	Your database password

Attach Persistent Volumes

Add persistent storage for your digital repository:

Mount Path	Recommended Size	Purpose
`/var/www/drupal/web/sites/default/files`	100+ GB	Drupal public files
`/var/www/drupal/private`	50+ GB	Drupal private files
`/data`	500+ GB	Fedora digital objects (if combined)

Deploy and Initialize

Click Deploy and wait for all services to start. The initial setup may take several minutes.

Complete Drupal Installation

Access your Islandora instance and complete the Drupal installation wizard if prompted.

Initial Configuration

Admin Access

After deployment:

Navigate to https://your-app-name.klutch.sh/user/login
Log in with username admin and your configured password
Complete any remaining setup steps

Content Types

Islandora provides pre-configured content types:

Repository Item: Base type for digital objects
Collection: Container for grouping items
Paged Content: Books and multi-page documents
Audio: Audio recordings
Video: Video content
Image: Single images

Configuring Media Types

Set up media handling:

Navigate to Structure > Media Types
Configure accepted file formats
Set up derivative generation
Configure IIIF image serving

Managing Collections

Creating Collections

To create a new collection:

Navigate to Content > Add Content > Collection
Enter collection title and description
Configure access permissions
Set finding aids and metadata
Publish the collection

Adding Items

Add items to your repository:

Navigate to Content > Add Content > Repository Item
Select the parent collection
Upload digital files
Enter descriptive metadata
Configure access and rights
Publish the item

Batch Ingest

For large collections:

Prepare metadata in CSV format
Use the Migrate module for batch import
Configure field mappings
Run the migration
Verify imported content

Production Best Practices

Security Recommendations

Admin Security: Use strong passwords and limit admin accounts
Database Security: Restrict database access to application containers only
File Permissions: Ensure proper file permissions on volumes
Regular Updates: Keep Drupal and modules updated
Access Control: Configure content access permissions appropriately

Performance Optimization

Caching: Enable Drupal caching and consider Varnish
Search Indexing: Regularly optimize Solr indexes
Image Delivery: Use IIIF for efficient image serving
Database Tuning: Optimize MariaDB for your workload

Backup Strategy

Database Backups: Daily MariaDB dumps
Fedora Backups: Regular Fedora repository exports
File Backups: Back up Drupal files directory
Configuration Export: Export Drupal configuration regularly
Test Restores: Periodically verify backup integrity

Troubleshooting Common Issues

Microservices Not Connecting

Symptoms: Derivatives not generating, services timing out.

Solutions:

Verify all service containers are running
Check network connectivity between containers
Review service logs for errors
Verify URLs in environment configuration

Search Not Working

Symptoms: Content not appearing in search results.

Solutions:

Check Solr container status
Reindex content in Drupal
Verify Solr schema is correct
Check Solr connection settings

Slow Performance

Symptoms: Pages load slowly, timeouts occur.

Solutions:

Enable caching in Drupal
Increase PHP memory limits
Optimize database queries
Scale up container resources

Additional Resources

Conclusion

Deploying Islandora on Klutch.sh enables institutions to run a professional digital repository platform with Docker-based simplicity. ISLE’s containerized architecture combined with Klutch.sh’s persistent storage and HTTPS support provides a solid foundation for managing digital collections.

Whether you’re building a new digital repository or migrating an existing collection, Islandora on Klutch.sh delivers the infrastructure needed for reliable, standards-compliant digital preservation and access.