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.

• 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\cantaloupe.properties.sample and rename it to cantaloupe.properties
• Open cantaloupe.properties 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"https://gitforwindows.org/ (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/cantaloupe.properties -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:
  

  http://localhost:8182/iiif/2/image.jpg/info.json
  

  
  and the image with
  

  http://localhost:8182/iiif/2/image.jpg/full/full/0/default.jpg