Skip to content

Installation

Jump to bottom Edit New page
evan magoni edited this page Sep 10, 2015 · 101 revisions
Contents
  1. What You'll Need
  2. Setting up IIPImage
  3. Setting up IIIF
  4. Configuring the Diva.js viewer
    1. The HTML File
    2. The CSS
  5. Building From Source
  6. Advanced Topics
    1. Load Balancing
    2. Memcached

Here you'll find instructions on how to install and set up the Diva.js document viewer and image server software on your own server. Diva can then be easily integrated into an existing website.

What you'll need

This guide assumes that you already have a website set up, and that the images you want to display can be stored on a server capable of running the IIPImage server or any IIIF-compatible image server (see a list of IIIF-compatible Image Servers). It is also possible to use Diva without installing your own image server if the images you want to view are accessible through an existing IIIF repository.

Read on below if you plan to use IIPImage. Otherwise, follow the installation instructions for the IIIF-compatible server you wish to use, and skip to Setting up IIIF.

Setting up IIPImage

  1. Download the IIPImage Server installation package from the IIPImage website. Ensure you download the package compatible with your server's operating system.

  2. Install the IIPImage Server as a FastCGI module (instructions here). If you wish to serve JPEG2000 and install from the binaries, see our installation instructions.

    • If you wish to serve JPEG2000 images with IIP, it's a bit trickier. You will need to download the pre-compiled IIP binaries from Old Maps Online, since they require the Kakadu JPEG2000 library. Alternatively, you can purchase the source code to the Kakadu libraries and compile your own version.

  3. Convert your page images into one of two options: Pyramid TIFF or JPEG2000. We ship Diva with a script for processing these files, process.py. It can be used on the command line to convert an entire directory of image files into Pyramid TIFF or JPEG2000 files. See the image processing documentation for how to use. If you wish to use other utilities to convert your images, please see our documentation on image processing.

  4. To test your IIPImage server installation, transfer your image files onto the server running IIPImage. Ensure the images are in a directory accessible by the user of the server process (www-data for instance). Then try to load each image by going to this URL:
    ``` http://www.your-domain.com/fcgi-bin/iipsrv.fcgi?FIF=/path/to/images/image.tif&CVT=JPG


5. As part of the processing script in step 3, the system will generate a `.json` file containing the measurement information for your image collection. This file may be served using any web server, but it must be accessible to the front-end. To provide Diva with the document dimensions, the URL of this JSON file will be included as the `objectData` setting ([[see Settings|Settings#objectdata]]).

### A note about Cross-site Requests

You may receive an error that looks something like this:

XMLHttpRequest cannot load http://example.com/demo/imagefiles.json. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:8000' is therefore not allowed access.


This is a security precaution that all browsers use to prevent cross-site request forgeries. If you receive this message it is because your `objectData` parameter and the server used to serve the Diva page are not at the same server address.

To fix this you must ensure that the HTML page within which Diva.js is embedded and the location pointed to by the `objectData` page are being served by the same server, or you must create an exception using the `Access-Control-Allow-Origin` header on your server to explicitly white-list the `objectData` location. See [http://enable-cors.org/] for more details.

## Setting up IIIF

In order to use your own images with IIIF and Diva, you'll need two components: **1. a IIIF-compatible image server** and **2. a IIIF Manifest**, or metadata in the form of a JSON file that describes the structure of your document. (If you are using an external IIIF repository, simply skip to [Configuring the Diva.js Viewer](#configuring-the-divajs-viewer).)

1. If you are using a IIIF-compatible image server, follow its setup instructions to get your images displaying. See [this page](http://iiif.io/technical-details.html) for a list of recommended servers.

2. Some IIIF-compatible servers have facilities to serve a IIIF manifest that references the served images. If not, you will have to publish a manifest that conforms to the [IIIF Presentation API](http://iiif.io/api/presentation/2.0/). As of this writing, tools to automatically generate a manifest from a set of image files are in development. You may wish to try the [Manifest Factory Python module](https://github.com/IIIF/presentation-api/tree/master/implementations/manifest-factory), or write the [IIIF Discuss list](https://groups.google.com/forum/#!forum/iiif-discuss) to see what possibilities are available depending on where your images are coming from.

## Configuring the Diva.js viewer

First, you must [download the release package](http://ddmal.github.io/diva.js/download/) or install using npm (`npm install diva.js`) or Bower (`bower install diva.js`).

### The HTML file

Create an HTML file that will contain the document viewer. For an example, see [`demo/diva/single.html`](https://github.com/DDMAL/diva.js/blob/develop/demo/diva/single.html). 
The important elements in the head of your document are as follows. If you are using IIIF, only the `objectData` setting is required, and should point to your IIIF manifest JSON file. If you are using IIPImage, you need all three:

```html
<head>
    <link rel="stylesheet" href="/css/diva.min.css" />
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js" type="text/javascript"></script>
    <script src="/js/diva.min.js" type="text/javascript"></script>
    <script>
    $(document).ready(function() {
        $('#diva-wrapper').diva({
            iipServerURL: "http://www.mydomain.com/fcgi-bin/iipsrv.fcgi",
            objectData: "http://www.mydomain.com/data/image_collection.json",
            imageDir: "/path/to/images/on/your/server"
            // Other options can be set here as well - see the Settings page
        });
    });
    </script>
</head>

Whether you have downloaded the release package or included the CSS and JS files from CDNjs, ensure that jQuery is included above the Diva.js script and stylesheet tags.

If you are using IIPImage, you will want to set iipServerURL to the URL of your IIPImage fcgi executable, and objectData to the URL of the JSON file generated by process.py (see Setting Up IIPImage above). imageDir should be the absolute path to the image directory on your server.

If you are using IIIF (with your own images or an existing external repository), just set objectData to the URL of the Manifest and omit the iipServerURL and imageDir settings.

The body element should contain a block-level element, generally a div, with the ID specified above (diva-wrapper in this case, although any unique ID is valid, as long as the same one is used within the script tags above). For instance:

<body>
    <div id="diva-wrapper"></div>
</body>

If you load up the HTML document, you should see Diva loaded with your images! If not, try opening your browser's Javascript console to display any errors.

At this point, you have completed the basic installation process. If you're having trouble, stop by our Gitter chat or open an issue. To see the other options that can be set in the script tag, see the Settings page and the wiki sidebar. Such options include adjusting formatting, adding custom actions to hook into viewer events, changing the location of the toolbar to fit within your existing website or application, and more.

For deployment to your website, include diva.min.js to include all default plugins (see Using the Plugins and The API and Plugins). (If you wish to develop Diva or write plugins for it, you may wish to instead include diva.js, which consists of only the Diva core (for more on this, see the development notes))

It is not recommended to use a DOCTYPE of strict for your HTML document, as that causes problems with support for Apple touch devices.

The CSS

If you wish to style the document viewer you can hand-edit the css/diva.css file and include it in your <head>. If, however, you wish to perform more extensive modifications, it may be easier to instead edit the LESS source and re-compile the CSS. More information on this is available in the section on development for Diva.

Building From Source

If you wish to install from source, you can check out the code from our GitHub repository or use npm (npm install diva.js). npm automatically downloads and installs dependencies and is the preferred method of installation. We use gulp as our build system and for other development tasks.

If you retrieved the code from our GitHub repository and already have node.js and npm installed, run npm install to fetch all dependencies. Install gulp if not already installed using npm install -g gulp and you can now run the following development tasks from the commandline:

gulp develop          // Runs a server at localhost:9001 and automatically builds and reloads upon changes
gulp develop:build    // Compiles the Javascript and LESS source and places it in the build/ directory
gulp develop:jshint   // Lints the Javascript source with JSHint
gulp develop:test     // Runs the unit tests and outputs a report to the console
gulp develop:release x.x.x   // Builds the release package for the specified version number
gulp develop:clean    // Removes the contents of the build/ directory

The full installation gives you access to the un-minified JavaScript source, the plugins, the documentation, and our unit-tests. See the Code Documentation section of the wiki sidebar for more information about developing Diva.

Advanced Topics

If you are expecting to serve up many images, we have found that using load balancing across multiple IIP FastCGI instances along with multiple Memcached stores dramatically improves the performance of Diva.

Load Balancing

We use the NginX webserver for a front-end to the IIP Image Server. The following is a snippet from an NginX configuration file that load balances across five IIP Image Servers.

upstream iip {
	server 127.0.0.1:9010;
	server 127.0.0.1:9011;
	server 127.0.0.1:9012;
	server 127.0.0.1:9013;
	server 127.0.0.1:9014;
}

server {
       	listen 9000;
	server_name example.com;

	location /fcgi-bin/iipsrv.fcgi {
		fastcgi_pass 	iip;
		fastcgi_param   PATH_INFO $fastcgi_script_name;
                fastcgi_param   REQUEST_METHOD $request_method;
                fastcgi_param   QUERY_STRING $query_string;
                fastcgi_param   CONTENT_TYPE $content_type;
                fastcgi_param   CONTENT_LENGTH $content_length;
	}
}

The listen port in the server block can be any preferred port (default 80). You would configure this setup by initializing Diva with settings resembling these:

iipServerURL: "http://example.com:9000/fcgi-bin/iipsrv.fcgi",
imageDir: "/server/path/to/images/"

Memcached

IIPImage Server supports the definition of multiple memcached instances for caching pre-processed images. This dramatically reduces the response time of the tile server, and is especially useful for often-consulted books. Notes on how to set this up are available on the IIP website (see Server Configuration).

Add a custom footer
Clone this wiki locally