Installation

This documentation is outdated and in need of review.

Setup and installation

Here you'll find instructions on how to set up the document viewer on your own server. It can then be easily integrated into an existing website.

This guide will assume that you already have a website set up on a server and that the images you want to display can be stored on a server capable of running the IIPImage server.

What you'll need

• IIPImage server installation package (download)
• Some images that you want to display using Diva.js
• The installation package for Diva.js

Setting up the backend

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 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 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 process.py documentation for more information. 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.

<a name="configuring-the-frontend"></a>
Configuring the frontend
-----------------------

###The HTML file###

Create an HTML file that will contain the document viewer. For an example, check out example.html in the Diva.js download. The important elements in the head are as follows:
```html
<head>
	<link rel="stylesheet" href="css/diva.css" type="text/css" />
	<link rel="stylesheet" href="css/ui-lightness/jquery-ui-1.8.9.custom.css" type="text/css" />
	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.5.2/jquery.min.js"></script>
	<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.8.11/jquery-ui-min.js"></script>
	<script src="js/diva-utils.js"></script>
	<script src="js/diva.js"></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
		});
	});
	</script>
</head>

To see the other options that can be set upon instantiation, see the overrideable settings section. Such options include setting a fixed (as opposed to adaptive) interpage padding, enabling the use of the space key to scroll down, and making use of callback functions for document viewer events like jumping to a specific page, zooming in or out, or scrolling.

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

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>

###The CSS

If you wish to simple styling of your Diva front-end you can hand-edit the css/diva.css file. 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.

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;
	}

}

You would configure this setup by pointing the iipServerBaseUrl to http://example.com:9000/fcgi-bin/iipsrv.fcgi?FIF=/path/to/images/image_directory_name.

Memcached

The 0.9.9 release of the IIP Image 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.