Configuring digilib

The main configuration for digilib is the XML file digilib-config.xml in the WEB-INF directory of the webapp. Alternatively you can also use a Java properties file digilib.properties somewhere in the classpath. (If you really need a different location for the XML file you can define it in the config-file init-parameter to the Servlet. TODO add an example)

In the configuration file you can set lots of paths and options. digilib uses default values for all configuration settings that meet most requirements. Hence you have to configure only the settings that you want to change. The basedir-list parameter however is mandatory unless you only want to serve the contributed example images for an evaluation.

All options are defined as parameter elements with the attributes name and value that are wrapped in the root element digilib-config. A minimal configuration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<digilib-config>
    <parameter name="basedir-list" value="/usr/local/images" />
</digilib-config>

A more extensive example is included in the sources as digilib-config.xml.template.

Available parameters

The documented parameter values below are the defaults.

If relative paths are provided as file locations, these will be resolved with the web application’s directory as base.

You can inspect a summary of your running digilib configuration at the URL <base_url>/server/dlConfig.jsp e.g. http://localhost:8080/digilib/server/dlConfig.jsp.

Image locations

<parameter name="basedir-list" value="sample-images" />

A list of directories where images are searched. See this document for details (required).

<parameter name="denied-image" value="img/digilib-denied.png" />

This image is sent to indicate an authorization failure.

<parameter name="error-image" value="img/digilib-error.png" />

This image is sent to indicate a general failure.

<parameter name="notfound-image" value="img/digilib-notfound.png" />

This image to sent to indicate that the requested image does not exist or could not be read.

<parameter name="use-mapping" value="false" />

Enables the mapping of ‘virtual directories’ to actual directories in the filesystem using a mapping file.

<parameter name="mapping-file" value="digilib-map.xml" />

The location of the mapping file. Refer to digilib-map.xml.template for an example.

The file contains mapping elements with a link attribute containing a ‘virtual directory’ name that is redirected to the directory given in the dir attribute.

Image processing options

<parameter name="default-quality" value="2" />

The default interpolation quality.

0: do not use interpolation (worst),
1: use linear interpolation,
2: use bilinear interpolation and blur-before-scale (best).

<parameter name="max-image-size" value="0" />

The maximum size of delivered images as pixel area, 40000 means up to 200x200 or 100x400, 0 means no limit.

<parameter name="sendfile-allowed" value="true" />

Defines whether requests with mo=file or mo=rawfile as parameter are allowed to download files (see Scaler API).

<parameter name="subsample-minimum" value="2.0" />

Specifies the degree of subsampling on image load. This is the minimum factor that is scaled by interpolation and not by subsampling, i.e. by skipping pixels.

<parameter name="image-reader-classes" value="image/jpeg=com.sun.imageio.plugins.jpeg.JPEGImageReader"/>
<parameter name="image-writer-classes" value="image/jpeg=com.sun.imageio.plugins.jpeg.JPEGImageWriter"/>

Parameters to explicitly specify the Java classes to use as ImageReader and ImageWriter for a given mime-type (separate multiple type-class pairs with comma). Only for special situations. Do not use this unless you have to!

<parameter name="input-preselection-allowed" value="false" />

Parameter to enable the input preselection mode. This mode currently tries to use browser-usable (JPEG, PNG, GIF) images for full-image unzoomed requests and tiled images for zoom requests. Enable this if you have different types of prescaled images at the same sizes and you want to offer both optimized tiled access and whole-image access.

Authentication and authorization

Details are provided in the documentation on authentication and authorization.

<parameter name="use-authorization" value="false" />

Enables or disables all authorization. If use-authorization is true you also have to configure authnops-class, authzops-class and the auth-file and its contents.

<parameter name="auth-file" value="digilib-auth.xml" />

Configuration file for authentication and authorization. The format and content of the configuration file is determined by the chosen authentication and authorization classes.

<parameter name="authn-token-cookie" value="id_token" />

The name of the cookie that holds the authentication token for digilib.auth.OpenIdAuthnOps.

<parameter name="authnops-class" value="digilib.auth.IpAuthnOps" />

The class to handle authentication.

<parameter name="authzops-class" value="digilib.auth.PathAuthzOps" />

The class to handle authorization.

IIIF API options

The options configure the IIIF interface. For more information see the digilib IIIF documentation

<parameter name="iiif-api-version" value="2.1" />

The IIIF API version for the generated info.json information response.

<parameter name="iiif-info-cors" value="true" />

Enables the Cross-Origin Resource Sharing header in IIIF info requests (Access-Control-Allow-Origin: *).

<parameter name="iiif-image-cors" value="true" />

Enables the Cross-Origin Resource Sharing header in IIIF image requests (Access-Control-Allow-Origin: *).

<parameter name="iiif-prefix" value="IIIF" />

The prefix (after Scaler) that leads to the IIIF API.

<parameter name="iiif-slash-replacement" value="!" />

The character that replaces a slash in the identifier of IIIF requests.

<parameter name="iiif-image-base-url" value="" />

The base URL used in constructing IIIF information resource URLs (needs to include servlet name and iiif-prefix). This is only necessary in some cases behind a proxy.

Threading options

<parameter name="max-waiting-threads" value="20" />

The maximum number of requests waiting in the queue before new requests get “service unavailable”.

<parameter name="worker-threads" value="2" />

The maximum number of concurrently working threads.

<parameter name="worker-timeout" value="60000" />

Timeout for worker threads in milliseconds.

Storage backends

The default configuration of digilib uses the filesystem of the server it runs on to find images (including mounted remote filesystems like NFS or CIFS).

This is implemented in the default DocuDirectory class that uses the basedir-list of image directories:

<parameter name="docudirectory-class" value="digilib.io.BaseDirDocuDirectory" />

But you can also use the new CDSTAR storage backend to directly access files stored in a CDSTAR server.

To use the CDSTAR backend you need to build digilib using the storage-cdstar profile in Maven e.g. with -Pstorage-cdstar,servlet3,iiif-presentation and add the following to your digilib configuration:

<parameter name="docudirectory-class" value="digilib.io.CdstarArchiveDocuDirectory" />
<parameter name="storage-base-url" value="http://localhost:8080/v3" />
<parameter name="storage-auth-username" value="someuser" />
<parameter name="storage-auth-password" value="somepassword" />

storage-base-url is the base URL of your CDSTAR server. storage-auth-username is the username and storage-auth-pqssword is the password for basic authentication with the CDSTAR server.

digilib tries to read the size of each image from the exif:Image.ImageHeight and exif:Image.ImageWidth keys in the file metadata to reduce the number of HTTP reqests to the CDSTAR server.

Other options

<parameter name="default-errmsg-type" value="image" />

Defines how errors are presented to the user. Allowed values are code, image and text.

image sends an error-image as error code (see denied-image, error-image, notfound-image parameters).
code sends an HTTP error code, which may result in a broken image display in the browser.
text sends a plain-text error message, which may result in a broken image display in the browser.

<parameter name="img-diskcache-allowed" value="false" />

Enables the use of a disk cache for the image toolkit. Using the disk cache may leak file handles and lead to resource issues if digilib runs for a long time.

<parameter name="log-config-file" value="log4j-config.xml" />

Location of the logging configuration file. The current logging library is Log4J 1.2.

Options for developers

Using these options you can replace default classes used by digilib with your own implementations to change the behaviour of digilib.

<parameter name="docuimage-class" value="digilib.image.ImageLoaderDocuImage" />

Class of the DocuImage instance. You can replace the digilib.image.DocuImage implementation to use a different image toolkit than Java ImageIO. (There are deprecated alternative implementations in the common-jai, common-imagej and common-bioformats modules.)

<parameter name="docuimage-hacks" value="" />

Text string to selectively enable specific Hacks in the DocuImage implementation (see the source)

<parameter name="filemeta-class" value="digilib.meta.IndexMetaFileMeta" />
<parameter name="dirmeta-class" value="digilib.meta.IndexMetaDirMeta" />

Classes of the digilib.meta.FileMeta and digilib.meta.DirMeta implementations. You can change these implementations to change the way digilib finds metadata about image files.

IndexMetaFileMeta and IndexMetaDirMeta read metadata from index.meta and *.meta XML files according to the index meta standard.

<parameter name="docudirectory-class" value="digilib.io.BaseDirDocuDirectory" />

Class of the digilib.io.DocuDirectory implementation. You can change this implementation to change the way digilib finds image files (including different resolutions).