Template for building and customizing your institution's Islandora installation, for use as both a development and production environment for your institution.
After confirming that assumptions match your use case, and you have the appropriate requirements , follow the instructions to set up your institution's Islandora installation from this template.
N.B. This is the not the only way to manage your Islandora installation, please also see isle-dc and islandora-playbook, and consult with the wider community on the Islandora Slack.
This is not intended to be an upstream fork that your institution will be pulling changes from. Instead this repository acts as a template. The intention is to make a new Git repository from it by copying the contents of this repository into your institution's Git repository, for which your institution will then be responsible.
This is for a few reasons. Primarily, we can't guarantee forward compatibility with the changes made by your institution to a fork of this Git repository. Your institution must be responsible for it's own configuration, as changes to configuration cannot easily be shared across Drupal sites.
This template assumes you'll be running your site in Docker on a single server. If that is not your intention you may want to ask in the Islandora Slack about existing examples for your chosen infrastructure.
This template is set up for a single site installation and isn't configured for a Drupal multisite. It is possible to add the functionality for that later, but it is left to the implementer to do those additional changes.
While Islandora can be setup to use a wide variety of databases, tools and configurations this template is set up for the following.
blazegraph
is included by default.crayfish
services are included by default.fcrepo
is included by default.fits
is included by default.mariadb
is used for the backend database (rather thanpostgresql
).solr
is included by default.- etc.
N.B. Although alternate components and configurations are supported by Islandora, for simplicities sake the most common use-case is shown. For example
mariadb
is used rather thanpostgresql
.
See the customizations steps afterwards about removing unwanted features.
- Docker 24.0+ Referring to the Docker Engine version, not Docker Desktop.
- Docker Compose Already included in OSX with Docker
- mkcert 1.4+
cURL
andgit
mkcert seems to have problems when running on Java installed via Homebrew. This is resolved by installing OpenJDK from an installer such as temurin from the Eclipse foundation.
Be sure to set the JAVA_HOME environment variable to the correct value, for version 20 of the temurin packaged installer linked above it is:
/Library/Java/JavaVirtualMachines/temurin-20.jdk/Contents/Home
After installing the requirements, run the following command for an automated setup. It is roughly equivalent to the Manual Setup.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Islandora-Devops/isle-site-template/main/setup.sh)"
You should now have a folder with the SITE_NAME
you provided to the above
script with the basics completed for you.
On your platform of choice (GitHub, GitLab, etc), create a new Git repository for your new site. This step allows you to persist your customizations to this repository. It is not necessary for a throwaway development instance.
In the following sections the GitHub, GitLab, etc; organization will be
referred to as INSTITUTION
, and the Git repository will be referred to as
SITE_NAME
.
Push the automatically generated repository to your remote (For example with GitHub):
cd SITE-NAME
git remote add origin git@github.com:INSTITUTION/SITE-NAME.git
git push
You can now continue on to customizations.
On your platform of choice GitHub, GitLab, etc. Create a new Git repository for your new site. Having these files in Git will make future steps possible.
In the following sections the GitHub, GitLab, etc; organization will be
referred to as INSTITUTION
, and the Git repository will be referred to as
SITE_NAME
.
- Clone a copy locally (For example with GitHub):
git clone git@github.com:INSTITUTION/SITE-NAME.git
cd SITE-NAME
At this point it should be an empty folder.
- Unpack this repository into that empty folder, using the
main
branch (or the latest release, if you alter what comes afterrefs
).
curl -L https://github.com/Islandora-Devops/isle-site-template/archive/refs/heads/main.tar.gz | tar -xz --strip-components=1
- Remove .github folder and setup.sh
rm -fr .github setup.sh
- Create the first commit:
git add .
git commit -am "First commit, added isle-site-template."
- Push your changes to your institution's repository:
git push
Just as this repository is not intended to be an upstream fork, neither is the islandora-starter-site. It is a starting point from which your institution will customize and manage Drupal for your Islandora installation.
- Unpack the islandora-starter-site using the
main
branch (or the latest release, if you alter what comes afterrefs
). Run this command from the root of your repository.
curl -L https://github.com/Islandora-Devops/islandora-starter-site/archive/refs/heads/main.tar.gz \
| tar --strip-components=1 -C drupal/rootfs/var/www/drupal -xz
This will place the contents in drupal/rootfs/var/www/drupal.
- Remove unneeded files (from the root of your repository):
rm -fr \
drupal/rootfs/var/www/drupal/.github
- Revert the content of drupal/rootfs/var/www/drupal/assets/patches/default_settings.txt to what was originally there.
git checkout drupal/rootfs/var/www/drupal/assets/patches/default_settings.txt
- Create the second commit:
git add .
git commit -am "Second commit, added islandora-starter-site."
- Push your changes to your institution's repository:
git push
- For a development server, generate certs and secrets.
./generate-certs.sh
./generate-secrets.sh
Continue on to Customizations.
The previous sections will have set you up with a Git repository to start from, but more customization is likely needed.
Read through each following sections and follow the steps if you deem them applicable to your institution's situation.
Edit .env and replace the following line with a name derived from your site name. If you have multiple sites on the same host, these must be unique.
COMPOSE_PROJECT_NAME=isle-site-template
ISLANDORA_TAG
tells Docker what version of Isle Buildkit
to use for the images. You should set this to the most
recent release number,
unless you have a reason to use older images.
Warning
You should not use ISLANDORA_TAG=main
in production.
If setting up your own images on a remote Docker image registry like DockerHub, set the following line to your use your image registry:
# The Docker image repository, to push/pull custom images from.
# islandora.io redirects to localhost.
REPOSITORY=islandora.io
If using a purchased a domain name for your production site, set the following line to your new domain:
# The domain at which your production site is hosted.
DOMAIN=islandora.dev
Lastly update the default email to that of your site's administrator:
# The email to use for admin users and Lets Encrypt.
EMAIL=postmaster@example.com
N.B. This is required to property generate certificates automatically!
Since this README.md
is meant as a guide for creating your institution's
Islandora installation, it is not useful after that point. Instead a template
README.template.md is provided from which you can then
customize. This template includes instructions on how to build and start up your
containers, as well as how to customize your Islandora installation. Please read
it after completing the steps in this README.md
.
- Replace this README.md with the template:
mv README.template.md README.md
- Customize the README.md:
Replace instances of INSTITUTION
and SITE-NAME
with appropriate values and
add any additional information you see fit.
- Commit your changes:
git commit -am "Replaced README.md from provided template."
- Push your changes to your institution's repository:
git push
Follow the rest of the instructions for setting up Islandora in README.md (formerly README.template.md).