From 8c583eac969493995b6b20f8d46a4a2ea46b98ec Mon Sep 17 00:00:00 2001 From: Rosie Le Faive Date: Thu, 15 Dec 2022 22:45:50 -0400 Subject: [PATCH] Update README for Playbook 2.0.0 (#242) --- README.md | 81 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 51 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 5c5a78ab..f18d789c 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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). @@ -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.