IIIF Image API Server

Image API Server is responsible to deliver the images.

Since OpenAtlas relies on Debian packages, we recommend to use IIPImage as IIIF Image API. But any other working IIIF Image API Server can be used, if it can handle Tiled Multi-Resolution TIFF and uses a folder to handle the images.

For installation of the IIPImage server see install notes of OpenAtlas.

Installing Cantaloupe 5 on Debian

  1. Check if Java 11 is installed, if not install default-jre
    java -version
    -bash: java: command not found
    sudo apt install default-jre
  2. Download cantaloupe /var/www/ and extract it, and rename it for easier use.
    cd /var/www
    7z x
    mv cantaloupe-5.0.5 cantaloupe
  3. Make a copy of without .sample and open it.
    cd cantaloupe
  4. Set FilesystemSource.BasicLookupStrategy.path_prefix to the path, where the images are.
    FilesystemSource.BasicLookupStrategy.path_prefix = /var/www/iiif/
  5. Additionally you can set "endpoint.admin.enabled" to true, to get access to the config via the browser.
    # Enables the Control Panel, at /admin.
    endpoint.admin.enabled = true
    endpoint.admin.username = admin
    endpoint.admin.secret = password

Apache config

  1. Enable headers and proxy_http
    sudo a2enmod headers
    sudo a2enmod proxy_http
  2. Create a new Apache2 config and enable the site. You can either use an own domain or an existing one with the port 8182(http)/8183(https)
    sudo vim /etc/apache2/sites-available/cantaloupe.conf

    <VirtualHost *:80>
      # X-Forwarded-Host will be set automatically by the web server.
      RequestHeader set X-Forwarded-Proto "https" 
      RequestHeader set X-Forwarded-Port "80" 
      RequestHeader set X-Forwarded-Path /
      ServerName apache-server
      AllowEncodedSlashes NoDecode
      ErrorLog        /var/log/apache2/cantaloupe_error.log
      CustomLog       /var/log/apache2/cantaloupe_access.log combined
      ProxyPass / http:// nocanon
      ProxyPassReverse /
      ProxyPassReverseCookieDomain apache-server
      ProxyPreserveHost on

    sudo a2ensite cantaloupe.conf
    sudo service apache2 restart
  1. If you use certbot, you can convert the certificate to an .pfx file. First create a folder in /etc/:
    sudo mkdir /etc/cantaloupe/
    openssl pkcs12 -export -out /etc/cantaloupe/ssl-certificate.pfx -inkey /etc/letsencrypt/live/ -in /etc/letsencrypt/live/ -certfile /etc/letsencrypt/live/
    sudo chown bkoschicek:www-data /etc/cantaloupe/ssl-certificate.pfx
  2. Change the settings either at the admin interface or config:
    # !! Configures the HTTPS server. (Standalone mode only.)
    https.enabled = true =
    https.port = 8183
    # !! Available values are `JKS` and `PKCS12`. (Standalone mode only.)
    https.key_store_type = PKCS12
    https.key_store_password = PASSWORD
    https.key_store_path = /etc/cantaloupe/ssl-certificate.pfx
    https.key_password = PASSWORD
  3. Again restart Apache, and you can visit cantaloupe with

Cantaloupe as Debian Service

  1. Open a terminal and create a systemd service unit file for Cantaloupe. You can name the file cantaloupe.service:
    sudo vim /etc/systemd/system/cantaloupe.service
  1. Add the following content to the cantaloupe.service file:
    Description=Cantaloupe Image Server
    ExecStart=/usr/bin/java -Dcantaloupe.config=/var/www/cantaloupe/ -Xmx2g -jar /var/www/cantaloupe/cantaloupe-5.0.5.jar
  2. Enable and start the Cantaloupe Service:
    sudo systemctl daemon-reload
    sudo systemctl enable cantaloupe.service
    sudo systemctl start cantaloupe.service

Installation on Windows (development only)

Since IIPServer is not so easy to install on Windows, and we don't really need it for development, I suggest to work with Cantaloupe to get an on-the-fly IIIF server.

  • Install vips and restart your PC (vips.exe should be in your PATH variable)
    scoop install main/libvips
  • Download Cantaloup
  • Extract it somewhere easy to find, e.g. C:\cantaloupe-5.0.5
  • Copy C:\cantaloupe-5.0.5\ and rename it to
  • Open and add a path where the image files are to FilesystemSource.BasicLookupStrategy.path_prefix e.g.
    FilesystemSource.BasicLookupStrategy.path_prefix = C:\Users\bkoschicek\PycharmProjects\iiif\
  • Open "GitBash" (or try to get it working in PowerShell), navigate to the root folder of Cantaloupe and start it with (leave the bash open!)
    java -Dcantaloupe.config=C:/cantaloupe-5.0.5/ -Xmx2g -jar cantaloupe-5.0.5.jar
  • If a image is in the give folder (e.g. C:\Users\bkoschicek\PycharmProjects\iiif\) you can view the info.json with:

    and the image with

Updated by Alexander Watzinger 7 months ago · 6 revisions

Also available in: PDF HTML TXT