Project

General

Profile

Actions

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
    

Updated by Alexander Watzinger 7 months ago · 6 revisions

Also available in: PDF HTML TXT