Islandora · dannylamb · Jul 15, 2020 · Nov 13, 2019 · Nov 13, 2019 · Nov 13, 2019
diff --git a/docs/assets/adding_a_jwt_rsa_key.png b/docs/assets/adding_a_jwt_rsa_key.png
diff --git a/docs/assets/adding_a_search_index.png b/docs/assets/adding_a_search_index.png
diff --git a/docs/assets/adding_a_solr_search_server.png b/docs/assets/adding_a_solr_search_server.png
diff --git a/docs/assets/configuring_flysystem_to_use_fedora.png b/docs/assets/configuring_flysystem_to_use_fedora.png
diff --git a/docs/assets/configuring_iiif.png b/docs/assets/configuring_iiif.png
diff --git a/docs/assets/configuring_islandora.png b/docs/assets/configuring_islandora.png
diff --git a/docs/assets/configuring_openseadragon.png b/docs/assets/configuring_openseadragon.png
diff --git a/docs/assets/configuring_standard_solr_connector.png b/docs/assets/configuring_standard_solr_connector.png
diff --git a/docs/assets/configuring_the_jwt_rsa_key_for_use.png b/docs/assets/configuring_the_jwt_rsa_key_for_use.png
diff --git a/docs/assets/setting_the_solr_install_directory.png b/docs/assets/setting_the_solr_install_directory.png
diff --git a/docs/assets/specifying_the_solr_server.png b/docs/assets/specifying_the_solr_server.png
diff --git a/docs/installation/component_overview.md b/docs/installation/component_overview.md
@@ -0,0 +1,68 @@
+# Component Overview
+
+A functioning Islandora 8 Stack is made up of dozens of components working in synchronization with each other to store information in your repository, manage that information, and disseminate it intelligently to users. Whether running an installation using the provided Ansible playbook or installing the stack manually, it may be helpful to have a brief overview of all the components we're going to need, in the order we're going to install them, as well as a brief introduction to each component's installation and configuration process.
+
+This list includes four different kinds of components:
+
+- Components which are hard-required (such as Drupal and the Islandora module)
+- Components for which defaults are provided but which can be swapped out (such as the software managing databases, or the repository's storage system)
+- Components that can't easily be swapped out but are not necessarily required (such as using Solr as the site's internal search engine)
+- Components which do not have official alternatives and are not necessarily required, but will likely exist on the vast majority of Islandora 8 installations (such as Alpaca and Crayfish)
+
+## The Webserver Stack - Apache, PHP, and MySQL/PostgreSQL
+
+Combined together, Apache, PHP, and MySQL/PostgreSQL comprise a LAMP or LAPP server used to provide end-user-facing components - namely, the website.
+
+**Apache** is the webserver that will serve up webpages to the public. It will also manage some internal funcionality provided by Crayfish, and will expose Cantaloupe to the public. We’ll be making changes to the VirtualHost entry, enabling some modules, and modifying the ports configuration. The VirtualHost entry will eventually be modified when we need to expose other services like Cantaloupe to the public.
+
+**PHP** is the runtime interpreter for all the code Drupal and Crayfish need to be processed. By default, installing PHP 7.2 will give us a command-line interpreter, as well as an interpreter for Apache. We’re going to install several PHP modules required and/or useful for the components that make use of PHP.
+
+**MySQL** and **PostgreSQL** are database management systems that we will use to store information for many different components like Drupal and Fedora. By default, the Ansible playbook installs MySQL, though this can be switched to PostgreSQL. The manual installation guide recommends and walks through installing and using PostgreSQL.
+
+## The Front-Facing CDM - Composer, Drush, and Drupal
+
+Composer will be used to install both Drupal and Drush simultaneously using Islandora's fork of the [drupal-project](https://github.com/Islandora/drupal-project) repository.
+
+**Composer** is an installer and dependency manager for PHP projects. We're going to need it to install components for any PHP code we need to make use of, including Drupal and Crayfish.
+
+**Drush** and **Drupal** are installed simultaneously using [drupal-project](https://github.com/Islandora/drupal-project). Drupal will serve up webpages and manage Islandora content, and Drush will help us get some things done from the command-line.
+
+## The Web Application Server - Tomcat and Cantaloupe
+
+Several applets will be deployed via their `.war` files into Tomcat, including Fedora and Cantaloupe.
+
+**Tomcat** serves up webpages and other kinds of content much like Apache, but is specifically designed to deploy Java applications as opposed to running PHP code.
+
+**Cantaloupe** is an image tileserver that Islandora will connect to and use to serve up extremely large images in a way that doesn't have an adverse effect on the overall system.
+
+## The Back-End File Management Repository - Fedora, Syn, and Blazegraph
+
+Fedora will be installed in its own section, rather than as part of the Tomcat installation, as the installation process is rather involved and requires some authorization pieces to be set up in order to connect them back to Drupal and other components.
+
+**Fedora** is the default backend repository that Islandora content will be synchronized with and stored in. A great deal of configuration will be required to get it up and running, including ensuring a database is created and accessible.
+
+**Syn** is the authorization piece that allows Fedora to connect to other components.
+
+**Blazegraph** will store representative graph data about the repository that can be queried using SPARQL. Some configuration will also be required to link it back to Fedora, as well as to ensure it is being properly indexed.
+
+## The Search Engine - Solr and search_api_solr
+
+The installation of Solr itself is rather straightforward, but a configuration will have to be generated and applied from the Drupal side.
+
+**Solr** will be installed as a standalone application. Nothing of particular importance needs to happen here; the configuration will be applied when `search_api_solr` is installed.
+
+**search_api_solr** is the Drupal module that implements the Solr API for Drupal-side searches. After installing and configuring the module, the `drush solr-gsc` command will be used to generate Solr configs, and these configs will be moved to the Solr configuration location.
+
+## The Asynchronous Background Services - Crayfish
+
+**Crayfish** is a series of microservices that perform different asynchronous tasks kicked off by Islandora. It contains a series of submodules that will be installed via Composer. Later, these configured components will be connected to Alpaca.
+
+## The Broker Connecting Everything - Karaf and Alpaca
+
+**Karaf**’s job is similar to Tomcat, except where Tomcat is a web-accessible endpoint for Java applets, Karaf is simply meant to be a container for system-level applets to communicate via its OSGI. Alpaca is one such applet; it will broker messages between Fedora and Drupal, and between Drupal and various derivative generation applications.
+
+**Alpaca** contains Karaf services to manage moving information between Islandora, Fedora, and Blazegraph as well as kicking off derivative services in Crayfish. These will be configured to broker between Drupal and Fedora using an ActiveMQ queue.
+
+## Finalized Drupal Configurations
+
+**Drupal configuration** exists as a series of .yaml files that can either be created in a feature, or exported from Drupal using the `content_sync` module. It can also be manually entered in via the UI. We're going to place configuration in a few different ways; Some content will be synchronized onto the site, and some core configurations from the main Islandora module will need to be run in order to facilitate ingest.
diff --git a/docs/installation/manual/configuring_drupal.md b/docs/installation/manual/configuring_drupal.md
@@ -0,0 +1,170 @@
+# Configuring Drupal
+
+After all of the above pieces are in place, installed, configured, started, and otherwise prepared, the last thing we need to do is to finally configure the front-end Drupal instance to wire all the installed components together.
+
+## Drupal Pre-Configuration
+
+### `settings.php`
+
+!!! notice
+    By default, `settings.php` is read-only for all users. It should be made writable while this pre-configuration is being done, then set back to `444` afterwards.
+
+Some additional settings will need to be established in your default `settings.php` before Drupal-side configuration can occur.
+
+The below configuration will establish `localhost` as a trusted host pattern, but on production sites this will need to be expanded to include the actual host patterns used by the site.
+
+`/opt/drupal/web/sites/default/settings.php`
+
+**Before**:
+> 789 |   'driver' => 'pgsql',
+
+> 790 | );
+
+**After**:
+> 789 |   'driver' => 'pgsql',
+
+> 790 | );
+
+> 791 | $settings['trusted_host_patterns'] = [
+
+> 792 |   'localhost',
+
+> 793 | ];
+
+> 794 | $settings['flysystem'] = [
+
+> 795 |   'fedora' => [
+
+> 796 |     'driver' => 'fedora',
+
+> 797 |     'config' => [
+
+> 798 |       'root' => 'http://localhost:8080/fcrepo/rest/',
+
+> 799 |     ],
+
+> 800 |   ],
+
+> 801 | ];
+
+Once this is done, refresh the cache to take hold of the new settings.
+
+```bash
+cd /opt/drupal
+drush -y cr
+```
+
+## Islandora
+
+### Downloading Islandora
+
+The Islandora Drupal module contains the core code to create a repository ecosystem in a Drupal environment. It also includes several submodules; of importance to us is `islandora_core_feature`, which contains the key configurations that turn a Drupal site into an Islandora site.
+
+Islandora also provides an [`islandora_defaults`](https://github.com/Islandora/islandora_defaults) module that contains additional configurations considered an appropriate launching point for configuring a site. We're going to first enable the `islandora_defaults` module before doing any wiring on the front-end.
+
+Take note of some of the other comments in the below bash script for an idea of what the other components are expected, and which may be considered optional.
+
+```bash
+cd /opt/drupal
+# This is a convenience piece that will help speed up most of the rest of our
+# process working with Composer and Drupal.
+sudo -u www-data composer require zaporylie/composer-drupal-optimizations:^1.0
+# Since islandora_defaults is near the bottom of the dependency chain, requiring
+# it will get most of the modules and libraries we need to deploy a standard
+# Islandora site.
+sudo -u www-data composer require islandora/islandora_defaults:dev-8.x-1.x
+# These can be considered important or required depending on your site's
+# requirements; some of them represent dependencies of Islandora submodules.
+sudo -u www-data composer require drupal/pdf:1.x-dev
+sudo -u www-data composer require drupal/rest_oai_pmh:^1.0
+sudo -u www-data composer require drupal/facets:^1.3
+sudo -u www-data composer require drupal/restui:^1.16
+sudo -u www-data composer require drupal/rdfui:^1.0-beta1
+sudo -u www-data composer require drupal/content_browser:^1.0@alpha
+# These tend to be good to enable for a development environment, or just for a
+# higher quality of life when managing Islandora. That being said, devel should
+# NEVER be enabled on a production environment, as it intentionally gives the
+# user tools that compromise the security of a site.
+sudo -u www-data composer require drupal/console:~1.0
+sudo -u www-data composer require drupal/devel:^2.0
+sudo -u www-data composer require drupal/admin_toolbar:^2.0
+# Islandora also provides a theme called Carapace designed to work well out of
+# the box with an Islandora site.
+sudo -u www-data composer require islandora/carapace:dev-8.x-3.x
+```
+
+### Enabling Downloaded Components
+
+Components we've now downloaded using `composer require` can be enabled simultaneously via `drush`, which will ensure they are installed in the correct dependent order. Enabling `islandora_defaults` will also ensure all content types and configurations are set up in Islandora. The installation process for all of these modules will likely take some time.
+
+!!! notice
+    This list of modules assumes that all of the above components were downloaded using `composer require`; if this is not the case, you may need to pare down this list manually. It also includes `devel`, which again, should not be enabled on production sites.
+
+```bash
+cd /opt/drupal
+drush -y en rdf responsive_image devel syslog serialization basic_auth rest restui search_api_solr search_api_solr_defaults facets content_browser pdf admin_toolbar islandora_defaults controlled_access_terms_defaults islandora_breadcrumbs islandora_iiif islandora_oaipmh
+# If Carapace was downloaded, now is the time to enable and set it as well.
+drush -y theme:enable carapace
+drush -y config-set system.theme default carapace
+# After all of this, rebuild the cache.
+drush -y cr
+```
+
+### Adding a JWT Configuration to Drupal
+
+To allow our installation to talk to other services via Syn, we need to establish a Drupal-side JWT configuration using the keys we generated at that time.
+
+Log onto your site as an administrator at `/user`, then navigate to `/admin/config/system/keys/add`. Some of the settings here are unimportant, but pay close attention to the **Key type**, which should match the key we created earlier (an RSA key), and the **File location**, which should be the ultimate location of the key we created for Syn on the filesystem, `/opt/keys/syn_private.key`.
+
+![Adding a JWT RSA Key](../../assets/adding_a_jwt_rsa_key.png)
+
+Click **Save** to create the key.
+
+Once this key is created, navigate to `/admin/config/system/jwt` to select the key you just created from the list. Note that before the key will show up in the **Private Key** list, you need to select that key's type in the **Algorithm** section, namely `RSASSA-PKCS1-v1_5 using SHA-256 (RS256)`.
+
+![Configuring the JWT RSA Key for Use](../../assets/configuring_the_jwt_rsa_key_for_use.png)
+
+Click **Save configuration** to establish this as the JWT key configuration.
+
+### Configuring Islandora
+
+Navigate to the Islandora core configuration page at `/admin/config/islandora/core` to set up the core configuration to connect to Gemini. Of note here, the **Gemini URL** will need to be established to facilitate the connection to Fedora, and the appropriate **Bundles with Gemini URI pseudo field** types will need to be checked off.
+
+!!! notice
+    Any other Drupal content types you wish to synchronize with Fedora should also be checked off here.
+
+![Configuring Islandora](../../assets/configuring_islandora.png)
+
+### Configuring Islandora IIIF
+
+Navigate to `/admin/config/islandora/iiif` to ensure that Islandora IIIF is pointing to our Cantaloupe server.
+
+![Configuring Islandora IIIF](../../assets/configuring_iiif.png)
+
+Next, configure Openseadragon by navigating to `/admin/config/media/openseadragon` and ensuring everything is set up properly.
+
+![Configuring Openseadragon](../../assets/configuring_openseadragon.png)
+
+### Establishing Flysystem as the Default Download Method
+
+Navigate to `/admin/config/media/file-system` to set the **Default download method** to the one we created in our `settings.php`.
+
+![Configuring Flysystem to Use Fedora](../../assets/configuring_flysystem_to_use_fedora.png)
+
+### Giving the Administrative User the `fedoraAdmin` Role
+
+In order for data to be pushed back to Fedora, the site administrative user needs the `fedoraAdmin` role.
+
+```
+cd /opt/drupal
+sudo -u www-data drush -y urol "fedoraadmin" islandora
+```
+
+### Running Feature Migrations
+
+Finally, to get everything up and running, run the Islandora Core Features and Islandora Defaults migrations.
+
+```bash
+cd /opt/drupal
+sudo -u www-data drush -y -l localhost --userid=1 mim --group=islandora
+```