Hymir is a Java based IIIF Server. It is based on "IIIF Image API Java Libraries" and "IIIF Presentation API Java Libraries" projects (see https://github.com/dbmdz)
Clone or download


Hymir IIIF Server

Build Status MIT License GitHub release Codacy Badge codecov Maven Central

Hymir is a Java based IIIF Server. It is based on our IIIF API Java Libraries (Java implementations of the IIIF specifications).


  • IIIF Image API 2.1 compliant (see http://iiif.io/api/image/2.1/).
  • IIIF Presentation API 2.1 compliant (see http://iiif.io/api/presentation/2.1/).
  • On the fly image processing. No additional pregenerated (pyramid zoom) images are needed. No additional storage consumption.
  • Can simply be run as a standalone IIIF server from the JAR, no application server necessary
  • Spring based modular, extendable, easy to maintain enterprise architecture.
  • Highly customizable image storage and identifier resolving: Access to images over project specific Resolver-plugin mechanism.
  • Support for Filesystem- and HTTP-Image-Repositories (own protocols can be added by providing specific resolver)
  • Pluggable Manifest generation: implement your own mapping from project specific structure metadata to a standard Manifest object.
  • Embedded IIIF Image Viewer (for out of the box viewing of served images): OpenSeadragon 2.3.1 (see "Usage" below)
  • Embedded IIIF Presentation Viewer: Mirador 2.6.0 (see "Usage" below)
  • Direct Manifest access (see "Usage" below)

Supported image formats

Format Reading Writing Dependencies
JPEG [x] [x] libturbojpeg (optional, but recommended)
JPEG2000 [x] [ ] libopenjp2 (>= 2.3 recommended)
TIFF [x] [x]
PNG [x] [x]
BMP [x] [x]
GIF [x] [x]


  • Server with minimum 4GB RAM.
  • Java 8


Download hymir-<version>-exec.jar from the GitHub releases page.


Run the downloaded application with java -jar hymir-<version>-exec.jar

  • Example with Logstash-JSON-logging to ./hymir.log:
$ java -jar hymir-3.0.1-exec.jar
  • Example with logging to console:
$ java -jar hymir-3.0.1-exec.jar --spring.profiles.active=local
  • Example with logging to console and custom file resolving rules:
$ java -jar hymir-3.0.1-exec.jar --spring.profiles.active=local --rules=file:/etc/hymir/rules.yml

Access Hymir GUI (e.g. http://localhost:9000/).


Using the TurboJPEG backend

By default, a Java-based image processing backend is used. If you want better performance, it is recommended to use the native image processing backend that is based on TurboJPEG. For this, you will have to install the TurboJPEG native library, on Ubuntu libturbojpeg.



(Configured in logback-spring.xml)

The default logging file is configured as ./hymir.log in Logstash-JSON-format.

If you want human readable logging to console use "--spring.profiles.active=local" on start command line.

Image and presentation manifest resolving

Based on unique resource identifiers the server tries to resolve identifiers to a "file:" or "http:" path. The resolving rules (one rule per line) are configurable with regular expressions in YML-files.

You can pass the path to your custom resolving rules with the --rules=/path/to/rules.yml option.

Example file "rules.yml":

# This configuration file defines a list of patterns with one ore more substitutions.
# These are used for resolving IDs to a concrete URI, e.g. on the file system, the
# classpath or even a remote HTTP endpoint.
# You can specify multiple substitutions, the resolver will try to match them against
# the desired MIME type and return all that matches
# The repository will then verify which of these URIs are actually readable and return
# the first matching substitution.
# In the example below, we have two MIME types (tiff/jpeg) and for JPEG two resolutions
# in decreasing order of quality, so that the higher-resolution image will be chosen
# if it is available.
- pattern: ^bsb(\d{8})_(\d{5})$
    - 'file:/var/local/bsb$1/images/original/bsb$1_$2.tif'
    - 'file:/var/local/bsb$1/images/300/bsb$1_$2.jpg'
    - 'file:/var/local/bsb$1/images/150/bsb$1_$2.jpg'

# A simpler example with just a single substitution pattern (for resolving IIIF-manifests)
- pattern: ^bsb(\d{8})$
    - 'file:/var/local/bsb$1/manifest/bsb$1.json'

Use Case:

In the simplest case you just want to serve images of a directory, supporting just the image API. Let's assume you have a bunch of jpg-files residing in the directory "/home/hans/my_images". The files are named "image_001.jpg", "image_002.jpg", ...

You could take the filename as identifier. The rules.yml then is just:

- pattern: ^(.*)$
    - 'file:/home/hans/my_images/$1'

An image API url example:


To make it more safe (avoid serving of other files) and shorter, you could decide to shorten the identifier and concatenate the file extension in the rule:

- pattern: ^(.*)$
    - 'file:/home/hans/my_images/$1.jpg'

An image API url example:



Monitoring endpoints under http://localhost:9001/monitoring (HAL-Browser-GUI), authentication by default: admin/secret (configurable in application.yml)



  • Install git client
  • Install Java JDK 1.8 or above
  • Install Apache Maven buildttool
$ cd ~/development
$ git clone git@github.com:dbmdz/iiif-server-hymir.git
$ cd iiif-server-hymir
$ mvn clean install

Executable JAR-file is in target directory.

On systems without installed libturbojpeg test fail. To build without tests, execute:

$ mvn clean install -DskipTests=true

To install libturbojpeg on Debian based systems:

$ sudo apt install libturbojpeg