Installing Cantaloupe IIIF Server for Omeka on Debian 12 with HestiaCP

Step-by-step guidance for deploying Cantaloupe 5, wiring it through HestiaCP Nginx, and integrating it with Omeka S.

Infrastructure IIIF Digital Collections Omeka

Last updated:

Overview

Cantaloupe is a Java-based image server that exposes IIIF-compliant APIs for delivering tiled and deep-zoom imagery. This procedure is adapted from documentation on the OpenAtlas wiki.

This page documents a procedure for a very particular set of circumstances:

  • Installing Cantaloupe for use as an IIIF Server for Omeka-S
  • Debian 12
  • Using HestiaCP control panel

Adapt as necessary, use at your own risk!

Prerequisites

Before you begin, make sure you have:

  • A Debian 12 server with sudo access.
  • HestiaCP is installed.
  • Omeka-S is installed and working.

Step 1: Install the Java Runtime

Cantaloupe 5 depends on Java 17. Confirm whether Java is installed and add the default OpenJDK runtime if needed.

java -version
sudo apt install -y default-jre

In addition, we need to install the OpenJP2 libraries.

sudo apt install -y libopenjp2-7 libopenjp2-7-dev libopenjp2-tools

Step 2: Download and Unpack Cantaloupe 5

Fetch the 5.0.7 release (the latest as of this writing) and extract it under /var/www. The resulting directory is renamed to a shorter cantaloupe path for convenience.

cd /var/www
sudo wget https://github.com/cantaloupe-project/cantaloupe/releases/download/v5.0.7/cantaloupe-5.0.7.zip
sudo unzip cantaloupe-5.0.7.zip
sudo mv cantaloupe-5.0.7 cantaloupe

If /var/www is owned by root (the default on Debian), keep using sudo for these commands or adjust ownership to match the service account that will run the process.

Step 3: Create the Runtime Configuration

Cantaloupe ships with a sample configuration that must be copied and customized. Switch into the installation directory, duplicate the sample file, and edit the new configuration.

cd /var/www/cantaloupe
sudo cp cantaloupe.properties.sample cantaloupe.properties
sudo nano cantaloupe.properties

Set the filesystem source path so that the server can locate your Omeka-S original files. Assuming we are using HestiaCP, this might be something like /home/user/web/myomekawebsite.org/public_html/files/original.

FilesystemSource.BasicLookupStrategy.path_prefix = /home/user/web/myomekawebsite.org/public_html/files/original/

Optional but recommended: enable the admin control panel to simplify future tweaks through the browser.

endpoint.admin.enabled = true
endpoint.admin.username = admin
endpoint.admin.secret = password

Choose stronger credentials before opening the admin endpoint to untrusted users.

By default, JP2 processing will be via Kakadu, but the licensing makes this difficult and prohibitive, so we’re going to use OpenJP2.

processor.selection_strategy = ManualSelectionStrategy
processor.ManualSelectionStrategy.jp2 = OpenJpegProcessor

At this point, logging is not set up. We do not go into that here. You can use journalctl to see recent messages from the service.

Step 4: Register a systemd Service

Running Cantaloupe through systemd ensures it starts automatically and restarts after failures. Create the unit file at /etc/systemd/system/cantaloupe.service.

sudo nano /etc/systemd/system/cantaloupe.service

Copy the following information into the 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.7.jar
Restart=on-failure
User=root
WorkingDirectory=/var/www/cantaloupe/

[Install]
WantedBy=multi-user.target

Notice that this runs the service as root. For production deployments you may wish to create a dedicated service account and adjust the User, WorkingDirectory, and file permissions accordingly.

Reload systemd, enable the service so it starts on boot, and then launch it immediately.

sudo systemctl daemon-reload
sudo systemctl enable cantaloupe.service
sudo systemctl start cantaloupe.service

Confirm that the JVM is running and listening on port 8182:

sudo systemctl status cantaloupe.service

Step 5: Create a HestiaCP Nginx Template

HestiaCP uses reusable template pairs (.tpl for HTTP, .stpl for HTTPS) to build per-domain Nginx configurations. Copy the default template and convert it into a dedicated reverse proxy that forwards traffic to the local Cantaloupe listener on port 8182.

sudo nano /usr/local/hestia/data/templates/web/nginx/cantaloupe.tpl

Copy this into the cantaloupe.tpl file:

server {
        listen      %ip%:%proxy_port%;
        server_name %domain_idn% %alias_idn%;
        error_log   /var/log/%web_system%/domains/%domain%.error.log error;

        include %home%/%user%/conf/web/%domain%/nginx.forcessl.conf*;

        location ~ /\.(?!well-known\/|file) {
                deny all;
                return 404;
        }

        location / {
                proxy_pass http://127.0.0.1:8182;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Port $server_port;
                proxy_set_header X-Forwarded-Proto $scheme;
        }

        include %home%/%user%/conf/web/%domain%/nginx.conf_*;
}

Now create the cantaloupe.stpl file.

sudo nano /usr/local/hestia/data/templates/web/nginx/cantaloupe.stpl

Copy this into the cantaloupe.stpl file:

server {
        listen      %ip%:%proxy_ssl_port% ssl;
        server_name %domain_idn% %alias_idn%;
        error_log   /var/log/%web_system%/domains/%domain%.error.log error;

        ssl_certificate     %ssl_pem%;
        ssl_certificate_key %ssl_key%;
        ssl_stapling        on;
        ssl_stapling_verify on;

        # TLS 1.3 0-RTT anti-replay
        if ($anti_replay = 307) { return 307 https://$host$request_uri; }
        if ($anti_replay = 425) { return 425; }

        include %home%/%user%/conf/web/%domain%/nginx.hsts.conf*;

        location ~ /\.(?!well-known\/|file) {
                deny all;
                return 404;
        }

        location / {
                proxy_pass http://127.0.0.1:8182;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Port $server_port;
                proxy_set_header X-Forwarded-Proto $scheme;
        }

        proxy_hide_header Upgrade;

        include %home%/%user%/conf/web/%domain%/nginx.ssl.conf_*;
}

HestiaCP will automatically recognize the new cantaloupe template. No restart required.

Step 6: Provision the IIIF Domain in HestiaCP

Add a dedicated subdomain (for example iiif.myomekawebsite.org) to serve as the reverse proxy to the Cantaloupe server.

In the HestiaCP admin panel, switch to the user that owns the main Omeka-S website, browse to Web → Add Web Domain, and create the domain. You don’t need DNS or mail service for this subdomain. But you will need to add a DNS record for the subdomain to the main DNS zone for the domain.

Once the domain is created, edit it. Enable SSL, and check the LetsEncrypt option. Save to activate SSL and fetch a certificate.

Edit the domain again, click Advanced Options and for Proxy Template choose cantaloupe.

Step 7: Install Required Omeka S Modules

Install these three modules in the usual way:

  1. Iiif Server
  2. Image Server
  3. Universal Viewer

Step 8: Configure Omeka S to Use Cantaloupe

With the modules active, point Omeka S at the new IIIF endpoint:

  1. Navigate to Modules → Image Server → Configure.
Media identifier = Filename with extension (all)
Tiling processing mode = Use an external imaging server
  1. Go to Modules → IIIF Server → Configure.
[External image server]
External image server base url = https://iiif.myomekawebsite.org
Media identifier = Filename with extension (all)

Add a new item to Omeka-S, upload a suitable source image, and verify that Universal Viewer displays the image correctly.

At this point Cantaloupe 5 is serving content through HestiaCP and Omeka S is publishing IIIF manifests that reference the new image server.