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
wget https://github.com/cantaloupe-project/cantaloupe/releases/download/v5.0.5/cantaloupe-5.0.5.zip
7z x cantaloupe-5.0.5.zip
mv cantaloupe-5.0.5 cantaloupe
  3. Make a copy of cantaloupe.properties.sample without .sample and open it.
    cd cantaloupe
cp cantaloupe.properties.sample cantaloupe.properties
vim cantaloupe.properties
  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:// YOUR-DOMAIN.at:8182/ nocanon
  ProxyPassReverse / http://YOUR-DOMAIN.at:8182/
  ProxyPassReverseCookieDomain YOUR-DOMAIN.at apache-server
  ProxyPreserveHost on
</VirtualHost>


    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/YOUR-DOMAIN.at/privkey.pem -in /etc/letsencrypt/live/YOUR-DOMAIN.at/cert.pem -certfile /etc/letsencrypt/live/YOUR-DOMAIN.at/fullchain.pem
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.host = 0.0.0.0
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 http://YOUR-DOMAIN.at:8183

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:
    [Unit]
Description=Cantaloupe Image Server
After=network.target

[Service]
ExecStart=/usr/bin/java -Dcantaloupe.config=/var/www/cantaloupe/cantaloupe.properties -Xmx2g -jar /var/www/cantaloupe/cantaloupe-5.0.5.jar
Restart=on-failure
User=root
WorkingDirectory=/var/www/cantaloupe/

[Install]
WantedBy=multi-user.target
  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.