Overview

This is a personal note on how to launch Cantaloupe, a IIIF image server, on EC2.

https://cantaloupe-project.github.io/

Additionally, I introduce an example of using Delegate Methods to add restrictions on image download size. Specifically, I address cases where an error occurs when trying to retrieve full-size images using /full/full/.

https://cantaloupe-project.github.io/manual/5.0/access-control.html

Setting Up Cantaloupe

Creating an EC2 Instance

I created an EC2 instance with the platform set to Ubuntu, instance type set to t2.medium, and storage set to 8GB.

As a result, an EC2 instance with the following “Public IPv4 Address” was created.

54.172.71.20

SSH

Connect to the launched EC2 instance via SSH. After connecting, set the root user password with the following command.

Installing Java

Install Java using the following commands.

Downloading Cantaloupe

Download Cantaloupe using the following commands.

Configuration

Edit the configuration file “cantaloupe.properties” using the following commands.

Use a command like vi cantaloupe.properties to specify the folder where images are stored.

Starting Cantaloupe

Cantaloupe will start at a URL like the following.

http://54.172.71.20:8182/

Placing Images

Server-Side Work

Create a folder to store images at /home/ubuntu/images as the ubuntu user.

Local Work

Use the following notebook, for example, to download a pyramid tiled TIF locally.

Then, if you downloaded converted.tif, upload the image to the server using a command like the following.

Once the image is uploaded to the server, you can retrieve the info.json at a URL like the following.

http://54.172.71.20:8182/iiif/3/converted.tif/info.json

A URL like http://54.172.71.20:8182/iiif/3/converted.tif also redirected properly.

Furthermore, by changing /3/ to /2/ as shown below, you can retrieve the Image API v.2 info.json.

http://54.172.71.20:8182/iiif/2/converted.tif

Interim Summary

With the settings so far, the minimum Cantaloupe setup is complete. HTTPS support and other configurations are needed separately, but I hope to cover those methods in other articles.

Handling Large Images: Enabling max_pixels

For example, when targeting “Hyakki Yako-zu” (Night Parade of One Hundred Demons, held at the University of Tokyo General Library), the following URL shows that the size is “79508 x 3082”.

https://iiif.dl.itc.u-tokyo.ac.jp/iiif/2/hyakki%2Fimages%2Fhyakki.tif/info.json

This Pyramid Tiled TIFF can be downloaded from the following GitHub repository.

https://github.com/nakamura196/ptif_sample/blob/main/hyakki.tif

If you upload this file as-is and try to retrieve the full-size image, the following error occurs.

http://54.172.71.20:8182/iiif/2/hyakki.tif/full/full/0/default.jpg

This is because max_pixels in cantaloupe.properties is set to 10,000,000, and 79,508 x 3,082 = 245,043,656 exceeds max_pixels.

Setting this max_pixels to 0 removes the upper limit, but I will describe that method later.

While specifying max_pixels has the advantage of reducing server load, the issue is that when users try to download full-size images in Universal Viewer or similar tools, they receive an error.

Therefore, I will explore how to handle cases where the max_pixels threshold is exceeded using the Delegate Methods provided by Cantaloupe.

Enabling Delegate Methods

Set delegate_script.enabled to true in cantaloupe.properties. Also specify delegate_script.pathname. Here, we assume the home directory of the ubuntu user.

Additionally, copy the sample script as the ubuntu user.

Updating the Script

Update the authorize method in the delegates.rb script as follows.

With the above, when a request is made with a URL containing /full/full/ and it exceeds the max_pixels value, it redirects to a URL containing /full/max/. This way, no error is returned, and the image is downloaded at the size specified by max_pixels.

Handling Large Images: Disabling max_pixels

As an alternative to the above method, you can also disable max_pixels. Specifically, set max_pixels as follows.

With this setting, depending on the server specs, you can use it without worrying about max_pixels.

Note that on the t2.medium instance used in this article, downloading failed when specifying large width values due to java.lang.OutOfMemoryError: Java heap space errors.

On the other hand, with a higher-spec server, you don’t need to worry about heap memory, but when trying to download the aforementioned “Hyakki Yako-zu” at full size (URL containing /full/full/), the download still failed as shown below.

This appeared to be caused by hitting the maximum JPEG size limit.

To address this, by modifying the authorize method in the delegates.rb script as follows, images can be downloaded with a specified maximum width or height.

However, with this setting, since maxArea and maxWidth are not included in info.json, images smaller than the width and height stated in info.json may be downloaded even when accessing with a URL containing /full/full/, so this is not considered an appropriate approach.

The advantage is that you don’t need to specify max_pixels (the product of width and height), but it needs to be examined whether this conforms to the IIIF specification.

https://iiif.io/api/image/3.0/

Summary

In this article, I introduced how to set up Cantaloupe.

I also introduced using Delegate Methods as an exceptional approach for downloading large images. By leveraging Delegate Methods, it appears possible to achieve things like allowing only authenticated users to download large images.

This time I introduced an unconventional usage, but I hope to investigate more Delegate Methods use cases in the future.

I hope this article is helpful for building a IIIF image server using Cantaloupe.

Please note that there may be incorrect understandings or descriptions, so I would appreciate any correction comments.