Islandora Starter Site

A starting Drupal configuration for Islandora sites.

Quick Installation

To launch a fully-functioning Islandora Starter site as well as the (non-Drupal) tools and services that support it, try one of the Islandora deployment tools:

• Islandora Playbook - Ansible-based, works locally with VirtualBox and Vagrant.
  • use the starter (default) or starter_dev option
• ISLE-DC - Docker-based
  • use the make starter or make starter_dev option

Manual Installation

Your mileage may vary. Depending on your particular use case, some Islandora prerequisites may not be needed; for example, if you do not need Fedora, Cantaloupe, or otherwise you can skip their installation and configuration. Note that this may leave behind stray configurations that should be removed. This is left as an exercise for the site admin, as documenting such advanced usage is beyond the scope of this document.

Prerequisites

1. PHP and Composer installed
2. Database installation/configuration for Drupal
   • Drivers for MySQL/MariaDB/Percona (mysql), PostgreSQL (pgsql), and SQLite (sqlite) are installed. Using other (contrib) drivers would require additional installation/configuration steps outside the scope of this document.
3. Fedora Commons (FCRepo) installation
   1. Syn installed and configured with a key.
4. Triplestore installation
5. Cantaloupe installation
   1. http://127.0.0.1:8080/cantaloupe/iiif/2 is expected to be resolvable, and to accept full URLs as resource IDs.
6. ActiveMQ/Alpaca/Crayfish installation
   1. ActiveMQ expected to be listening for STOMP messages at tcp://127.0.0.1:61613
   2. Queues (and underlying (micro)services) configured appropriately:

Queue Name	Destination
islandora-connector-homarus	Homarus (Crayfish ffmpeg transcoding microservice)
islandora-indexing-fcrepo-delete	FCRepo indexer
islandora-indexing-triplestore-delete	Triplestore indexer
islandora-connector-houdini	Houdini (Crayfish imagemagick transformation microservice)
islandora-connector-ocr	Hypercube (Crayfish OCR microservice)
islandora-indexing-fcrepo-file-external	FCRepo indexer
islandora-indexing-fcrepo-media	FCRepo indexer
islandora-indexing-triplestore-index	Triplestore indexer
islandora-indexing-fcrepo-content	FCRepo indexer
islandora-connector-fits	CrayFits derivative processor

7. A Drupal-compatible web server
8. A Matomo installation
   • Further details in the matomo module's documentation
9. FITS Web Service and CrayFits installations
   • Further details in the islandora_fits module's README/documentation

Usage

1. Create a project based on this repository:

   composer create-project islandora/islandora-starter-site

   This should:

   1. Grab the code and all PHP dependencies,
   2. Scaffold the site, and have the default site's settings.php point at our included configuration for the next step.

2. Configure Flysystem's fedora scheme in the site's settings.php:

   $settings['flysystem'] = [
     'fedora' => [
       'driver' => 'fedora',
       'config' => [
         'root' => 'http://127.0.0.1:8080/fcrepo/rest/',
       ],
     ],
   ];

   Changing http://127.0.0.1:8080 to point at your Fedora installation.

3. Install the site:

   composer exec -- drush site:install --existing-config

   After this step, you should configure your web server to serve web/ directory as its document root.

4. Add (or otherwise create) a user to the fedoraadmin role; for example, giving the default admin user the role:

   composer exec -- drush user:role:add fedoraadmin admin

5. Make the Syn/JWT keys available to our configuration either by (or by some combination of):

   1. Symlinking the private key to /opt/islandora/auth/private.key; or,
   2. Configuring the location to the private key on the site at http://<your-web-server>/admin/config/system/keys/manage/islandora_rsa_key (where <your-web-server> accesses your web server which is configured to serve from the starter site's web/ directory).

6. Run the migrations in the islandora migration group to populate the base taxonomies, specifying the --userid targeting the user with the fedoraadmin role:

   composer exec -- drush migrate:import --userid=1 islandora_tags,islandora_defaults_tags,islandora_fits_tags

This should get you a starter Islandora site with:

• A basic node bundle to represent repository content
• A handful of media types presentable
• RDF and JSON-LD mappings for miscellaneous entities to support storage in Fedora, Triplestore indexing and client requests.

Post-installation cleanup

1. Uninstall the database driver modules you are not using; for example, if you are using mysql to use a MySQL-compatible database, you should be clear to uninstall the pgsql (PostgreSQL) and sqlite (SQLite) modules:

   composer exec -- drush pm:uninstall pgsql sqlite

Known issues

Warnings/errors during installation

Some modules presently have some bad expectations as to the system state when hook_install() is invoked and as such, some messages are emitted:

$ composer exec -- drush site:install --existing-config --db-url=mysql://user:***@localhost/db

 You are about to:
 * DROP all tables in your 'db' database.

 Do you want to continue? (yes/no) [yes]:
 >

 [notice] Starting Drupal installation. This takes a while.
 [notice] Performed install task: install_select_language
 [notice] Performed install task: install_select_profile
 [notice] Performed install task: install_load_profile
 [notice] Performed install task: install_verify_requirements
 [notice] Performed install task: install_settings_form
 [notice] Performed install task: install_verify_database_ready
 [notice] Performed install task: install_base_system
 [notice] Performed install task: install_bootstrap_full
 [error]  The Flysystem driver is missing.
 [warning] Could not find required jsonld.settings to add default RDF namespaces.
 [notice] Performed install task: install_config_import_batch
 [notice] Performed install task: install_config_download_translations
 [notice] Performed install task: install_config_revert_install_changes
 [notice] Performed install task: install_configure_form
 [notice] Performed install task: install_finished
 [success] Installation complete.  User name: admin  User password: ***
$

There are two "unexpected" messages there:

• [error] The Flysystem driver is missing.
  • Appears to be from the flysystem module's hook_install() implementation where it tries to ensure that all schemes defined are in a state ready to be used; however, all the modules are not yet enabled (in the particular case, islandora is not actually enabled, so the fedora driver is unknown), and so leading to this message being emitted. The islandora module is enabled by the time the command exits, so this message should be ignorable.
• [warning] Could not find required jsonld.settings to add default RDF namespaces.
  • Appears to be from the islandora module's hook_install() implementation where it tries to alter the jsonld module's jsonld.settings config object to add some namespaces; however, because the configs are not yet installed when installing the modules with --existing-config, it fails to find the target configuration to alter it. As exported, the jsonld.settings already contains the alterations (at time of writing), so this warning should be ignorable.

In summary: These two messages seem to be ignorable.

Patches

There are currently no patches included with the Starter Site. If a patch (external or internal) is necessary, it can be applied automatically by composer by using the composer-patches plugin. Any patches included in the Starter Site should be described fully here (including when they should be removed).

Ongoing Project Maintenance

It is anticipated that Composer will be used to manage Drupal and its extensions, including Islandora's suite of modules. The Drupal project has already documented many of the interactions in this space, so we will just list and summarize them here:

Using Composer to Install Drupal and Manage Dependencies

• The "install" describing:

  • Composer's create-project command, which we describe above being used to install using this "starter site" project; and,
  • The drush site:install/drush si command, described above being used to install Drupal via the command line.

• "manage[ment]", describing:

  • Composer's require command, used to add additional dependencies to your project
  • Updating, linking out to additional documentation for Drupal's core and modules:
    • Updating Drupal core via Composer
    • Updating Modules and Themes using Composer

  Generally, gets into using Composer's update command to update extensions according to the specifications in the composer.json, and Composer's require command to change those specifications when necessary to cross major version boundaries.

It is also recommended to monitor and/or subscribe to Drupal's security advisories to know when it might be necessary to update.

Documentation

Further documentation for this ecosystem is available on the Islandora documentation site.

Troubleshooting/Issues

Having problems or solved a problem? Check out the Islandora Google Groups for a solution.

• Islandora Group
• Islandora Dev Group

Development

If you would like to contribute, please get involved by attending our weekly Tech Call. We love to hear from you!

If you would like to contribute code to the project, you need to be covered by an Islandora Foundation Contributor License Agreement or Corporate Contributor License Agreement. Please see the Contributor License Agreements page on the islandora-community wiki for more information.

We recommend using the islandora-playbook to get started.

General starter site development process

For development of this starter site proper, we anticipate something of a particular flow being employed, to avoid having other features and modules creep into the base configurations. The expected flow should go something like:

1. Provisioning an environment making use of the starter site

   • It may be desirable to replace the environment's starter site installation with a repository clone of the starter site at this point to avoid otherwise manually copying changes out to a clone.

2. Importing the config of the starter site

   1. This should overwrite any configuration made by the provisioning process, including disabling any modules that should not be generally enabled, and installing those that should be.

   2. This might be done with a command in the starter site directory such as:

      composer exec -- drush config:import sync

3. Perform the desired changes, such as:

   • Using composer to manage dependencies:
     • If updating any Drupal extensions, this should be followed by running Drupal's update process, in case there are update hooks to run which might update configuration.
   • Performing configuration on the site

4. Export the site's config, to capture any changed configuration:

   composer exec -- drush config:export sync

5. Copying the config/sync directory (with its contents) and composer.json and composer.lock files into a clone of the starter site git repository, committing them, pushing to a fork and making a pull request.

   • If the environment's starter site installation was replaced with a repository clone, you should be able to skip the copying, and just commit your changes, push to a fork and make a pull request to the upstream repository.

Periodically, it is expected that releases will be published/minted/tagged on the original repository; however, it is important to note that automated updates across releases of this starter site is not planned to be supported. That said, we plan to include changelogs with instructions of how the changes introduced since the last release might be effected in derived site for those who wish to adopt altered/introduced functionality into their own site.

Development modules

A few modules are included in our require-dev section but left uninstalled from the Drupal site, as they may be of general utility but especially development. Included are:

• config_inspector: Helps identify potential issues between the schemas defined and active configuration.
• devel: Blocks and tabs for miscellaneous tasks during development
• restui: Helper for configuration of the core rest module

These modules might be enabled via the GUI or CLI; however, they should be disabled before performing any kind of config export, to avoid having their enabled state leak into configuration.

License

GPLv2