From aa36a773748ce9bd592e7535fe83036761d870a5 Mon Sep 17 00:00:00 2001 From: bencomp Date: Wed, 21 Aug 2019 16:28:19 +0200 Subject: [PATCH] Update and clarify README for 7.x-1.13 (#100) This update does not present new information, but hopefully makes the README more readable. - add "Djatoka or IIIF image server" as requirement - reorder installation options, implicitly prefer Drush - explain what configuration is discussed here - explain IIIF settings - align IIIF settings with Djatoka settings - make reverse proxy information more generic - remove Apache example setup - update Cantaloupe URLs - use more informative link labels - fix a few typos --- README.md | 79 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 51 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index b0496eb..f51b485 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Islandora OpenSeadragon [![Build Status](https://travis-ci.org/Islandora/islandora_openseadragon.png?branch=7.x)](https://travis-ci.org/Islandora/islandora_openseadragon) -# Introduction +## Introduction -An Islandora viewer module using OpenSeadragon. Works with large image datastreams (JPEG-2000). Supports a custom Djatoka tilesource and a IIIF tilesource. +This is an Islandora viewer module using OpenSeadragon. It allows users to view large image datastreams (like JPEG-2000) through image tile servers. This module supports a custom Djatoka tilesource and a IIIF tilesource. -Based in spirit from the JS component of Kevin Clarke's [FreeLib-Djatoka](https://github.com/ksclarke/freelib-djatoka) +Based in spirit on the JS component of Kevin Clarke's [FreeLib-Djatoka](https://github.com/ksclarke/freelib-djatoka). ## Requirements @@ -15,55 +15,78 @@ This module requires the following modules/libraries: * [OpenSeadragon](https://github.com/openseadragon/openseadragon/) * [Drupal Token Module](https://www.drupal.org/project/token) +In addition, either Djatoka or a IIIF image server needs to be setup. + ## Installation -Install as usual, see [this](https://drupal.org/documentation/install/modules-themes/modules-7) for further information. +Install the module as usual, see [Drupal 7's documentation on installing modules](https://drupal.org/documentation/install/modules-themes/modules-7) for further information. + +The OpenSeadragon JavaScript library is not included in this module. Openseadragon 2.3.1 is known to work well with Islandora. +You can use Drush to download and install it automatically or do it manually. + +Older versions must be updated. You can do this quickly +with the provided Drush command. + +### Drush OpenSeadragon installation + +This module provides a Drush command to download and install a recent version of OpenSeadragon. It is advisable to *move* (not copy) the install script to your `.drush` folder and run the following command from that folder: -[Download](https://github.com/openseadragon/openseadragon/releases/download/v2.3.1/openseadragon-bin-2.3.1.zip) and install the Openseadragon library to your sites/libraries folder, or run `drush openseadragon-plugin`. Openseadragon 2.3.1 is known to work well with Islandora. +`drush openseadragon-plugin` -Note: If you use the Drush command, it is advisable to Move (not copy) the install script to your `.drush` folder and run it. +### Manual OpenSeadragon installation + +Download the [OpenSeadragon 2.3.1 binary release](https://github.com/openseadragon/openseadragon/releases/download/v2.3.1/openseadragon-bin-2.3.1.zip) and install the Openseadragon library to your sites/libraries folder. ## Configuration -### Djatoka Image Server +Islandora OpenSeadragon offers many settings to be configured. All settings are found in Administration » Islandora » Islandora Viewers » OpenSeadragon (admin/islandora/islandora_viewers/openseadragon). -#### Drupal +In this README, only the image server settings are highlighted. +Other settings are explained on the [Open Seadragon wiki page](https://wiki.duraspace.org/display/ISLANDORA/Open+Seadragon). -Set the paths for 'Djatoka server base URL' and configure OpenSeadragon in Administration » Islandora » Islandora Viewers » OpenSeadragon (admin/islandora/islandora_viewers/openseadragon). +### Djatoka Image Server -![Configuration](https://user-images.githubusercontent.com/25011926/40389344-2a7854ea-5de0-11e8-8db9-7a1bf25f2561.png) +When you use the Adore-Djatoka Image Server ("Djatoka"), you need to set the base URL to the Adore-Djatoka server OpenURL resolver. +The base URL depends on the setup of Djatoka, including (optional) configuration of a reverse proxy. -If you have an *existing* install it's required to update Openseadragon to it's latest version. You can do this quickly -with the provided Drush command. +By default, Islandora OpenSeadragon expects that the Djatoka OpenURL resolver is reachable on the same domain name and port as Islandora itself, at the path `adore-djatoka/resolver`. +A checkmark and confirmation message appear when Islandora can connect to the server. +If Islandora cannot connect to the server, a cross and error message appear. -```bash -drush openseadragon-plugin -``` +![Configuration](https://user-images.githubusercontent.com/25011926/40389344-2a7854ea-5de0-11e8-8db9-7a1bf25f2561.png) -#### Apache Reverse Proxy +### IIIF Image server -Reverse proxy config: We make the assumption that we (reverse) proxy Djatoka, to fix the same-origin issue. +When you use the IIIF Image Server, you need to specify: -For Apache, with Drupal running on the same box as Apache, a couple lines like: +* the base URL of the image server; +* whether to send the image access token as a HTTP header instead of a query parameter; +* the pattern to use as the image identifier. -``` -ProxyPass /adore-djatoka http://localhost:8080/adore-djatoka -ProxyPassReverse /adore-djatoka http://localhost:8080/adore-djatoka -``` +As with Djatoka, the base URL depends on the setup of your IIIF image server and reverse proxy, if you use one. +Any [IIIF](https://iiif.io) image server can be used as the IIIF tile source. This IIIF server does need to be configured to resolve the image identifier to retrieve the image. -in the Apache config somewhere (either the main apache.conf, httpd.conf, or in and arbitrarily named `*.conf` in your Apache's conf.d directory should suffice to establish the reverse proxy. +By default, Islandora OpenSeadragon uses the full URL to the image's JP2 datastream and the image access token as image identifier. +If you use the [Cantaloupe 🍈](https://cantaloupe-project.github.io/) IIIF image server, +you can configure it to resolve these identifiers using the [`HttpResolver`](https://cantaloupe-project.github.io/manual/3.4/resolvers.html#HttpResolver) with no prefix specified. -In Debian derived systems one will need to create location entries for each proxy or remove the Deny from All in mod_proxy's conf file. +### Reverse Proxy -### IIIF +A reverse proxy can be used to make an image server available on the same domain as Drupal, +so that cross-origin resource access and the need for CORS headers are avoided. +Various applications can be used as a reverse proxy; [Apache HTTPD] and [nginx] are common in reverse proxy setups. +For details on configuring your reverse proxy, you should consult the documentation for your application of choice. -Any [IIIF](http://iiif.io) image server can be used the the IIIF tile source. The IIIF tile source provides a full URL to the datastream to be displayed as the IIIF `identifier`. The IIIF server needs to be configured to resolve this full URL to retrieve the image. +[Apache HTTPD]: https://httpd.apache.org +[nginx]: https://nginx.org/ -The [Cantaloupe 🍈](https://medusa-project.github.io/cantaloupe/) IIIF image server can be configured to resolve these identifiers using the [`HttpResolver`](https://medusa-project.github.io/cantaloupe/manual/3.3/resolvers.html#HttpResolver) with no prefix specified. +Note: if you use a reverse proxy, you may need to configure the image server as well, so that it knows +what external URLs are used to reach the image server. Whether this is necessary and how the image server +needs to be configured, depends on the image server. ## Documentation -Further documentation for this module is available at [our wiki](https://wiki.duraspace.org/display/ISLANDORA/Open+Seadragon) +Further documentation for this module is available at [our wiki](https://wiki.duraspace.org/display/ISLANDORA/Open+Seadragon). ## Troubleshooting/Issues