Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README for Playbook 2.0.0 #242

Merged
merged 1 commit into from
Dec 16, 2022
Merged

Update README for Playbook 2.0.0 #242

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 51 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,52 +3,49 @@

## Introduction

This is an Ansible playbook for provisioning an instance of Islandora. This repository includes a Vagrantfile, so `vagrant up` will create a local virtual machine and run the playbook on it.
This is an Ansible playbook for provisioning an instance of Islandora. This repository can be used with Vagrant, or for deploying to a remote server.

This can also be used as an ansible playbook (playbook.yml) to provision a remote server. If doing so, be sure to change the passwords in `inventory/vagrant/group_vars/all/passwords.yml` (or override them with your own inventory), as well as ensure all ports except the Drupal port are behind a firewall.
As of tag 2.0.0, deployment is done in two stages:
* with `islandora_build_base_box=true` ('ISLANDORA_BUILD_BASE=true' in Vagrant), to install environment components that change infrequently, and
* with `islandora_build_base_box=false` ('ISLANDORA_BUILD_BASE=false' [default] in Vagrant), to install and configure the Islandora software.

The base box can be stored, to save time on subsequent builds (e.g. for creating dev or testing environments).

For usage instructions, including Vagrant and remote server deployment, see [Islandora Playbook](https://islandora.github.io/documentation/installation/playbook) in the Islandora Documentation.

For an alternative installation using Docker, please see [ISLE](https://islandora.github.io/documentation/installation/docker-introduction/).

## Running Vagrant on Macs

### No Virtualbox available for M1, M2 Macs
## Use

The new architecture of the Apple silicon chips (M1, M2) is incompatible with VirtualBox,
so the newest Macs cannot be used with the Vagrant method. However, they can still deploy
the playbook to remote VMs, or use Docker (ISLE).
Detailed installation and usage instructions can be found on the [official installation documentation for Islandora](https://islandora.github.io/documentation/installation/playbook/).

### macOS 12.0 Monterey VirtualBox Workaround

VirtualBox has not been updated to work fully with macOS Monterey as of October, 2021.
A workaround exists, which is to run VirtualBox in non-headless mode.
## Variables

In your Vagrantfile, add the line `v.gui = true` to the configuration section near the top:
These Vagrant variables (in all caps) are read from the environment, so if you set them as Unix shell variables they will override the defaults defined in the Vagrantfile.

```
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
config.vm.provider "virtualbox" do |v|
v.name = "Islandora 8 Ansible"
v.gui = true
end
```
### Build Base box

Discussion of this issue can be found on [this issue](https://github.com/hashicorp/vagrant/issues/12557
) in Vagrant's GitHub project.
If `ISLANDORA_BUILD_BASE` is `true`, then the playbook will download a standard Vagrant base box of the `ISLANDORA_DISTRO` and partly provision it, creating a virtual machine that can be saved as an islandora base box.

## Variables
If `ISLANDORA_BUILD_BASE` is `false` (default), then the playbook will use an existing islandora base box and provision the islandora software.

This corresponds to the `islandora_build_base_box` Ansible variable.

### Base box
### Islandora Distro

By default the Vagrantfile builds Islandora on a `ubuntu/focal64` (20.04 LTS) base box.
`ISLANDORA_DISTRO` defaults to `ubuntu/focal64` (20.04 LTS), which is currently the only working distribution.

This corresponds to the `islandora_distro` Ansible variable.

### Install Profile

The Unix shell variable `ISLANDORA_INSTALL_PROFILE` can be one of:
`ISLANDORA_INSTALL_PROFILE` can be one of:

* `demo`: Installs the demo based on the [install profile](https://github.com/Islandora-Devops/islandora_install_profile_demo) developed by Born Digital. This has a custom theme and more out-of-the-box customizations.
* `starter`: Installs using [the `islandora/islandora-starter-site` project](https://github.com/Islandora/islandora-starter-site/) as a template, intended for spinning up sites for general usage.
* `starter_dev`: Similar to `starter`, installs based on [the `islandora/islandora-starter-site` project](https://github.com/Islandora/islandora-starter-site/); however, performs a clone of the repository with its history, intended specifically for development of the starter site.
* `demo`: Installs the demo based on the [install profile](https://github.com/Islandora-Devops/islandora_install_profile_demo) developed by Born Digital. This has a custom theme and more out-of-the-box customizations.

This corresponds to the `islandora_profile` Ansible variable.

Expand All @@ -61,11 +58,7 @@ export ISLANDORA_VAGRANT_CPUS=4
export ISLANDORA_VAGRANT_MEMORY=5040
```

## Use

Detailed installation and usage instructions can be found on the [official installation documentation for Islandora](https://islandora.github.io/documentation/installation/playbook/).

## Connect
## Connect (Vagrant)

You can connect to the machine via the browser at [http://localhost:8000](http://localhost:8000).

Expand Down Expand Up @@ -139,6 +132,34 @@ The Playbook installs an instance of the [Matomo](https://matomo.org/) web analy
* username: admin
* password: islandora


## Running Vagrant on Macs

### Virtualbox not available for M1, M2 Macs

The new architecture of the Apple silicon chips (M1, M2) is incompatible with VirtualBox,
so the newest Macs cannot be used with the Vagrant method. However, they can still deploy
the playbook to remote VMs, or use Docker (ISLE).

### macOS 12.0 Monterey VirtualBox Workaround

VirtualBox has not been updated to work fully with macOS Monterey as of October, 2021.
A workaround exists, which is to run VirtualBox in non-headless mode.

In your Vagrantfile, add the line `v.gui = true` to the configuration section near the top:

```
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
config.vm.provider "virtualbox" do |v|
v.name = "Islandora 8 Ansible"
v.gui = true
end
```

Discussion of this issue can be found on [this issue](https://github.com/hashicorp/vagrant/issues/12557
) in Vagrant's GitHub project.


## Roadmap

The playbook is in maintenance mode as new development is focused on [ISLE](https://islandora.github.io/documentation/installation/docker-compose/) for development and production.
Expand Down