Setting up Cantaloupe IIIF Image Server

Make sure you have installed the prerequisites.

Download Cantaloupe

For more information, checkout the Cantaloupe getting started guide.

Download Cantaloupe v4.1.3

Open and extract the zip file to your directory of choosing. We suggest ~/iiif-workshop.

Now change directory to that extracted directory

cd ~/iiif-workshop/Cantaloupe-4.1.3

Configure Cantaloupe

Now lets create a copy of the configuration file:

cp cantaloupe.properties.sample cantaloupe.properties

Now lets enable the admin panel where we will modify the rest of the settings.

Scroll to line 104, and change false to true. Also add a password.

# Enables the Control Panel, at /admin.
- admin.enabled = false
+ admin.enabled = true
- admin.secret =
+ admin.secret = yolo

Save the file.

Now lets try and start the server. Run this command from your Cantaloupe directory

java -Dcantaloupe.config=./cantaloupe.properties -Xmx2g -jar Cantaloupe-4.1.3.war

Now navigate to http://127.0.0.1:8182/iiif/2 in your browser.

You should see this:

server image

Congrats you successfully installed Cantaloupe!

Troubleshooting

If you don't see the screen above there are a few common problems that people have come across:

  • Lack of memory. You may see something like the following when you run the Cantaloupe java command:
Error occurred during initialization of VM
Could not reserve enough space for 2097152000000KB object heap

to fix this change the -Xmx parameter to something smaller e.g:

java -Dcantaloupe.config=./cantaloupe.properties -Xmx1g -jar Cantaloupe-4.1.3.war
  • Spaces in Windows. If you are using Windows ensure that there are no spaces in the directories above the Cantaloupe directory.

Admin panel

Also make sure you can get into the admin panel by navigating to http://127.0.0.1:8182/admin.

Use the username admin and the password you set previously.

admin panel

Configuring Cantaloupe to use your images.

Congrats now you have your image server up and running! We need to feed it some images to keep it happy!

Download some images

Go ahead and download a *.jpg image from the Internet into your Cantaloupe directory Cantaloupe-4.1.3. Here is one eddie.jpg that you can use.

Configure Cantaloupe to use the correct path

Now we need to configure Cantaloupe to use that image directory.

Navigate to the admin page http://127.0.0.1:8182/admin.

Click on "Source", then click "FilesystemSource" tab at the bottom of the page.

Next fill in Path Prefix to be ./

file resolver

and click Save.

Check it out in the browser

Now you should be able to navigate to an image's info.json response successfully.

Checkout http://127.0.0.1:8182/iiif/2/eddie.jpg/info.json

And if everything goes right, you should see an info.json response.

info json

Let's finally check it using the Leaflet-IIIF image api viewer.

Try this url: http://mejackreed.github.io/Leaflet-IIIF/examples/?url=http://127.0.0.1:8182/iiif/2/eddie.jpg/info.json

Notice how we added our local IIIF server's info.json response url as a parameter. This is used by IIIF Image API clients to understand how they can request images/tiles.

eddie in iiif

Cross our fingers, but you should see a picture of Eddie in a zoomable viewer.

You can also try this image with:

Last modified by Glen Robson 2021-10-07 10:23:23
Created by Glen Robson 2021-10-07 10:23:23

results matching ""

    No results matching ""