Building ISLE 1.3.0 (ld) for Local Development
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.
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:
git clone https://github.com/DigitalGrinnell/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*|
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…
╭─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#
docker exec -it isle-apache-ld bash
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:
Then I cloned the empty https://github.com/Digital-Grinnell/dg-isle to ma7053 and made the prescribed additions like so:
git clone https://github.com/Digital-Grinnell/dg-isle
git remote add icg-upstream https://github.com/Islandora-Collaboration-Group/ISLE.git
git remote -v
git fetch icg-upstream
git pull icg-upstream master
git push -u origin master
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:
|All site, user, and database names||local|
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:
time docker-compose pull
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!
time docker-compose up -d;
docker ps -a
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:
time docker exec -it isle-apache-ld bash -c “cd /utility-scripts/isle_drupal_build_tools && ./isle_islandora_installer.sh”
Note the addition of the
time command out front; that was put there to record how long this process takes. My
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:
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…
git checkout master
git add .
git commit -m “Created new dg.localdomain site”
git remote add origin https://github.com/Digital-Grinnell/dg-islandora.git
git push -u origin master
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:
git checkout -b local-with-dg-fedora
git add .env docker-compose.DG-FEDORA.yml
git commit -m “Added DG-FEDORA to dg.localdomain site”
git push -u origin local-with-dg-fedora
I hope that was the right thing to do, because I just did it. ❗
And that’s a wrap. Until next time…