From fbdbda554278f2a1d392ee612bf62ca49f583b75 Mon Sep 17 00:00:00 2001 From: Rosie Le Faive Date: Mon, 24 Aug 2020 11:09:56 -0300 Subject: [PATCH 1/5] Render the example helpful tip properly. (#1586) * Render the example helpful tip properly. * Fix note syntax, again. --- docs/contributing/docs_style_guide.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/contributing/docs_style_guide.md b/docs/contributing/docs_style_guide.md index e810b210b..7e092bd01 100644 --- a/docs/contributing/docs_style_guide.md +++ b/docs/contributing/docs_style_guide.md @@ -10,9 +10,20 @@ - Use `-` instead of `*` for bulleted lists. - Upload images to the 'assets' folder and reference them from there. -- For file name, use underscores between words and prefix all file names with the page name, e.g. context_display_hints.jpg for the image showing how to set display hints in the context menu. -- Use `!!! note "Note title"` at the start of a paragraph to have it rendered as a note like this: +- Use the [Admonition syntax](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) to create notes like this (four-space indent required): + +_Example:_ + +``` +!!! note "Helpful Tip" + I am a helpful tip! +``` + +_Result:_ + +!!! note "Helpful Tip" + I am a helpful tip! -!!! note "Helpful Tip" I am a helpful tip! ## Don'ts From 6a66bcf9dce6e34e10585d47665d89428ccb56f9 Mon Sep 17 00:00:00 2001 From: Rosie Le Faive Date: Mon, 24 Aug 2020 11:14:48 -0300 Subject: [PATCH 2/5] Mention the User Call (#1587) --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ee404a9e..40946f8f8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ If you are reading this document then you are interested in contributing to Isla ## Workflows -The group meets each Wednesday at 1:00 PM Eastern. Meeting notes and announcements are posted to the [Islandora community list](https://groups.google.com/forum/#!forum/islandora) and the [Islandora developers list](https://groups.google.com/forum/#!forum/islandora-dev). You can view meeting agendas, notes, and call-in information [here](https://github.com/Islandora/documentation/wiki#islandora-8-tech-calls). Anybody is welcome to join the calls, and add items to the agenda. +The Islandora 8 Tech Call meets each Wednesday at 1:00 PM Eastern, and the Islandora 8 User Call meets every second Thursday at 1:00 PM Eastern. Meeting notes and announcements are posted to the [Islandora community list](https://groups.google.com/forum/#!forum/islandora) and the [Islandora developers list](https://groups.google.com/forum/#!forum/islandora-dev). You can view meeting agendas, notes, and call-in information [here](https://github.com/Islandora/documentation/wiki#islandora-8-tech-calls). Anybody is welcome to join the calls, and add items to the agenda. ### Use cases From 26264e8e75345efa397aa8a9e7dc0f466cb7ce12 Mon Sep 17 00:00:00 2001 From: Eli Zoller <5439169+elizoller@users.noreply.github.com> Date: Tue, 25 Aug 2020 10:37:12 -0700 Subject: [PATCH 3/5] Update rdf-mapping.md doc (#1585) --- docs/islandora/rdf-mapping.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/islandora/rdf-mapping.md b/docs/islandora/rdf-mapping.md index ef064feac..124178e41 100644 --- a/docs/islandora/rdf-mapping.md +++ b/docs/islandora/rdf-mapping.md @@ -63,8 +63,28 @@ Below is an example of an RDF mapping as a .yml (YAML) file. It is the current v - The top level key `types` specifies the `rdf:type` of the resource or content model. `field_model`, a required field of Islandora objects, also gets mapped to `rdf:type` through an arcane back-end process. - The top level key `fieldMappings` specifies fields attached to that bundle and their RDF property mappings. One field can be mapped to more than one RDF property. It is a simple flat list. -- `datatype_callback` : [needs documentation] -- `mapping_type: rel` : [needs documentation] + +#### Mapping Types +`mapping_type:`: There are several mapping types which are provided out of the box. +- `rel` - standing for relationship, expresses a relationship between two resources +- `property` - the default, or if a relationship is not provided, expresses the relationship between a resource and some literal text. + +#### Datatype Callbacks +`datatype_callback`: This is a custom function that transforms the output of the field. There are some provided to us by Drupal and some added by Islandora, such as: +- `Drupal\controlled_access_terms\EDTFConverter::dateIso8601Value` which converts dates to Iso format +- `Drupal\jsonld\EntityReferenceConverter::linkFieldPassthrough` which converts a referenced entity to the URI on the entity (which is configurable with the `link_field` argument +An example usage of the `Drupal\jsonld\EntityReferenceConverter::linkFieldPassthrough` is as follows: +```yml +field_subject: + properties: + - 'dcterms:subject' + datatype_callback: + callable: 'Drupal\jsonld\EntityReferenceConverter::linkFieldPassthrough' + arguments: + link_field: 'field_authority_link' +``` +Which would convert a reference to the subject's taxonomy term entity to a reference to the URI provided in `field_authority_link` of that subject's taxonomy term entity. + ## Sample RDF Mapping ```yml From 6c1777b0f8e2ebeca52d16daeb76a4e8ab17a2e8 Mon Sep 17 00:00:00 2001 From: dannylamb Date: Thu, 27 Aug 2020 12:44:58 -0300 Subject: [PATCH 4/5] Update committers.md (#1592) --- docs/contributing/committers.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing/committers.md b/docs/contributing/committers.md index dacedc176..1f026aead 100644 --- a/docs/contributing/committers.md +++ b/docs/contributing/committers.md @@ -29,6 +29,7 @@ The following is an alphabetized list of the current Islandora 8 committers: | Name | Organization | Github username | |-----------------------------|---------------------------------------|----------------| +| Melissa Anez | Islandora Foundation | manez | | Jonathan Green | LYRASIS | jonathangreen | | Jonathan Hunt | Catalyst.Net | kayakr | | Mark Jordan | Simon Fraser University | mjordan | From 6a2bac321c32a68044ee4bebecf425f4f2d2b52e Mon Sep 17 00:00:00 2001 From: Rosie Le Faive Date: Fri, 28 Aug 2020 15:05:18 -0300 Subject: [PATCH 5/5] Document using base box and dev branch --- docs/installation/playbook.md | 103 +++++++++++++++++++++++++++------- 1 file changed, 82 insertions(+), 21 deletions(-) diff --git a/docs/installation/playbook.md b/docs/installation/playbook.md index 83747f43a..e28c79cc7 100644 --- a/docs/installation/playbook.md +++ b/docs/installation/playbook.md @@ -1,8 +1,26 @@ -The fastest way to get up and running with Islandora 8 is through an Ansible Playbook called [islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook). It can be used to spin up a local environment using [Vagrant](https://www.vagrantup.com/), or to provision an existing machine. +# Islandora Playbook + +The Islandora Playbook ([islandora-playbook](https://github.com/Islandora-Devops/islandora-playbook)) is a tool for installing Islandora Defaults. It can be used both as a Vagrant project to create a local development environment, or as an Ansible playbook which can provision a remote server. + +!!! Note + 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. + + +## Quick-start mode: + +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. + +```bash +$ 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. ## Requirements -Download and install the following: +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): 1. [Virtual Box](https://www.virtualbox.org/) 2. [Vagrant](https://www.vagrantup.com/) (version 2.0 or higher required) @@ -10,11 +28,11 @@ Download and install the following: 4. [OpenSSL](https://www.openssl.org/) 5. [Ansible](https://www.ansible.com/community) (up to, and not past, 2.8.7) -#### Ubuntu/Debian +#### Installing Git, OpenSSL, and Ansible on Ubuntu/Debian Git and OpenSSL are available via `apt`. [Ansible](https://www.ansible.com/community) up to version 2.8.7. This is done best with `pip`, the python package manager: -``` +```bash # Install git and openssl $ sudo apt-get install git $ sudo apt-get install openssl @@ -25,11 +43,11 @@ $ python get-pip.py --user $ pip install --user -Iv ansible==2.8.7 ``` -#### CentOS +#### Installing Git, OpenSSL and Ansible on CentOS Git and OpenSSL are available via `yum`. Most everything else can be installed in the same way. -``` +```bash $ sudo yum install git $ sudo yum install openssl # If pip isn’t already available, run the following commands to install it @@ -39,46 +57,89 @@ $ python get-pip.py --user $ pip install --user -Iv ansible==2.8.7 ``` -#### MacOS +#### Installing Git and Ansible on MacOS -OpenSSL is already pre-installed on MacOS. Python and Pip should be installed via the downloaded installer direct from the site. For the installation of Ansible, consider using [homebrew](https://brew.sh/): +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](https://brew.sh/) (see below). -``` +```bash # 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 ansible@2.8.7 ``` ## Installing a local development environment -Before provisioning a local environment, you should likely double check that no [required ports](#port-clashes-for-local-environments) are currently in use. +Clone the `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](#port-clashes-for-local-environments) are currently in use. -Clone the `islandora-playbook` and use `vagrant up` to automatically provision an environment. +### Clone the playbook -#### Ubuntu 18.04 or MacOS +For the most recent release: +```bash +$ git clone -b main https://github.com/Islandora-Devops/islandora-playbook +$ cd islandora-playbook +``` +For the bleeding edge: ```bash -$ git clone https://github.com/Islandora-Devops/islandora-playbook +$ git clone -b dev https://github.com/Islandora-Devops/islandora-playbook $ cd islandora-playbook -$ vagrant up ``` +### Set the base box -#### CentOS 7 +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 + +Open `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 +to `.bashrc` (on Ubuntu/Debian environments), or `.bash_profile` (on MacOS): ```bash -$ git clone https://github.com/Islandora-Devops/islandora-playbook -$ cd islandora-playbook -$ vagrant plugin install vagrant-vbguest -$ ISLANDORA_DISTRO="centos/7" vagrant up +export ISLANDORA_DISTRO="ubuntu/bionic64" ``` -Or, for simplicity's sake, add the following to your user profile (e.g., `.bashrc` on Ubuntu/Debian environments, or `.bash_profile` on MacOS): +This will override what is written in the Vagrantfile. + +### Spin up with Vagrant + +Before using `vagrant up`: + +- 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: ```bash -export ISLANDORA_DISTRO="centos/7" +vagrant up ``` + + ## 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: