IIIF server implementation

In case you have an old computer available, with minimum hardware specifications: 64-bit 1 Ghz CPU, 1 Gb RAM memory and 5 Gb harddisk space, and you want to repurpose that, think of experimenting with IIIF by installing Ubuntu server v22.04 LTS and Cantaloupe v5.0.7 on it. Below you will find a short tutorial on how to do this.

Step 1: Ubuntu server installation

The first step is to download the iso file for Ubuntu server v22.04 LTS (ubuntu-22.04.5-live-server-amd64.iso) over here and to extract that on a DVD or a USB-drive, depending on what works best for the computer you intend to use as a server. Next, make sure that computer is able to start from the DVD or USB-drive (check the BIOS option for that) and reboot it with the DVD or USB-drive inserted. You will soon see the first messages of the Ubuntu server installation appear on your screen.

When the message: "Try or Install Ubuntu server" appears highlighted on your screen, click on it to start the installation process.
After a while, you will be asked to choose your language, by default "English" is selected, you can accept this (or any other available language you select from the list instead) by clicking on the "Enter"-key.
Next, you will be asked to "Update to the new installer" or "Continue without updating", the latter is selected by default, click on the "Enter"-key to accept this.
Next, you will be asked to choose your keyboard layout, it will be detected automatically, so usually "English (US)" as well as "Done" at the bottom of the screen is selected, so click on the "Enter"-key to accept this.
Next, you will be asked to "Choose the base for the installation", by default: "Install Ubuntu Server" as well as "Done" at the bottom of the screen are selected, so click on the "Enter"-key to accept this.
Next, the installer will automatically detect and configure your network connection via DHCP

Note: in case your internet account runs on a fixed IP-address and you want the server to have its own IP-address, within the range provided by your internet provider, then choose to manually configure the network connection for the server. You can do this by selecting the name of the network card and clicking on the "Enter"-key. In the menu that opens next, select "Edit IPv4", then a new menu will open in which you can select "Manual". This opens a form in which you can provide all information needed to run the server with a static IP-address. Remember that in case you want the server to be availble via the internet, you have to configure port frwarding for the server and its specific IP-address in your router.

Next, you will be asked whether you want to use a "Proxy address". An empty field is provided for this and by default "Done" is selected at the bottom of the screen. You can skip this by simply clicking on the "Enter"-key.
Next, the installer will check whether the "mirror address" for downloading necessary files is valid, if this is Ok, the cursor will be put on "Done" at the bottom of the screen and then you can proceed by clicking on the "Enter"-key.
Next, the installer will ask you whether you want to use the entire hard disk or only a part of it and by default "Use an Entire Disk" is selected , the name and type of your harddisk is mentioned and the option "Set up this disk as an LVM group" selected. Furthermore the option "Encypt the LVM group with LUKS" is deselected. Accept these choices by putting the cursor on "Done" at the bottom of the screen and clicking on the "Enter"-key.
Next, the installer will calculate what partitions to create and present this information to you for a last check. The cursor is already on "Done" at the bottom of the screen, so you can accept this by clicking on the "Enter"-key.
Next, a menu will be shown in which you need to make sure this is Ok with you ("Confirm destructive action", i.e.: erase and format the whole harddisk), so select "Continue" and click on the "Enter"-key.
Next, the installer will ask you to fill in some profile information: your name, your server's name, a user name and a password. Provide this information and confirm this by clicking on "Done" at the bottom of the screen and on the "Enter"-key.
Next, you will be asked to upgrade to Ubuntu Pro, by default "Skip for now" is selected and the cursor points at "Continue", accept this by clicking on the "Enter"-key.
Next, you will be asked to install OpenSSH. This allows you to access the server via another device (via: ssh [username]@[ip-address] in a terminal window), so select the option "Install OpenSSH server", but deselect "Import SSH keys" (importing those from Github doesn't really work properly in my experience), then put the cursor on "Done" at the bottom of the screen and click on the "Enter"-key to continue.
Next, you will be given the opportunity to install extra software (like: Nextcloud, Docker, Postgresql10, Heroku, etc.). We will skip this, so put the cursor on "Done" at the bottom of the screen and click on the "Enter"-key to continue.

Now, the installation process will continue and after a while the option: "Reboot now" will appear at the bottom of the screen. Select this option and click on the "Enter"-key. The computer will start rebooting and asks you to remove the installation medium (DVD or USB-drive) during this process. After a while the Ubuntu 22.04 server will start and you will be given the opportunity to login.

Step 2: Prepration for IIIF implementation

Note: you can run most of the following instructions/commands directly on the server once logged in, however it's also possible to do this on another computer. As explained above, you can do that by using the SSH access to the server, but it's more convenient to install a graphical interface for this such as Webmin (see below).

Activate and configure the firewall

First it's best to activate the build-in firewall on the server and that can be done by this command "sudo ufw enable".
Next, we need to tell the firewall that some ports on the server need to be accessible, for example port 22 for SSH access, port 10000 for the Webmin tool and port 8182 for the Cantaloupe IIIF application we're going to implement later, so run these commands to make sure these ports are available: "sudo ufw allow 22/tcp", "sudo ufw allow 10000/tcp" and: "sudo ufw allow 8182/tcp".
Then restart the firewall service using this command: "sudo ufw reload". You can check whether your commands for opening up the ports were successfull by using this command: "sudo ufw status". The three above mentioned ports will be mentioned in the list of "allowed" ports.

Install Webmin

To install Webmin you first need to fetch the packages which will enable this and you can do that using this command:
"wget -qO- https://download.webmin.com/jcameron-key.asc | sudo gpg --dearmor -o /usr/share/keyrings/webmin.gpg"
You can now add the Webmin repository with this key to the file "/etc/apt/sources.list". Open that file in the editor "Nano", using this command:
"sudo nano /etc/apt/sources.list"
Then add at the end of the file this line:
"deb [signed-by=/usr/share/keyrings/webmin.gpg] http://download.webmin.com/download/repository sarge contrib"
and save this file by using the comands: Ctrl+X, Yes, and the "Enter"-key.
Next, update this packages index using this command:
"sudo apt update"
Now you can finally install Webmin using this command:
"sudo apt install webmin"
The graphical Webmin interface for your Ubuntu 22.04 server is now availble on any computer by typing this url in a webbrowser: http://[IP-address server]:10000 and entering your login information (see above).

Note: you haven't set up an SSL certificate from a Certificate Authority on your server, so you will receive a "Not Secure" or "Connection is not private" error, depending on your browser. This informs you that the connection to your server is not secure. This error message is normal because Webmin is encrypted and secured with a self-signed certificate, and the browser does not recognise it since your server is not one of its known certificate authorities. Click the "Advanced"-button or "More information" depending on the browser, and choose to proceed.

figuur 1: Webmin interface.

Install Java

The IIIF application we are going to install on the Ubuntu 22.04 server is Cantaloupe, which is a Java application, so we need to have Java installed on the server.

The current version of Cantaloupe, version 5.0.7 (at the time of writing this: 20th of May 2025) needs Java version 17 or higher. So let's first check whether the server already has Java installed and if so, which version. For that you can use this command: "java --version".

The answer will probably be: "command 'java' not found, but can be installed with:" and then a list of commands to install possible Java versions will follow. We will pick the command for installing Java version 17, which is: "sudo apt install open-jdk-jre-headless", so enter this command, follow the instructions on the screen and Java 17 will be installed.

Step 3: Cantaloupe IIIF installation

Now let's finalise our IIIF server implementation by installing Cantaloupe.

Download the Cantaloupe v5.0.7 zip-file over here: https://cantaloupe-project.github.io/. Extract the zip-file locally, which will lead to this overview of files it contains:

figuur 2: Cantaloupe files.

Now follow these instructions in preparation to install Cantaloupe on the Ubuntu 22.04 server:

Copy the file "cantaloupe.properties.sample" to "cantaloupe.properties" and edit line 14 as follows:
"temp_pathname = /var/cantaloupe/temp"
Next, edit line 120 as follows (changing "false" into: "true"):
"endpoint.admin.enabled = true"
Then provide an admin password in line 122 as follows:
"endpoint.admin.secret = password"
Finally, change line 162 from this:
"FilesystemSource.BasicLookupStrategy.path_prefix = /home/myself/images/"
into this:
"FilesystemSource.BasicLookupStrategy.path_prefix = /var/cantaloupe/images/"

Next, save the file and delete the now superfluous file "cantaloupe.properties.sample".

Now rename the folder "cantaloupe-5.0.7" into: "cantaloupe" and upload it to the folder "/var" on the server via Webmin, using the options: "Tools > File Manager > File > Upload to current directory":

figuur 3: Webmin File Manager.

Make sure you have selected the option: "Directory Upload" before you click on the "Upload"-button:

figuur 4: Webmin Directory Upload.

Next, still in the Webmin option "File Manager", select the newly uploaded folder "cantaloupe" within the folder: "/var" and create in there a new folder called: "temp" (as registered in the "cantaloupe.properties"-file earlier), using the Webmin option: "File > Create new directory":

figuur 5: Webmin Create new directory "/var/cantaloupe/temp".

Next, still in the Webmin option "File Manager", go back to the folder: "/var" and create in there a new folder called: "cantaloupeimages" (also as registered in the "cantaloupe.properties"-file earlier), using the same option: "File > Create new directory":

figuur 6: Webmin Create new directory "/var/cantaloupeimages".

Finally, use the Webmin option "File Manager" to upload an image to the folder: "/var/cantaloupeimages":

figuur 7: Webmin Upload image.

Now it's time to start the Cantaloupe IIIF application following these steps, which you can perform either directly on the server or on any other computer using SSH access:

Once connected to the server, switch to 'root' access using this command: "sudo -s".
Go to the "/var/cantaloupe"-folder using this command: "cd /var/cantaloupe".
Next, start there the Cantaloupe IIIF application by entering this line: "java -Dcantaloupe.config=cantaloupe.properties -Xmx2g -jar cantaloupe-5.0.7.jar"

Your Cantaloupe IIIF image server has now started and you can access it like this:

For fetching a json file of an uploaded image: "http://[server's ip-address]:8182/iiif/2/[name of uploaded image+extension]/info.json"figuur 8: Cantaloupe IIIF image server - json file.

For fetching a the uploaded image itself: "http://[server's ip-address]:8182/iiif/2/[name of uploaded image+extension]/full/full/0/default.jpg"figuur 9: Cantaloupe IIIF image server, image file - 1.figuur 10: Cantaloupe IIIF image server - image file - 2.

For entering the Admin panel of your Cantaloupe IIIF image server (with username/password as provided in: "cantaloupe.properties"): "http://[server's ip-address]:8182/admin"figuur 11: Cantaloupe IIIF image server - Admin panel.