Skip to content

Commit

Permalink
Improve ~remote~ _playbook_ instructions. (#2191)
Browse files Browse the repository at this point in the history 
* Improve remote instructions.

* Add new  variable to remote playbook intructions.

* Leave the cantaloupe_HttpResolver_BasicLookupStrategy_url_prefix='' to allow cantaloupe.

* Instructions for Playbook in Two Pieces.

* Update Ubuntu version mentioned to 22.04.

* Make more consistent.

* Mention how to recreate VM.

* Remove accidental files.
  • Loading branch information
@rosiel
rosiel authored Jan 19, 2023
1 parent 218fdfa commit 75f51fb
Showing 1 changed file with 73 additions and 111 deletions.
184 changes: 73 additions & 111 deletions docs/installation/playbook.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,28 @@
# Islandora Playbook

!!! note "Still Alive"
Reports of the playbook's demise have been exaggerated. It is still in use and being maintained. Local VMs (VirtualBox) cannot be run on M1 series Apple silicon at this time, but you can use the remote deployment option to deploy Islandora on low-cost virtual hosting.
The Islandora Playbook ([Islandora-Devops/islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook)) is a tool for installing the Islandora stack on a single virtual machine. It can be used both as a [Vagrant](https://www.vagrantup.com/) project to create a local development environment, or as an [Ansible](https://www.ansible.com/community) playbook to provision a local or remote server. It can set up a Drupal based either on Islandora Starter Site, or on the Install Profile Demo.

The Islandora Playbook ([Islandora-Devops/islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook)) is a tool for installing the Islandora stack on a single virtual machine. It can be used both as a [Vagrant](https://www.vagrantup.com/) project to create a local development environment, or as an [Ansible](https://www.ansible.com/community) playbook to provision a local or remote server. It can set up a Drupal based either on Islandora Starter Site, or on the Install Profile Demo.
## Basic Usage (Vagrant):

## Basic Usage (local, Islandora Starter Site):

Install requirements, then:
Install requirements (below), then:
```bash
$ git clone -b dev https://github.com/Islandora-Devops/islandora-playbook
$ cd islandora-playbook
$ vagrant up
```
## Basic Usage (local, Install Profile Demo):

Install requirements, then:
First, create the islandora base box:
```bash
$ ISLANDORA_BUILD_BASE=true vagrant up
$ vagrant package --output islandora_base
$ vagrant destroy
```
Second, build a VM using the islandora base box:
```bash
$ git clone -b dev https://github.com/Islandora-Devops/islandora-playbook
$ cd islandora-playbook
$ export ISLANDORA_INSTALL_PROFILE=demo
$ vagrant up
```

## Requirements
When used this way, you can trash your working site and get a fresh Islandora relatively quickly, with `vagrant destroy` (you will be asked to confirm, as this will delete all your changes and your content), and then `vagrant up`.

## Requirements (Vagrant)

To create a local VM, download and install the following.

Expand All @@ -34,7 +33,7 @@ To create a local VM, download and install the following.
5. [Ansible](https://www.ansible.com/community) (Tested on version 2.11+, versions back to 2.9 should work.)


#### Installing Git and Ansible on MacOS
### 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 can either be installed via the downloaded installer direct from the site or via Homebrew (not shown below). Ansible is best installed using [Homebrew](https://brew.sh/) (see below).

Expand All @@ -49,7 +48,9 @@ $ brew install ansible

## Installing a local development environment

Clone the `islandora-playbook` 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](#port-clashes-for-local-environments) are currently in use.
You will use `vagrant up` twice, first to create an Islandora base box, and then again to provision that base box into a full Islanodra. This method uses Vagrant, VirtualBox, and Ansible.

!!! warn Make sure that no [required ports](#port-clashes-for-local-environments) are currently in use.

### Clone the playbook

Expand All @@ -58,33 +59,60 @@ $ git clone -b dev https://github.com/Islandora-Devops/islandora-playbook
$ cd islandora-playbook
```

### Spin up with Vagrant
### Create the Base Box

Before using `vagrant up`:
The Playbook will create a "base box" that includes core software (PHP, Apache, etc). Since these do not need to be updated too often, this can be packaged as a Vagrant base box that will be used to quickly provision the Islandora part.

Notes:
- 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`
- If this is not your first time spinning up the Islandora Playbook from this directory, you may want to clear cached ansible roles in roles/external" `rm -rf roles/external`

First, create the islandora base box by overriding the Vagrant variable `ISLANDORA_BUILD_BASE` (which defaults to `false` in the `Vagrantfile`):
```bash
$ ISLANDORA_BUILD_BASE=true vagrant up
```

Then, to spin up the machine:
Once it is complete (without errors), store it as a Vagrant base box. It will appear as `islandora_base` in the current directory.
```bash
$ vagrant package --output islandora_base
```

Then, get rid of the existing VM since we've saved what we need:
```bash
$ vagrant destroy
default: Are you sure you want to destroy the 'default' VM? [y/N] y
==> default: Forcing shutdown of VM...
==> default: Destroying VM and associated drives...

```

Then, to provision Islandora on top of the new base box:
```bash
vagrant up
```

Access your site at `http://localhost:8000`.

## Deploying to a remote environment

A remote environment can be provisioned by providing SSH credentials to `islandora-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:
The `ansible-playbook` command using `playbook.yml` can provision a remote environment. First, you will need to create a new folder in `inventory/` with the details of your remote deployment. This includes:

- Configuring the SSH parameters so Ansible can log in
- Changing usernames and passwords to something more sensible than the default
- Changing IP addresses to use the remote machine's actual IP
- Changing IP addresses to use the remote machine's 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 `example`.
Before beginning, you may want to:

- Create a non-root user on the remote machine. Ansible will need to "escalate" (i.e. `sudo`) as this user. See Ansible Docs on [Understanding privilege escalation: become](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_privilege_escalation.html)
- Ensure all ports except the Drupal port and ports used by Ansible are behind a firewall.

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 `production`.

```bash
$ git clone https://github.com/Islandora-Devops/islandora-playbook
$ cd islandora-playbook
$ cp -r inventory/vagrant inventory/example
$ cp -r inventory/vagrant inventory/production
```

Then you can update the following entries in the following files using your own information. If an entry does not exist in a file,
Expand All @@ -96,79 +124,24 @@ your own values.
#### group_vars/all/passwords.yml

```yml
# Drupal
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
```

#### group_vars/crayfish.yml
# MySQL/Postgres
islandora_db_root_password: changeme

```yml
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
```
# Tomcat
islandora_tomcat_password: changeme

#### group_vars/karaf.yml
# Syn
islandora_syn_token: changeme

For Alpaca, only the `token.value` and various URLs are of particular importance, but the entire configuration chunk is provided here for convenience.
# Cantaloupe
cantaloupe_admin_password: changeme

```yml
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
```

#### group_vars/tomcat.yml

```yml
fcrepo_allowed_external_content:
- http://example.org/
cantaloupe_HttpResolver_BasicLookupStrategy_url_prefix: http://example.org/
# Fedora
fcrepo_db_password: changeme
```
#### group_vars/webserver/apache.yml
Expand All @@ -178,54 +151,42 @@ This is where we specify that the webserver is listening on the default port 80,
apache_listen_port: 80
```
#### group_vars/webserver/drupal.yml

```yml
drupal_trusted_hosts:
- ^localhost$
- example.org
fedora_base_url: "http://example.org:8080/fcrepo/rest/"
```

#### group_vars/webserver/general.yml
You will have to add the matomo line.
```yml
openseadragon_iiiv_server: http://example.org:8080/cantaloupe/iiif/2
matomo_site_url: http://example.org
```
#### hosts
You'll need the SSH particulars for logging into your server in the `inventory/vagrant/hosts` file . This example is set up to login as `root` using
You'll need to put particulars for logging into your server in the `inventory/production/hosts` file . This example is set up to login as the `ansible` user (to avoid trying to run Composer as `root`) and uses
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
[this page](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#connecting-to-hosts-behavioral-inventory-parameters)
for more details about what you can put into a
host file
[//]: # (How to avoid getting asked for a sudo password? Use -K in the command below? Configuring passwordless sudo seemed to not work. no idea how vagrant does it.)

```
default ansible_host=example.org ansible_port=22 ansible_user=root ansible_ssh_private_key_file='/home/username/.ssh/id_rsa'
default ansible_host=example.org ansible_port=22 ansible_user=ansible 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
First, you'll want to install the ansible roles that are needed for the version of Islandora you are trying to install. This can be done
with

```bash
$ 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
Then, if you are on Ubuntu 22.04, run the following commands:

```bash
$ ansible-playbook -i inventory/production playbook.yml -e "islandora_distro=ubuntu/xenial64"
```

or for CentOS 7

```bash
$ ansible-playbook -i inventory/production playbook.yml -e "islandora_distro=centos/7"
$ ansible-playbook -i inventory/production playbook.yml -e "islandora_distro=ubuntu/jammy64" -e "islandora_profile=starter" -e "islandora_build_base_box=true"
$ ansible-playbook -i inventory/production playbook.yml -e "islandora_distro=ubuntu/jammy64" -e "islandora_profile=starter" -e "islandora_build_base_box=false"
```

## Troubleshooting
Expand Down Expand Up @@ -265,3 +226,4 @@ change this, set a new value for `ansible_port` in `inventory/vagrant/hosts`.
If you run into any issues installing the environment, do not hesitate to email the [mailing list](mailto:islandora@googlegroups.com) to
ask for help. If you think you've stumbled across a bug in the installer, please create an issue in the
[Islandora issue queue](http://github.com/Islandora/documentation/issues) and give it an `ansible` tag.

0 comments on commit 75f51fb

Please sign in to comment.