README

Islandora Starter Site

A starting Drupal configuration for Islandora sites.

What is a Starter Site?

The Starter Site is a ready-to-customize Drupal site that shows off Islandora's features. It can be used as a template for your site, but once you start using it, your site (and all its config) are managed by you. Like a template MS Word document, changes that are made to the template after you've started using it cannot and will not be automatically transferred into your copy (in this case, your Islandora site). If you need these kinds of services done for you, check out our service providers. However, we will endeavour to document and communicate changes, should you wish to incorporate them.

The Starter site contains instructions to set up a Drupal site, but several features requre the presence of external services such as Fedora, Solr, and others (see installation instructions below).

The Starter Site uses semantic-like versioning now, but this is only for compatibility with the tools that install it. The Starter Site will change major versions whenever it requires something new from the tools that create its environment (Playbook/ISLE).

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
ISLE Site Template - Docker-based
- The default installation instructions use the Starter Site.

Manual Installation

The config files in the Starter Site assume a full suite of external services. If you do not need all the external services (such as Fedora) then you can skip them but you will also want to adjust the Drupal configs. Such a partial install is beyond the scope of this document.

Prerequisites

PHP and Composer installed
A Database server installed and configured for Drupal
- The Starter Site installs drivers for MySQL/MariaDB/Percona (mysql), PostgreSQL (pgsql), and SQLite (sqlite). Using other (contrib) drivers would require additional installation/configuration, and is outside the scope of this document.
Fedora Commons (FCRepo) installed
1. Syn installed and configured with a key.
Triplestore installed
Cantaloupe installed
1. A IIIF URL is expected to be resolvable, and to accept full URLs as resource IDs. If the URL is not http://127.0.0.1:8080/cantaloupe/iiif/2, this will have to be set (see Usage step 5).
ActiveMQ/Alpaca/Crayfish installation
1. ActiveMQ expected to be listening for STOMP messages at a tcp url. If not the default tcp://127.0.0.1:61613, this will have to be set (see Usage step 5)
2. Queues (and underlying (micro)services) configured appropriately:

A Drupal-compatible web server
FITS Web Service and CrayFits installed
- Further details in the islandora_fits module's README/documentation
A Solr server installed or available with a core set up
- Further details on Drupal's Search API Solr module page.
- If not available at 127.0.0.1:8983, or if the core name is not ISLANDORA its information will need to be set up (see Usage step 5)

Usage

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.

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.

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.
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
```
Configure the locations of external services.

Change the following Drupal configs to your values using any method (GUI, drush cset, config overrides in settings.php...):

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. Setting the appropriate location as key.key.islandora_rsa_key key_provider_settings.file_location (using the methods listed in step 5 or at /admin/config/system/keys/manage/islandora_rsa_key)
Run the migrations tagged with islandora to populate some taxonomies, specifying the --userid targeting the user with the fedoraadmin role:
```
composer exec -- drush migrate:import --userid=1 --tag=islandora
```

This should get you a starter Islandora site with:

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

Post-installation cleanup

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

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 in this section (including when they should be removed).

None, presently.

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.

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:

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.
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
```
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
Export the site's config, to capture any changed configuration:
```
composer exec -- drush config:export sync
```
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

islandora / islandora-starter-site

Maintainers

Details