The Islandora Playbook (Islandora-Devops/islandora-playbook) is a tool for installing Islandora Defaults on a single virtual machine. It can be used both as a Vagrant project to create a local development environment, and/or as an Ansible playbook which can provision a remote server.
This repository has two active branches. The main branch's playbook will install the latest release of Islandora and its components. The dev branch, when configured to use Ansible, will provision with the most recent code of Islandora and its components.
The fastest way to spin up a local Vagrant version of Islandora Defaults is to use the Islandora Base Box, which is a packaged VM of the latest release of Islandora - including Islandora Defaults and all components. This is the default behaviour of the dev branch of the playbook. This method requires Vagrant and VirtualBox, but does not use Ansible.
$ git clone -b dev https://github.com/Islandora-Devops/islandora-playbook $ cd islandora-playbook $ vagrant up
This method results in an installation that does not contain the latest code changes.
Download and install the following. VirtualBox and Vagrant are needed if creating local VMs. Ansible is only necessary if provisioning (not using quick-start mode described above):
- Virtual Box
- Vagrant (version 2.0 or higher required)
- Ansible (up to, and not past, 2.8.7)
Installing Git, OpenSSL, and Ansible on Ubuntu/Debian¶
Git and OpenSSL are available via
apt. Ansible up to version 2.8.7. This is done best with
pip, the python package manager:
# Install git and openssl $ sudo apt-get install git $ sudo apt-get install openssl # If pip isn’t already available, run the following commands to install it $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py $ python get-pip.py --user # Install ansible $ pip install --user -Iv ansible==2.8.7
Installing Git, OpenSSL and Ansible on CentOS¶
Git and OpenSSL are available via
yum. Most everything else can be installed in the same way.
$ sudo yum install git $ sudo yum install openssl # If pip isn’t already available, run the following commands to install it $ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py $ python get-pip.py --user # Install ansible $ pip install --user -Iv ansible==2.8.7
Installing Git and Ansible on MacOS¶
OpenSSL is already pre-installed on MacOS. Git can be installed using XCode's command line tools (see below). Python and Pip should be installed via the downloaded installer direct from the site (not shown below). For the installation of Ansible, consider using homebrew (see below).
# Use xcode-select to install command line components, including git $ xcode-select --install # Install homebrew $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" # Use homebrew to install ansible $ brew install email@example.com
Installing a local development environment¶
islandora-playbook, set the base box, and use
vagrant up to automatically provision a local environment. This method uses Vagrant, VirtualBox, and Ansible. Before provisioning a local environment, you should likely double check that no required ports are currently in use.
Clone the playbook¶
For the most recent release:
$ git clone -b main https://github.com/Islandora-Devops/islandora-playbook $ cd islandora-playbook
For the bleeding edge:
$ git clone -b dev https://github.com/Islandora-Devops/islandora-playbook $ cd islandora-playbook
Set the base box¶
To tell Vagrant which base box to use, set ISLANDORA_DISTRO. This can be done by editing the Vagrantfile or by setting a shell variable.
Editing the Vagrantfile¶
Vagrantfile (in the islandora-playbook directory) in a text editor, and find the following section.
# Available boxes are 'islandora/8', ubuntu/bionic64' and 'centos/7' # Use 'ubuntu/bionic64' or 'centos/7' to build a dev environment from scratch. # Use 'islandora/8' if you just want to download a ready to run VM. $vagrantBox = ENV.fetch("ISLANDORA_DISTRO", "islandora/8")
To build a dev environment that is Ubuntu, change the last line of that section to:
$vagrantBox = ENV.fetch("ISLANDORA_DISTRO", "ubuntu/bionic64")
To build a dev environment that is CentOS, change the last line of that section to:
$vagrantBox = ENV.fetch("ISLANDORA_DISTRO", "centos/7")
Note that setting ISLANORA_DISTRO as a shell variable will override what is specified in the Vagrantfile.
Setting ISLANDORA_DISTRO as a shell (environment) variable¶
Or, an alternative to altering the Vagrantfile, you can set
ISLANDORA_DISTRO by adding the following
.bashrc (on Ubuntu/Debian environments), or
.bash_profile (on MacOS):
This will override what is written in the Vagrantfile.
Spin up with Vagrant¶
- If building a CentOS box, you also need to install the vbguest additions with
vagrant plugin install vagrant-vbguest.
- If this is not your first time spinning up Islandora from this directory, and you want to get the latest code, you may want to clear cached ansible roles in roles/external
rm -rf roles/external
Then, to spin up the machine:
Installing a remote environment¶
A remote environment can be provisioned by providing SSH credentials to
claw-playbook and using the
ansible-galaxy installer instead of Vagrant. Some preparation of configuration entries in the
inventory also need to be changed to be aware of the particulars of your remote environment; this includes:
- Changing usernames and passwords to something more sensible than the default
- Changing IP addresses to use the remote machine's actual IP
- Changing Apache to serve at port 80 (as opposed to 8000, which we use for development purposes)
We're going to build up this new remote environment configuration from the default provided Vagrant configuration. To start, take the inventory for the vagrant development environment and make a copy of it. Be sure to give it an appropriate name. Here we're using
$ git clone https://github.com/Islandora-Devops/islandora-playbook $ cd islandora-playbook $ cp -r inventory/vagrant inventory/example
Then you can update the following entries in the following files using your own information. If an entry does not exist in a file, just add it. Ansible will then use the value you provide instead of relying on its defaults.
changeme to represent passwords and assume the server will be available at
example.org, but you'll want to provide
your own values.
drupal_db_password: changeme drupal_account_pass: changeme islandora_db_root_password: changeme islandora_tomcat_password: changeme islandora_syn_token: changeme cantaloupe_admin_password: changeme
crayfish_gemini_fedora_base_url: http://example.org:8080/fcrepo/rest crayfish_houdini_fedora_base_url: http://example.org:8080/fcrepo/rest crayfish_hypercube_fedora_base_url: http://example.org:8080/fcrepo/rest crayfish_milliner_fedora_base_url: http://example.org:8080/fcrepo/rest crayfish_milliner_drupal_base_url: http://example.org crayfish_milliner_gemini_base_url: http://example.org/gemini crayfish_homarus_fedora_base_url: http://example.org:8080/fcrepo/rest crayfish_recast_fedora_base_url: http://example.org:8080/fcrepo/rest crayfish_recast_drupal_base_url: http://example.org crayfish_recast_gemini_base_url: http://example.org/gemini
For Alpaca, only the
token.value and various URLs are of particular importance, but the entire configuration chunk is provided here for convenience.
alpaca_settings: - pid: ca.islandora.alpaca.http.client settings: token.value: changeme - pid: org.fcrepo.camel.indexing.triplestore settings: input.stream: activemq:topic:fedora triplestore.reindex.stream: activemq:queue:triplestore.reindex triplestore.baseUrl: http://example.org:8080/bigdata/namespace/islandora/sparql - pid: ca.islandora.alpaca.indexing.triplestore settings: error.maxRedeliveries: 10 index.stream: activemq:queue:islandora-indexing-triplestore-index delete.stream: activemq:queue:islandora-indexing-triplestore-delete triplestore.baseUrl: http://example.org:8080/bigdata/namespace/islandora/sparql - pid: ca.islandora.alpaca.indexing.fcrepo settings: error.maxRedeliveries: 5 node.stream: activemq:queue:islandora-indexing-fcrepo-content node.delete.stream: activemq:queue:islandora-indexing-fcrepo-delete media.stream: activemq:queue:islandora-indexing-fcrepo-media file.stream: activemq:queue:islandora-indexing-fcrepo-file file.delete.stream: activemq:queue:islandora-indexing-fcrepo-file-delete milliner.baseUrl: http://example.org/milliner/ gemini.baseUrl: http://example.org/gemini/ alpaca_blueprint_settings: - pid: ca.islandora.alpaca.connector.houdini in_stream: activemq:queue:islandora-connector-houdini derivative_service_url: http://example.org/houdini/convert error_max_redeliveries: 5 camel_context_id: IslandoraConnectorHoudini - pid: ca.islandora.alpaca.connector.homarus in_stream: activemq:queue:islandora-connector-homarus derivative_service_url: http://example.org/homarus/convert error_max_redeliveries: 5 camel_context_id: IslandoraConnectorHomarus
fcrepo_allowed_external_content: - http://example.org/ cantaloupe_HttpResolver_BasicLookupStrategy_url_prefix: http://example.org/
This is where we specify that the webserver is listening on the default port 80, instead of the development machine port 8000.
drupal_trusted_hosts: - ^localhost$ - example.org fedora_base_url: "http://example.org:8080/fcrepo/rest/"
openseadragon_iiiv_server: http://example.org:8080/cantaloupe/iiif/2 matomo_site_url: http://example.org
You'll need the SSH particulars for logging into your server in the hosts file. This example is set up to login as
an SSH key. You'll need to get the details for logging into your remote server from your hosting provider (AWS, Digital Ocean, etc...)
or your systems administrator if you're running the server in-house. See
for more details about what you can put into a
default ansible_host=example.org ansible_port=22 ansible_user=root ansible_ssh_private_key_file='/home/username/.ssh/id_rsa'
Running the remote installer¶
First, you'll want to get the ansible roles that are needed for the version of Islandora you are trying to install. This can be done with
$ ansible-galaxy install -r requirements.yml
Then, depending on the operating system installed on the remote environment, you can use the following command for Ubuntu 16.04
$ ansible-playbook -i inventory/production playbook.yml -e "islandora_distro=ubuntu/xenial64"
or for CentOS 7
$ ansible-playbook -i inventory/production playbook.yml -e "islandora_distro=centos/7"
Out of date playbooks¶
Ansible caches the code used to provision the environment, so if you've already installed once you may not be getting the latest version
of things even if you've
git pull'd the latest playbook. The code is stored in
roles/external, so if you want to clear it out you can
remove these before attempting to provision an environment
$ rm -rf roles/external
Port clashes for local environments¶
When provisioning using a local environment, you should be aware of any ports that are already in use by your computer that are also going to be used by Vagrant, as these may clash and cause problems during and after provisioning. These include:
- 8000 (Apache)
- 8080 (Tomcat)
- 3306 (MySQL)
- 5432 (PostgreSQL)
- 8983 (Solr)
- 8161 (ActiveMQ)
- 8081 (API-X)
If there are port clashes for any of these, you will need to either find and replace them in the configuration .yml files under
inventory/vagrant/group_vars, or provide new values for the different playbooks that support changing the ports (for example,
supports adding a
port property which is currently simply unused). You will also need to replace the port forwarding values in
Additionally, Ansible attempts to use port 2200 for SSH. If this port is already in use, your local environment cannot be provisioned. To
change this, set a new value for
If you run into any issues installing the environment, do not hesitate to email the mailing list to
ask for help. If you think you've stumbled across a bug in the installer, please create an issue in the
Islandora 8 issue queue and give it an