This post, an updated (the original was written in August 2019 for ISLE-1.2.0) follow-up to a previous post is intended to chronicle my efforts to build a new ~ISLE v1.2.0~ ISLE-1.3.0, ld, or local development, instance of Digital.Grinnell on my work-issued MacBook, ma7053.

Goal Statement

The goal of this project is to spin up a pristine, local Islandora stack using an updated fork of the ISLE project at https://github.com/Digital-Grinnell/dg-isle, then 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.

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 like this.

• 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:

• 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:

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…

╭─markmcfate@ma7053 ~/Projects/dg-isle ‹ruby-2.3.0› ‹ld*›
╰─$ docker exec -it isle-apache-ld bash
root@9bec4edd3964:/# cd /var/www/html
root@9bec4edd3964:/var/www/html#

Installing per install-local-new.md

This is first-and-foremost a local development copy of ISLE, but with considerable Digital.Grinnell customization, so I’m following the process outlined in the project’s ./docs/install/install-local-new.md. References to Step X that follow refer to corresponding sections of install-local-new.md. Each section or “Step” listed below is also a link back to the corresponding section of the canonical document.

Step 1: Choose a Project Name

I choose a very short and simple name, dg, as my value for yourprojectnamehere.

Step 1.5: Edit “/etc/hosts” File

In this step I found it necessary to be very diligent about editing my /etc/hosts file, even though I’ve done this a thousand times (and that’s not exaggerated). Why? Because every time I update Docker Desktop for Mac, the hideous thing adds a new 127.0.0.1 entry to the bottom of my /etc/hosts file, effectively overriding my own additions.

The critical line in /etc/hosts now reads:

127.0.0.1    localhost dg.localdomain admin.dg.localdomain images.dg.localdomain portainer.dg.localdomain

And there’s no comment, and no active 127.0.0.1... lines later in the file!

Step 2: Setup Git Project Repositories

Since I choose dg as my value for yourprojectnamehere, and since this step calls for creation of two private repos, I logged in to Github as “Digital-Grinnell” and created:

• https://github.com/Digital-Grinnell/dg-isle
• https://github.com/Digital-Grinnell/dg-islandora

Then I cloned the empty https://github.com/Digital-Grinnell/dg-isle to ma7053 and made the prescribed additions like so:

The final command in that sequence simply opened a copy of the local dg-isle project files in my Atom editor.

Step 3: Edit the “.env” File to Point to the Local Environment

Since this is a short-lived, local, development project, I have no reservations about sharing this with you. So, as instructed I modified .env to read as follows:

#### Activated ISLE environment
# To use an environment other than the default Demo, please change values below
# from the default Demo to one of the following: Local, Test, Staging or Production
# For more information, consult https://islandora-collaboration-group.github.io/ISLE/install/install-environments/

COMPOSE_PROJECT_NAME=dg_local
BASE_DOMAIN=dg.localdomain
CONTAINER_SHORT_ID=ld
COMPOSE_FILE=docker-compose.local.yml

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

No secrets here either… Since this is a local instance of ISLE, I set the following:

Also note that I kept all of the original # Replace this… comments by pushing them to the line below. A copy of my customized local.env file can be found in this gist.

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

As before, no secrets here, so there’s a copy of my customized local.sh file in this gist and my traefik.local.toml file in this gist.

Certs were generated as prescribed. All is well.

Step 6: Download the ISLE Images

Only comment here is that you must navigate to your project folder, like cd ~/Projects/dg-isle, before you do docker-compose pull. The command will not work properly in any other directory!

I used the command time docker-compose pull so:

And my download time was: docker-compose pull 3.95s user 0.89s system 2% cpu 3:21.16 total.

Step 7: Launch Process

Same comment here as above, you must navigate to your project folder, like cd ~/Projects/dg-isle, before you do docker-compose up -d. The command will not work properly in any other directory!

And my launch time was: docker-compose up -d 1.45s user 0.34s system 14% cpu 12.546 total. Elapsed time was, of course, on the order of 6 minutes.

Step 8: Run Islandora Drupal Site Install Script

Ok, fingers crossed for good luck. ✌️ I left docker-compose.local.yml just as it was, right out of the box, and did almost as instructed:

Note the addition of the time command out front; that was put there to record how long this process takes. My time... results: docker exec -it isle-apache-ld bash -c 0.21s user 0.15s system 0% cpu 31:07.34 total.

Step 9: Test the Site

Woot! It works! ✨👍✨ No funky errors this time.

For the record (remember, no secrets here) my admin username and password for the site are: local and password. Pretty sneaky, eh? And the address is https://dg.localdomain.

Step 10: Ingest Sample Objects

OK, so this is where I generally depart from the “script”, because I’m lazy, and I already have a portable Fedora repository to test from. So, my process in this step follows what I wrote more than a month ago, 046 DG-FEDORA: A Portable Object Repository.

Next, I added the Islandora Simple Search block as instructed in Step 10: Ingest Sample Objects, and ran some search tests. ☑️ It works!

Step 11: Check-In the Newly Created Islandora Drupal Site Code Into Your Git Repository

OK, I have to admit this “step” was confusing at first, but it works and seems to make sense now that I’ve completed it. I’ll spare you the output details, because there was a LOT of it, but here is the exact command sequence I used…

Something Missing Here?

Step 11 is essentially the end of the install-local-new.md process, but it left me with a local ISLE project directory, namely ~/Projects/dg-isle, with the following Git status and remotes…

╭─markmcfate@ma7053 ~/Projects/dg-isle ‹ruby-2.3.0› ‹master*›
╰─$ git status; git remote -v
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   .env
	modified:   config/apache/settings_php/settings.local.php
	modified:   config/proxy/traefik.local.toml
	modified:   local.env
	modified:   scripts/proxy/ssl-certs/local.sh

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	config/proxy/ssl-certs/dg.localdomain.key
	config/proxy/ssl-certs/dg.localdomain.pem
	docker-compose.DG-FEDORA.yml

no changes added to commit (use "git add" and/or "git commit -a")
icg-upstream	https://github.com/Islandora-Collaboration-Group/ISLE.git (fetch)
icg-upstream	https://github.com/Islandora-Collaboration-Group/ISLE.git (push)
origin	https://github.com/Digital-Grinnell/dg-isle (fetch)
origin	https://github.com/Digital-Grinnell/dg-isle (push)

Since this is a local ISLE with no secrets, it seems prudent to add, commit, and push at least my “off-script” additions, .env and docker-compose.DG-FEDORA.yml. To safeguard against making a bad move I’m going to approach this like so:

I hope that was the right thing to do, because I just did it. ❗

And that’s a wrap. Until next time…