This post is an addendum to earlier posts 021 and 058, with simiar titles. It is intended to chronicle my efforts to migrate to a local development instance of Digital.Grinnell on my work-issued iMac, MA8660, currently identified as MAD25W812UJ1G9.

Goal

The goal of this project is once again to spin up a local Islandora stack using the ISLE project following the guidance of the project’s install-local-migrate document. My process will be slightly different than documented since I’ve already created a pair of private dg-isle and dg-islandora repositories. This workflow will also take steps to introduce elements like the Digital Grinnell theme and custom modules like DG7. Once these pieces are in-place and working, I’ll begin adding other critical components as well as a robust set of data gleaned from https://digital.grinnell.edu/.

Changes Since Post 058

There have been three significant changes since I last attempted this effort:

  1. ISLE v1.5.1 is now the latest release,
  2. I now have proper HTTPS access to, and availability of, DGDockerX.Grinnell.edu to use for staging ISLE, and
  3. All of my GitHub-hosted projects have moved from a local directory of ~/Projects to ~/GitHub.

Using This Document

There are just a couple of notes regarding this document that I’d like to pass along to make it more useful.

  • Gists - You will find a few places in this post where I generated a gist to take the place of lengthy command output. Instead of a long stream of text you’ll find a simple link to a gist.

  • Workstation Commands - There are lots of places in this document where I’ve captured a series of command lines along with output from those commands in block text. Generally speaking, after each such block you will find a Workstation Commands table that can be used to conveniently copy and paste the necessary commands directly into your workstation. The tables look something like this:

Workstation Commands
cd ~/GitHub
git clone https://github.com/DigitalGrinnell/ISLE
cd ISLE
git checkout -b ld
  • Apache Container Commands - Similar to Workstation Commands, a tabulated list of commands may appear with a heading of Apache Container Commands. *Commands in such tables can be copied and pasted into your command line terminal, but ONLY after you have opened a shell into the Apache container. The asterisk (*) at the end of the table heading is there to remind you of this! See the next section of this document for additional details. These tables looks something like this:
Apache Container Commands*
cd /var/www/html/sites/all/modules/contrib
drush dl backup_migrate
drush -y en backup_migrate

Opening a Shell in the Apache Container

This is something I find myself doing quite often during ISLE configuration, so here’s a reminder of how I generally do this…

Workstation Commands
docker exec -it isle-apache-ld bash

Cleaning Up

I typically use the following command stream to clean up any Docker cruft before I begin anew. Note: Uncomment the third line ONLY if you want to delete images and download new ones. If you do, be patient, it could take several minutes depending on connection speed.

Workstation Commands
docker stop $(docker ps -q)
docker rm -v $(docker ps -qa)
# docker image rm $(docker image ls -q) --force
docker system prune --force

Local ISLE Installation: Migrate Existing Islandora Site

What follows is my annotated copy of Local ISLE Installation: Migrate Existing Islandora Site. Annotations in this document use the annotation shortcode and appear in a highlighted box like the one you are reading from now.

Expectations: It takes an average of 2-4+ hours to read this documentation and complete this installation.

This Local ISLE Installation builds a local environment for the express purpose of migrating a previously existing Islandora site onto the ISLE platform. If you need to build a brand new local development site, please stop and use the Local ISLE Installation: New Site instead.

This Local ISLE Installation will use a copy of a currently running Production Islandora Drupal website and an empty Fedora repository for end users to test migration to ISLE and do site development and design with the end goal of deploying to ISLE Staging and Production environments for public use. The final goal would be to cut over from the existing non-ISLE Production and Staging servers to their new ISLE counterparts.

This Local ISLE Installation will allow you to locally view this site in your browser with the domain of your choice (Example:https://yourprojectnamehere.localdomain”), instead of being constrained to the Demo URL (“https://isle.localdomain”).

This document has directions on how you can save newly created ISLE code into a git software repository as a workflow process designed to manage and upgrade the environments throughout the development process from Local to Staging to Production. The ISLE Installation: Environments documentation offers an overview of the ISLE structure, the associated files, and what values ISLE end users should use for the “.env”, “local.env”, etc.

This document does not have directions on how you can save previously existing Islandora Drupal code into a git repository and assumes this step has already happened. The directions below will explain how to clone Islandora Drupal code from a previously existing Islandora Drupal git repository that should already be accessible to you.

Please post questions to the public Islandora ISLE Google group, or subscribe to receive emails. The Glossary defines terms used in this documentation.

Assumptions / Prerequisites

  • This Local ISLE installation expects that an existing Production Islandora Drupal site will be imported on a personal computer for further ISLE migration testing, Drupal theme development, ingest testing, etc.

  • You will be using ISLE version 1.2.0 or higher.

  • You are using Docker-compose 1.24.0 or higher.

  • You have git installed on your personal computer.

  • You have a previously existing private Islandora Drupal git repository.

  • You have access to a private git repository in Github, Bitbucket, Gitlab, etc.

    • If you do not, please contact your IT department for git resources, or else create an account with one of the above providers.
    • WARNING: Only use Private git repositories given the sensitive nature of the configuration files. DO NOT share these git repositories publicly.
  • For Microsoft Windows:

    • You have installed Git for Windows and will use its provided “Git Bash” as your command line interface; this behaves similarly to LINUX and UNIX environments. Git for Windows also installs “openssl.exe” which will be needed to generate self-signed SSL certs. (Note: PowerShell is not recommended as it is unable to run UNIX commands or execute bash scripts without a moderate degree of customization.)
    • Set your text editor to use UNIX style line endings for files. (Text files created on DOS/Windows machines have different line endings than files created on Unix/Linux. DOS uses carriage return and line feed ("\r\n”) as a line ending, which Unix uses just line feed ("\n”).)

Index of Instructions

  • Step 0: Copy Production Data to Your Personal Computer
  • Step 1: Choose a Project Name
  • Step 1.5: Edit “/etc/hosts” File
  • Step 2: Setup Git Project Repositories
  • Step 3: Git Clone the Production Islandora Drupal Site Code
  • Step 4: Edit the “.env” File to Change to the Local Environment
  • Step 5: Create New Users and Passwords by Editing “local.env” File
  • Step 6: Create New Self-Signed Certs for Your Project
  • Step 7: Download the ISLE Images
  • Step 8: Launch Process
  • Step 9: Import the Production MySQL Drupal Database
  • Step 10: Run Islandora Drupal Site Scripts
  • Step 11: Test the Site
  • Step 12: Ingest Sample Objects

Step 0: Copy Production Data to Your Personal Computer

Be sure to run a backup of any current non-ISLE systems prior to copying or exporting any files.

Drupal Site Files and Code

  1. Copy the /var/www/html/sites/default/files directory from your Production Apache server to an appropriate storage area on your personal computer. You’ll move this directory in later steps.

On the production instance of Digital.Grinnell the Apache container’s Drupal webroot at /var/www/html maps to the host, DGDocker1 with a static IP address of 132.161.132.103, at /opt/ISLE/persistent/html. So, as directed above, I put a copy of the /var/www/html/sites/default/files directory into ~/Desktop/migration-copy from my iMac like so:

Workstation Commands
rsync -aruvi islandora@132.161.132.103:/opt/ISLE/persistent/html/sites/default/files/. ~/Desktop/migration-copy/var/www/html/sites/default/files/ --progress
  1. Locate and note the previously existing private Islandora Drupal git repository.You’ll be cloning this into place once the ISLE project has been cloned in later steps.

Drupal Site Database

Prior to attempting this step, please consider the following:

  • Drupal website databases can have a multitude of names and conventions. Confer with the appropriate IT departments for your institution’s database naming conventions.

  • Recommended that the production databases be exported using the “.sql” /or “.gz” file formats (e.g. “prod_drupal_site_082019.sql.gz”) for better compression and minimal storage footprint.

  • If the end user is running multi-sites, there will be additional databases to export.

  • Do not export the “fedora3” database or any system tables (such as “information_schema”, “performance_schema”, “mysql”)

  • If possible, on the production Apache web server, run drush cc all from the command line on the production server in the /var/www/html directory PRIOR to any db export(s). Otherwise issues can occur on import due to all cache tables being larger than “innodb_log_file_size” allows

Export the Production MySQL Islandora Drupal Database

  • Export the MySQL database for the current Production Islandora Drupal site in use and copy it to your personal computer (local) in an easy to find place. In later steps you’ll be directed to import this file. Please be careful performing any of these potential actions below as the process impacts your Production site.

  • If you are not comfortable or familiar with performing these actions, we recommend that you instead work with your available IT resources to do so.

    • To complete this process, you may use a MySQL GUI client or, if you have command line access to the MySQL database server, you may run the following command, substituting your actual user and database names:
    • Example: mysqldump -u username -p database_name > prod_drupal_site_082019.sql
    • Copy this file down to your personal computer.

Even though the production instance of Digital.Grinnell has built-in facilities for performing this step, I chose to use an easily-repeated command line from an SSH session open on DGDocker1, like so:

DGDocker1 Commands
docker exec -w /var/www/html/sites/default isle-apache-dg drush cc all
docker exec -it isle-mysql-dg bash

Then, working inside the isle-mysql-dg container:

isle-mysql-dg Container Commands
mysqldump -u isle_dg_user -p isle_dg > prod_drupal_site_083120.sql
exit

Back in the DGDocker1 terminal:

DGDocker1 Commands
docker cp isle-mysql-dg:/prod_drupal_site_083120.sql ~/.
exit

Next, from my desktop terminal this command saved a copy of the exported database in /Users/markmcfate/Desktop/migration-copy/prod_drupal_site_083120.sql:

Workstation Commands
rsync -aruvi islandora@132.161.132.103:/home/islandora/prod_drupal_site_083120.sql ~/Desktop/migration-copy/prod_drupal_site_083120.sql

Fedora Hash Size (Conditional)

  • Are you migrating an existing Islandora site that has greater than one million objects?

    No

  • If true, then please carefully read about the Fedora Hash Size (Conditional).

Solr Schema and Islandora Transforms

This data can be challenging depending on the level of customizations to contend with and as such, ISLE maintainers recommends following one of the three (3), “Easy”, “Intermediate”, and “Advanced” strategies outlined below.

Strategy 1: Easy - Run “Stock” ISLE

Don’t copy any existing production Solr schemas, GSearch .xslt files, etc., and opt instead to use ISLE’s default versions. Import some objects from your existing Fedora repository and see if they display properly in searches as you like.

Strategy 2: Intermediate - Bind Mount in Existing Transforms and Schemas

Bind mount in existing transforms and schemas to override ISLE settings with your current Production version.

WARNING This approach assumes you are running Solr 4.10.x.; only attempt if you are running that version on Production.

  • Copy these current Production files and directory to your personal computer in an appropriate location.

    • Solr schema.xml
    • GSearch foxmltoSolr.xslt file
    • GSearch islandora_transforms
    • Keep the files you create during this process; you will need them again for Step 2a (below)!
  • Note: You may need to further review paths in the files mentioned above, and edit them to match ISLE system paths. i.e. If foxmltoSolr.xslt and any transforms within islandora_transforms include xsl:include statements, make sure they match the paths noted in Step 2a (i.e. /usr/local/tomcat/webapps/fedoragsearch/WEB-INF/classes/fgsconfigFinal/index/FgsIndex/islandora_transforms).

Strategy 3: Advanced - Diff and Merge Current Production Customization Edits Into ISLE Configs

I chose this approach, Strategy 3, just as I have in the past.

  • Copy these current production files and directory to your personal computer in an appropriate location.

    • Solr schema.xml
    • GSearch foxmltoSolr.xslt file
    • GSearch islandora_transforms
  • Run the Demo ISLE briefly to pull files for modification and correct ISLE system paths.

Since I already have “customized” copies of the files in question (see post 058 I executed this step in two parts so that I can identify any changes in the files since the last time I did this. Specifically, I loaded and pulled the files and directory listed below from both ISLE v1.5.1 and ISLE v1.3.0, the version that I used in my previous attempt. In each case, before spinning up the Demo ISLE instance I did git checkout ISLE-1.3.0 and git checkout master, the later was to create a v1.5.1 instance.

  • You can find these paths by running the Demo and copying these files out to an appropriate location.

    • docker cp isle-solr-ld:/usr/local/solr/collection1/conf/schema.xml schema.xml
    • docker cp isle-fedora-ld:/usr/local/tomcat/webapps/fedoragsearch/WEB-INF/classes/fgsconfigFinal/index/FgsIndex/foxmlToSolr.xslt foxmlToSolr.xslt
    • docker cp isle-fedora-ld:/usr/local/tomcat/webapps/fedoragsearch/WEB-INF/classes/fgsconfigFinal/index/FgsIndex/islandora_transforms islandora_transforms

Using the commands above, I pulled content from ISLE v1.5.1 and saved it in ~/Desktop/isle-demo-v1.5.1. The same content from ISLE v1.3.0 is saved in ~/Desktop/isle-demo-v1.3.0 for comparison.

  • Using a “diff” tool (software that allows one to compare and find the differences between two files), compare:

    • your Production Solr schema.xml file to the ISLE demo schema.xml file.
    • your Production GSearch foxmltoSolr.xslt file to the ISLE demo foxmltoSolr.xslt file.
    • your Production GSearch islandora_transforms directory to the ISLE demo islandora_transforms directory.

I subsequently used diff -bur ~/Desktop/isle-demo-v1.3.0 ~/Desktop/isle-demo-v1.5.1 to recursively report any differences between the two versions of files and directories. There were NONE.

  • Look for edits and comments that indicate specific customization and make note of the differences.

    • Merge in the customizations into the ISLE versions.
    • Keep the files you create during this merge process; you will need them again for Step 2a (below)!

Step 1: Choose a Project Name

Please choose a project name (concatenated, with no spaces) that describes your institution or your collection platform. You will substitute in your preferred project name whenever the documentation refers to “yourprojectnamehere”. (Be creative. Some real-life examples include: arminda, dhinitiative, digital, digitalcollections, digitallibrary, unbound, etc.)

As in past cases, I chose the very simple name dg.


Step 1.5: Edit “/etc/hosts” File

Enable the Local ISLE Installation to be viewed locally on a personal computer browser using “yourprojectnamehere” (e.g. “https://yourprojectnamehere.localdomain”).

Checked my /etc/hosts file and the necessary edits are in place. To protect that file from future updates to Docker, I changed the file’s permissions to 444, read-only!


Step 2: Setup Git Project Repositories

The prescribed private repositories, dg-isle and dg-islandora, were created long ago in blog posts 051 and 059. Adjust accordingly!

You will create two new, empty, private git repositories (if they do not already exist) within your git repository hosting service (e.g Github, Bitbucket, Gitlab). Below, we suggest a naming convention that will clearly distinguish your ISLE code from your Islandora code. It’s very important to understand that these are two separate code repositories, and not to confuse them.

  • Login to your git repository hosting service.
  • Create a new private repository for ISLE.
    • We suggest you name it: yourprojectnamehere-isle
    • (This git repository will hold your ISLE code and your environment-specific customizations. Storing this in a private repository and following the workflow below will save you a lot of time and confusion.)
  • Create a new private repository for Islandora Drupal.
    • We suggest you name it: yourprojectnamehere-islandora
    • (This git repository will hold your Islandora Drupal code and your site specific customizations. Storing this in a private repository and following the workflow below will save you a lot of time and confusion.)

Note: This documentation will walk you through using git on the command line.

You will open a terminal and use the command line to clone your newly created (and empty) yourprojectnamehere-isle repository from your git hosting service to create a local directory/copy on your personal computer:

  • Open a terminal (Windows: open Git Bash)

  • Use the “cd” command to navigate to a directory where you want to locate your new yourprojectnamehere-isle directory. (We recommend using the default user home directory. You may choose a different location, but it must not be a protected folder such as system or root directory.)

    • Example (Mac): cd ~
    • Example (Windows): cd /c/Users/somebody/
  • Clone your new yourprojectnamehere-isle repository to your personal computer:

    • Example: git clone https://yourgitproviderhere.com/yourinstitutionhere/yourprojectnamehere-isle.git
  • Note: It is OKAY if you see this warning message: “Warning: You appear to have cloned an empty repository.”

  • Navigate to the new directory created by the above clone operation:

    • Example: cd yourprojectnamehere-isle
  • Add the ICG ISLE git repository as a git upstream:

    • git remote add icg-upstream https://github.com/Islandora-Collaboration-Group/ISLE.git
  • View your connections to remote git repositories:

    • git remote -v
  • You should now see the following:

icg-upstream	https://github.com/Islandora-Collaboration-Group/ISLE.git (fetch)
icg-upstream	https://github.com/Islandora-Collaboration-Group/ISLE.git (push)
origin	https://yourgitproviderhere.com/yourinstitutionhere/yourprojectnamehere-isle.git (fetch)
origin	https://yourgitproviderhere.com/yourinstitutionhere/yourprojectnamehere-isle.git (push)
  • Run a “git fetch” from the icg-upstream repository:

    • git fetch icg-upstream
  • Pull down the ICG ISLE “master” branch into your yourprojectnamehere-isle local “master” branch:

    • git pull icg-upstream master
  • View the ISLE code you now have in this directory:

    • ls -lha
  • Push this code to your git hosting provider:

    • git push -u origin master
    • This will take 2-5 minutes depending on your internet speed.

You now have the current ISLE project code checked into git as a foundation to make changes on specific to your local and project needs. You’ll use this git “icg-upstream” process in the future to pull updates and new releases from the main ISLE project.


Step 2a: Add Customizations from “Step 0” to the Git Workflow

This step is intended for users who followed either the “Intermediate” or “Advanced” migration options in “Step 0” above. If you choose the Easy migration option you may safely skip Step 2a.

Navigate to your local yourprojectnamehere-isle directory:

  • cd /path/to/yourprojectnamehere-isle

Create new directories under “./config” to hold the Solr and GSearch files you retrieved in “Step 0”. Do the following::

mkdir -p ./config/solr
mkdir -p ./config/fedora/gsearch
  • Copy your “schema.xml” file from “Step 0” into the new “./config/solr/” directory.

  • Copy your “foxmltoSolr.xslt” file and “islandora_transforms” directory from “Step 0” into the “config/fedora/gsearch/” directory.

  • Add a new line in the Solr volumes section of your “docker-compose.local.yml”

  - config/solr/schema.xml:/usr/local/solr/collection1/conf/schema.xml`
  • Add new lines in the Fedora volumes section of your “docker-compose.local.yml”
  - ./config/fedora/gsearch/islandora_transforms:/usr/local/tomcat/webapps/fedoragsearch/WEB-INF/classes/fgsconfigFinal/index/FgsIndex/islandora_transforms
  - ./config/fedora/gsearch/foxmlToSolr.xslt:/usr/local/tomcat/webapps/fedoragsearch/WEB-INF/classes/fgsconfigFinal/index/FgsIndex/foxmlToSolr.xslt

Continue the local setup as directed below and ultimately import some objects from your existing Fedora repository and see if they display properly in searches as you like.

All prescribed “customizations” were previously incorporated into my dg-isle repository. Since no changes to the base files, see annotations above in Step 0 - Strategy 3, were detected, I will assume that my previous customizations remain valid.


Step 3: Git Clone the Production Islandora Drupal Site Code

This step assumes you have an existing Islandora Drupal site, like yourprojectnamehere-islandora, checked into a git repository. (If not, then you’ll need to check your Drupal site into a git repository following the same commands from Local ISLE Installation: New Site documentation. Your git repository should be initialized at the Drupal root.)

Note: If below you see a “fatal: Could not read from remote repository.” error, then please read Fatal: Could not read from remote repository.

Using the same open terminal:

  • Create a location outside of your /path/to/yourprojectnamehere-isle directory where your Islandora Drupal site code will be stored. While you may create this location anywhere, we suggest that you put it at the same level as your existing yourprojectnamehere-isle directory. From your /path/to/yourprojectnamehere-isle directory, go up one level:
    • cd /path/to/yourprojectnamehere-isle
    • cd ..
    • git clone https://yourgitproviderhere.com/yourinstitutionhere/yourprojectnamehere-islandora.git
    • Example: The above process created a folder named “yourprojectnamehere-islandora”

Attention: Digital.Grinnell’s dg-islandora repository contains numerous theme and module git submodules! It is therefore absolutely imperative that the aforementioned git clone... command be run with a --recursive option, like so:

Workstation Commands
cd ~/GitHub/
git clone https://github.com/Digital-Grinnell/dg-islandora.git --recursive
  • Now update the “docker-compose.local.yml” in the yourprojectnamehere-isle directory to create a bind-mount to the Islandora Drupal site code:
    • Search for “apache:”
    • Find the sub-section called “volumes:”
    • Find this line:
      • “- ./data/apache/html:/var/www/html:cached”
    • Edit the above line to be like this:
      • - ../yourprojectnamehere-islandora:/var/www/html:cached
  • Your Production Islandora site code is now configured to be used in this local setup.

Step 4: Edit the “.env” File to Change to the Local Environment

  • Navigate to your local yourprojectnamehere-isle directory.

  • Copy the sample.env to .env. By default, the Demo environment is setup. You will need to edit this file to match the correct environment. Please note that the .env is no longer tracked by git as of ISLE version 1.5. Instructions below involving git are for ISLE versions below 1.5. However the settings recommended below for the environment can still be followed as needed.

    • cp sample.env .env
  • Open the “.env” file in a text editor.

  • Change only the following lines in the “.env” file so that the resulting values look like the following: Please note: the following below is an example not actual values you should use. Use one word to describe your project and follow the conventions below accordingly

    • COMPOSE_PROJECT_NAME=yourprojectnamehere_local
    • BASE_DOMAIN=yourprojectnamehere.localdomain
    • CONTAINER_SHORT_ID=ld leave default setting of ld as is. Do not change.
    • COMPOSE_FILE=docker-compose.local.yml
  • Save and close the file.

  • Additionally, depending on your decision from “Step 0”, you may need to make additional edits to docker-compose.local.yml and move files into place as directed from the (Intermediate) and (Advanced) sections.

Note: We highly recommend that you also review the contents of the docker-compose.local.yml file as the Apache service volume section uses bind mounts for the intended Drupal Code instead of using default Docker volumes. This allows users to perform Local Islandora Drupal site development with an IDE. This line is a suggested path and users are free to change values to the left of the : to match their Apache data folder of choice. However we recommend starting out with the default setting below. Default: - ./data/apache/html:/var/www/html:cached

I checked for significant changes to sample.env (for .env) and docker-compose.local.yml between past versions and v1.5.1, and found NONE. So, I believe my previous changes to these files should still be valid.


Step 5: Create New Users and Passwords by Editing “local.env” File

You can reuse some of the older Production settings in the “local.env” if you like (e.g. the database name “DRUPAL_DB”, database user “DRUPAL_DB_USER” even the Drupal database user password “DRUPAL_DB_PASS” if that makes it easier). It is important to avoid repeating passwords in the ISLE Staging and Production environments.

  • Open the “local.env” file in a text editor.

    • Find each comment that begins with: # Replace this comment with a ... and follow the commented instructions to edit the passwords, database and user names.

      • Review carefully as some comments request that you replace with ...26 alpha-numeric characters while others request that you create an ...easy to read but short database name.

      • In many cases the username is already pre-populated. If it doesn’t have a comment directing you to change or add a value after the =, then don’t change it.

    • For Microsoft Windows:

      • Find the following line:
        • # COMPOSE_CONVERT_WINDOWS_PATHS=1
      • In the above line, delete the first two characters (# ) so as to uncomment the line. It should now look like this:
        • COMPOSE_CONVERT_WINDOWS_PATHS=1
    • Once finished, save and close the file.

  • Open the “config/apache/settings_php/settings.local.php” file in a text editor.

    • Find the first comment that begins with: # ISLE Configuration and follow the commented instructions to edit the database, username and password.
    • Find the second comment that begins with: # ISLE Configuration and follow the instructions to edit the Drupal hash salt.
    • Once finished, save and close the file.

As in previous sections, I checked for significant changes to local.env and config/apache/settings_php/settings.local.php between past versions and v1.5.1, and found NONE. So, I believe my previous changes to these files should still be valid.


Step 6: Create New Self-Signed Certs for Your Project

  • Open the appropriate file in a text editor:

    • For Mac/Ubuntu/CentOS/etc: “./scripts/proxy/ssl-certs/local.sh”
    • For Microsoft Windows: “./scripts/proxy/ssl-certs/local-windows-only.sh”
  • Follow the in-line instructions to add your project’s name to the appropriate areas.

    • Once finished, save and close the file.
  • Using the same open terminal:, navigate to “/path/to/yourprojectnamehere-isle/scripts/proxy/ssl-certs/”

    • cd ./scripts/proxy/ssl-certs/
  • Change the permissions on the script to make it executable

    • For Mac/Ubuntu/CentOS/etc: chmod +x local.sh
    • For Microsoft Windows: chmod +x local-windows-only.sh
  • Run the following command to generate new self-signed SSL keys using your “yourprojectnamehere.localdomain” domain. This now secures the local site.

    • For Mac/Ubuntu/CentOS/etc: ./local.sh
    • For Microsoft Windows: ./local-windows-only.sh
    • The generated keys can now be found in:
      • cd ../../../config/proxy/ssl-certs
  • Add the SSL .pem and .key file names generated from running the above script to the “./config/proxy/traefik.local.toml” file.

    • cd ..
    • Open traefik.local.toml in a text editor.
    • Example:
      • certFile = "/certs/yourprojectnamehere.localdomain.pem"
      • keyFile = "/certs/yourprojectnamehere.localdomain.key"

As in previous sections, I checked for significant changes to the files involved in this section between past versions and v1.5.1, and found NONE. So, I believe my previous changes to these files should still be valid.


Step 7: Download the ISLE Images

  • Download all of the latest ISLE Docker images (~6 GB of data may take 5-10 minutes):
  • Using the same open terminal:
    • Navigate to the root of your local yourprojectnamehere-isle directory:
      • cd ~/path/to/yourprojectnamehere-isle
    • docker-compose pull

I followed the instructions in this section to-the-letter. Specifically…

Workstation Commands
cd ~/GitHub/dg-isle
docker-compose pull

Step 8: Launch Process

  • Using the same open terminal:

    • docker-compose up -d
  • Please wait a few moments for the stack to fully come up. Approximately 3-5 minutes.

  • Using the same open terminal:

    • View only the running containers: docker ps
    • View all containers (both those running and stopped): docker ps -a
    • All containers prefixed with “isle-” are expected to have a “STATUS” of “Up” (for x time).

I followed the instructions in this section to-the-letter. Specifically…

Workstation Commands
cd ~/GitHub/dg-isle
docker-compose up -d

Step 9: Import the Production MySQL Drupal Database

Method A: Use a MySQL client with a GUI

  • Configure the client with the following:
    • Host = 127.0.0.1
    • Port: 3306 or a different port if you changed it
    • Username: root
    • Password: YOUR_MYSQL_ROOT_PASSWORD in the “local.env”)
  • Select the Drupal database “DRUPAL_DB” in the “local.env”)
  • Click File > Import (or equivalent)
  • Select your exported Production Islandora Drupal database file (e.g. “prod_drupal_site_082019.sql.gz”)
  • The import process will take 1 -3 minutes depending on the size.

Method B: Use the command line

  • Copy the Production Islandora Drupal database file (e.g. “prod_drupal_site_082019.sql.gz”) to your ISLE MySQL container

    • Run docker ps to determine the mysql container name
    • docker cp /pathto/prod_drupal_site_082019.sql.gz your-mysql-containername:/prod_drupal_site_082019.sql.gz
    • Example:
      • docker cp /c/db_backups/prod_drupal_site_082019.sql.gz isle-mysql-ld:/prod_drupal_site_082019.sql.gz
    • This might take a few minutes depending on the size of the file.
  • Shell into the mysql container by copying and pasting the appropriate command:

    • For Mac/Ubuntu/CentOS/etc: docker exec -it your-mysql-containername bash
    • For Microsoft Windows: winpty docker exec -it your-mysql-containername bash
  • Import the Production Islandora Drupal database. Replace the “DRUPAL_DB_USER” and “DRUPAL_DB” in the command below with the values found in your “local.env” file.

    • mysql -u DRUPAL_DB_USER -p DRUPAL_DB < prod_drupal_site_082019.sql.gz
  • This might take a few minutes depending on the size of the file.

  • Type exit to exit the container

I chose Method B and used the following commands to complete this step:

Workstation Commands
docker cp /Users/markmcfate/Desktop/migration-copy/prod_drupal_site_083120.sql isle-mysql-ld:/prod_drupal_site_083120.sql
docker exec -it isle-mysql-ld bash
isle-mysql-ld Container Commands
mysql -u admin -p digital_grinnell < prod_drupal_site_083120.sql

Once I completed this entire process, as documented, I was left wondering what to do with the backup copy of my production /var/www/html/sites/default/files directory that I created back in Step 0? After posting a question to the isle-support Slack channel about this, I agreed that the handling of that backup directory should be covered here, and I opened an issue #388 in GitHub to deal with the documentation. The command sequence I used is documented here.

Workstation Commands
docker cp /Users/markmcfate/Desktop/migration-copy/var/www/html/sites/default/files/. isle-apache-ld:/var/www/html/sites/default/files/

Since I introduced and executed this annotation after completing the entire process, I found it necessary to repeat a portion of the migration_site_vsets.sh script introduced later in the document. I did this working in the Apache container, like so:

isle-apache-ld Container Commands
/bin/bash /utility-scripts/isle_drupal_build_tools/drupal/fix-permissions.sh --drupal_path=/var/www/html --drupal_user=islandora --httpd_group=www-data
cd /var/www/html/sites/default
drush cc all

Step 10: Run Islandora Drupal Site Scripts

migration_site_vsets.sh: updates Drupal database settings

This step will show you how to run the “migration_site_vsets.sh” script on the Apache container to change Drupal database site settings for ISLE connectivity.

Using the same open terminal:

  • Run docker ps to determine the apache container name
  • Copy the “migration_site_vsets.sh” to the root of the Drupal directory on your Apache container
    • docker cp scripts/apache/migration_site_vsets.sh your-apache-containername:/var/www/html/migration_site_vsets.sh
  • Change the permissions on the script to make it executable
    • For Mac/Ubuntu/CentOS/etc: docker exec -it your-apache-containername bash -c "chmod +x /var/www/html/migration_site_vsets.sh"
    • For Microsoft Windows: winpty docker exec -it your-apache-containername bash -c "chmod +x /var/www/html/migration_site_vsets.sh"
  • Run the script
    • For Mac/Ubuntu/CentOS/etc: docker exec -it your-apache-containername bash -c "cd /var/www/html && ./migration_site_vsets.sh"
    • For Microsoft Windows: winpty docker exec -it your-apache-containername bash -c "cd /var/www/html && ./migration_site_vsets.sh"

Before running the prescribed scripts for this step, I executed the following commands to run a script intended to eliminate some unnecessary warnings:

isle-apache-ld Container Commands
cd /var/www/html
source Digital-Grinnell-Migration-Mitigation-Script.sh

Final output of the Digital-Grinnell-Migration-Mitigation-Script.sh script was:

The following module is missing from the file system: <em class="placeholder">antibot</em>. For information about   [warning]
how to fix this, see <a href="https://www.drupal.org/node/2487215">the documentation page</a>. bootstrap.inc:1156
The following module is missing from the file system: <em class="placeholder">islandora_mods_via_twig</em>. For     [warning]
information about how to fix this, see <a href="https://www.drupal.org/node/2487215">the documentation page</a>.
bootstrap.inc:1156
'all' cache was cleared.

Attention: If the output of the script above yields warnings about missing module dg7, and other islandora_... modules, then you probably forgot to clone the dg-islandora project using the --recursive option! If that is the case you should return to [Step 3](#step-3-git-clone-the-production- islandora-drupal-site-code) and take note of the important annotation there.

Next, I ran the following commands to complete this portion of Step 10:

Workstation Commands
docker cp scripts/apache/migration_site_vsets.sh isle-apache-ld:/var/www/html/migration_site_vsets.sh
docker exec -w /var/www/html isle-apache-ld chmod +x migration_site_vsets.sh
time docker exec -w /var/www/html isle-apache-ld ./migration_site_vsets.sh

The abridged output of the script is included below.

Drush vset of ISLE specific configurations
The following module is missing from the file system: <em              [warning]
class="placeholder">antibot</em>. For information about how to fix
this, see <a href="https://www.drupal.org/node/2487215">the
documentation page</a>. bootstrap.inc:1156
The following module is missing from the file system: <em              [warning]
class="placeholder">islandora_mods_via_twig</em>. For information
about how to fix this, see <a
href="https://www.drupal.org/node/2487215">the documentation
page</a>. bootstrap.inc:1156

The two warnings shown above were repeated many times in the original output, but all subsequent instances have been removed from the abridged version shown below. No other changes were made to this output.

islandora_base_url was set to "fedora:8080/fedora".                    [success]
islandora_solr_url was set to "solr:8080/solr".                        [success]
imagemagick_convert was set to "/usr/local/bin/convert".               [success]
image_toolkit was set to "imagemagick".                                [success]
islandora_ocr_tesseract was set to "/usr/bin/tesseract".               [success]
islandora_batch_java was set to "/usr/bin/java".                       [success]
islandora_lame_url was set to "/usr/bin/lame".                         [success]
islandora_paged_content_gs was set to "/usr/bin/gs".                   [success]
islandora_video_ffmpeg_path was set to "/usr/bin/ffmpeg".              [success]
islandora_video_ffmpeg2theora_path was set to                          [success]
"/usr/bin/ffmpeg2theora".
islandora_use_kakadu was set to FALSE.                                 [success]
islandora_kakadu_url was set to "/usr/local/bin/kdu_compress".         [success]
islandora_pdf_path_to_pdftotext was set to "/usr/bin/pdftotext".       [success]
islandora_fits_executable_path was set to "/usr/local/bin/fits".       [success]
islandora_openseadragon_iiif_identifier was set to                     [success]
"[islandora_openseadragon:pid]~[islandora_openseadragon:dsid]~[islandora_openseadragon:token]".
islandora_openseadragon_iiif_token_header was set to 0.                [success]
islandora_openseadragon_iiif_url was set to "iiif/2".                  [success]
islandora_openseadragon_tilesource was set to "iiif".                  [success]
islandora_internet_archive_bookreader_iiif_identifier was set to       [success]
"[islandora_iareader:pid]~[islandora_iareader:dsid]~[islandora_iareader:token]".
islandora_internet_archive_bookreader_iiif_token_header was set to 0.  [success]
islandora_internet_archive_bookreader_iiif_url was set to "iiif/2".    [success]
islandora_internet_archive_bookreader_pagesource was set to "iiif".    [success]
"anonymous user" already has the permission "view fedora repository         [ok]
objects"
Running fix-permissions script
Changing ownership of all contents of /var/www/html:
 user => islandora 	 group => www-data
Changing permissions of all directories inside /var/www/html to rwxr-x---...
Changing permissions of all files inside /var/www/html to rw-r-----...
Changing permissions of files directories in /var/www/html/sites to rwxrwx---...
Changing permissions of all files inside all files directories in /var/www/html/sites to rw-rw----...
Changing permissions of all directories inside all files directories in /var/www/html/sites to rwxrwx---...
find: './*/files': No such file or directory
find: './*/files': No such file or directory
Done setting proper permissions on files and directories
Configuring cron job to run every 3 hours
Running Drupal Cron first time and clearing Drupal Caches.
WD smtp: phpmailerException: SMTP Error: Could not connect to SMTP       [error]
host. in PHPMailer->SmtpConnect() (line 810 of
/var/www/html/sites/all/modules/contrib/smtp/smtp.phpmailer.inc).
WD smtp: Error sending e-mail from digital@grinnell.edu to               [error]
digital@grinnell.edu : SMTP Error: Could not connect to SMTP host.
WD mail: Error sending e-mail (from digital@grinnell.edu to              [error]
digital@grinnell.edu).
Cron run successful.                                                   [success]
Unable to send e-mail. Contact the site administrator if the problem     [error]
persists.
Drush script finished! ...exiting
docker exec -w /var/www/html isle-apache-ld ./migration_site_vsets.sh  0.05s user 0.04s system 0% cpu 7:59.50 total

Note: In the above output the two lines that read find: './*/files': No such file or directory were present because our production backup copy of /var/www/html/sites/defaults/files had not been restored. Completion of that missing portion of Step 9 should resolve/remove those warnings.

install_solution_packs.sh: installs Islandora solution packs

Since you’ve imported an existing Drupal database, you must now reinstall the Islandora solution packs so the Fedora repository will be ready to ingest objects.

  • Copy the “install_solution_packs.sh” to the root of the Drupal directory on your Apache container
    • docker cp scripts/apache/install_solution_packs.sh your-apache-containername:/var/www/html/install_solution_packs.sh
  • Change the permissions on the script to make it executable
    • For Mac/Ubuntu/CentOS/etc: docker exec -it your-apache-containername bash -c "chmod +x /var/www/html/install_solution_packs.sh"
    • For Microsoft Windows: winpty docker exec -it your-apache-containername bash -c "chmod +x /var/www/html/install_solution_packs.sh"
  • Run the script
    • For Mac/Ubuntu/CentOS/etc: docker exec -it your-apache-containername bash -c "cd /var/www/html && ./install_solution_packs.sh"
    • For Microsoft Windows: winpty docker exec -it your-apache-containername bash -c "cd /var/www/html && ./install_solution_packs.sh"
  • The above process will take a few minutes depending on the speed of your local and Internet connection.
    • You should see a lot of green [ok] messages.
    • If the script appears to pause or prompt for “y/n”, DO NOT enter any values; the script will automatically answer for you.
For Microsoft Windows:
You may be prompted by Windows to:
- Share the C drive with Docker. Click Okay or Allow.
- Enter your username and password. Do this.
- Allow vpnkit.exe to communicate with the network. Click Okay or Allow (accept default selection).
- If the process seems to halt, check the taskbar for background windows.
  • Proceed only after this message appears: “Done. ‘all’ cache was cleared.”

I ran the following commands to complete this portion of Step 10:

Workstation Commands
docker cp scripts/apache/install_solution_packs.sh isle-apache-ld:/var/www/html/install_solution_packs.sh
docker exec -w /var/www/html isle-apache-ld chmod +x install_solution_packs.sh
time docker exec -w /var/www/html isle-apache-ld ./install_solution_packs.sh

The two aforementioned warnings were repeated several times, but have once again been removed from the abridged output for clarity. The abridged output is:

Installing all Islandora modules
Resinstalling the Islandora module with Solution Packs
islandora: Successfully reinstalled. Top-level Collection.              [status]
Replaced islandora:sp-audioCModel - Islandora Audio Content Model
Replaced islandora:collectionCModel - Islandora Collection Content Model
Replaced islandora:sp_basic_image - Islandora Basic Image Content Model
Replaced islandora:pageCModel - Islandora Page Content Model
Replaced islandora:bookCModel - Islandora Internet Archive Book Content Model
Replaced islandora:compoundCModel - Islandora Compound Object Content Model
Replaced islandora:sp_large_image_cmodel - Islandora Large Image Content Model
Replaced islandora:sp_pdf - Islandora PDF Content Model
Replaced islandora:sp_videoCModel - Islandora Video Content Model
Drush script finished! ...exiting
docker exec -w /var/www/html isle-apache-ld ./install_solution_packs.sh  0.03s user 0.02s system 0% cpu 4:31.81 total

Step 11: Test the Site

  • In your web browser, enter this URL: https://yourprojectnamehere.localdomain

I visited https://dg.localdomain on my iMac desktop as instructed. The site comes up with the appropriate theme apparently enabled and working. The two aforementioned warnings are present in a different format than before (this is a web/html response rather than command-line output), but no other warnings or errors are present!

  • Note: You may see an SSL error warning that the site is unsafe. It is safe, it simply uses “self-signed” SSL certs. Ignore the error and proceed to the site.

  • Log in to the local Islandora site with the credentials (“DRUPAL_ADMIN_USER” and “DRUPAL_ADMIN_PASS”) you created in “local.env”.

    • You can also attempt to use login credentials that the Production server would have stored in its database.

In order to attempt to login I explicitly visited https://dg.localdomain/user/login. Unfortunately, neither the old nor new credentials worked, so I followed the additional steps below to add the new user to the Apache container.

  • If the newly created Drupal login doesn’t work then, you’ll need to Shell into the Apache container:

    • For Mac/Ubuntu/CentOS/etc: docker exec -it your-apache-containername bash
    • For Microsoft Windows: winpty docker exec -it your-apache-containername bash
  • Navigate to this directory

    • cd /var/www/html
  • Create the user found in “DRUPAL_ADMIN_USER” and set its password to the value of “DRUPAL_ADMIN_PASS” as you previously created in “local.env”.

    • In the example below swap-out “DRUPAL_ADMIN_USER” and “DRUPAL_ADMIN_PASS” with those found in “local.env”.

    • drush user-create DRUPAL_ADMIN_USER --mail="youremailaddresshere" --password="DRUPAL_ADMIN_PASS";

    • drush user-add-role "administrator" DRUPAL_ADMIN_USER

  • Type exit to exit the container

On my workstation I executed the following docker exec... commands

Workstation Commands
docker exec -w /var/www/html isle-apache-ld drush user-create admin --mail="mark.mcfate@icloud.com" --password="**obfuscated**"
docker exec -w /var/www/html isle-apache-ld drush user-add-role "Administrator" admin

Note the changes above:

  • In my case, the prefered email address digital@grinnell.edu is already assigned to a user, and
  • There is no “administrator” role, only “Administrator”, with a capital “A”.

With corresponding changes the commands appear to have worked with output as follows:

User ID       :  1119378
User name     :  admin
User mail     :  mark.mcfate@icloud.com
User roles    :  authenticated user
User status   :  active

Added role Administrator role to admin
  • Attempt to login again

I did as instructed and this time the admin login was accepted. The output included both of the aforementioned warnings, but no additional issues were present.


Please refer to post 090 for details of the customizations I implemented to complete the process of migrating to a new local instance of ISLE, one that looks and behaves exactly like Digital.Grinnell.

Step 12: Ingest Sample Objects

Since my new local instance of ISLE includes the use of my DG-FEDORA portable (USB stick) repository, there was no need for me to execute the steps outlined in this section. Instead, I followed the update guidance provided in DG-FEDORA: A Portable FEDORA Repository.

After following the aforementioned blog post my repository containing more than 120 objects was visible, as expected.

Digital.Grinnell’s home page “view” is somewhat complex and requires some attention before it will function properly. Guidance to update/configure the dg7 Collection View is provided in Updating DG’s Collection Views and I followed that guidance to ensure that our new local ISLE instance was behaving properly.

Following this critical update I’m pleased to report that https://dg.localdomain appears to be working perfectly!

It is recommended that end users migrating their sites opt to either import sample objects from their non-ISLE Production Fedora servers or use the following below:

The Islandora Collaboration Group provides a set of Islandora Sample Objects with corresponding metadata for testing Islandora’s ingest process. These sample objects are organized by solution pack and are zipped for faster bulk ingestion.

  • To download these sample objects, clone them to your computer’s desktop:
git clone https://github.com/Islandora-Collaboration-Group/islandora-sample-objects.git
  • Follow these ingestion instructions How to Add an Item to a Digital Collection

  • (Note: Getting Started with Islandora contains explanations about content models, collections, and datastreams.)

  • After ingesting content, you may need to add an Islandora Simple Search block to the Drupal structure. (The default search box will only search Drupal content, not Islandora content.) This might already exist in your current Drupal Production site as a feature.

    • Select from the menu: Structure > Blocks > Islandora Simple Search

    • Select: Sidebar Second

    • Click: Save Blocks at bottom of page

    • You may now search for ingested objects that have been indexed by SOLR

  • After ingesting either the ICG sample objects or a selection of your pre-existing Fedora Production objects, continue to QC the migrated site, ensuring that objects display properly, the theme and design continue to work properly, there are no errors in the Drupal watchdog and everything matches the functionality of the previous non-ISLE Production Islandora Drupal site.


Next Steps

Once you are ready to deploy your finished Drupal site, you may progress to:


Additional Resources


End of Local ISLE Installation: Migrate Existing Islandora Site