Cantaloupe Ubuntu 24.04

Search the Marketplace for Cantaloupe on Ubuntu 24.04 and choose your VM size. Attach an NSG that allows TCP 22 (SSH) from your management network. The NSG must also allow TCP 443 (the IIIF API) from the networks and applications that need to serve images.

In production, front the service with a CA-issued certificate (see Step 10).

RG="cantaloupe-prod"; LOCATION="eastus"; VM_NAME="cantaloupe-01" IMAGE_URN="sac1647283583153:cantaloupe-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name cantaloupe-vnet --address-prefix 10.90.0.0/16 --subnet-name cantaloupe-subnet --subnet-prefix 10.90.1.0/24 az network nsg create -g "$RG" --name cantaloupe-nsg az network nsg rule create -g "$RG" --nsg-name cantaloupe-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name cantaloupe-nsg --name allow-https --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 443 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:cantaloupe-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name cantaloupe-vnet --subnet cantaloupe-subnet --nsg cantaloupe-nsg --public-ip-sku Standard

ssh azureuser@<vm-ip>

Cantaloupe listens on loopback 127.0.0.1:8182. nginx fronts the IIIF API on port 443, and port 80 redirects to it. The /healthz endpoint is public. Every other endpoint requires your per-VM password.

sudo systemctl is-active cantaloupe nginx
sudo ss -tln | grep -E ':443 |:8182' curl -sk https://127.0.0.1/healthz

You should see both services active, the two listening sockets (Cantaloupe on loopback 8182, nginx on 443), and ok from the health endpoint. An unauthenticated IIIF request returns 401.

The password was generated on this VM's first boot and stored in a root-only file. Read it and keep it secret, because it authenticates every IIIF request. Then confirm that unauthenticated and wrong-password requests are rejected while the per-VM password succeeds.

sudo ls -l /root/cantaloupe-credentials.txt echo "no credentials -> HTTP $(curl -sk -o /dev/null -w '%{http_code}' https://127.0.0.1/iiif/3/sample.jpg/info.json)" echo "wrong password -> HTTP $(curl -sk -o /dev/null -w '%{http_code}' -u admin:wrong https://127.0.0.1/iiif/3/sample.jpg/info.json)"

The info note holds CANTALOUPE_URL, CANTALOUPE_USERNAME (admin) and CANTALOUPE_PASSWORD. It is owned by root:root with mode 0600. Unauthenticated and wrong-password calls return 401 because the nginx Basic Auth gate protects the whole IIIF surface.

Every IIIF resource has an info.json that describes the image's full dimensions and the sizes and tiles a client can request. An IIIF viewer reads it first to plan its deep zoom tiling. Load the per-VM password into a shell variable, then request the demo image's info.json.

export
CANTALOUPE_PW=$(sudo grep '^CANTALOUPE_PASSWORD=' /root/cantaloupe-credentials.txt | cut -d= -f2-)
curl -sk -u "admin:$CANTALOUPE_PW" https://127.0.0.1/iiif/3/sample.jpg/info.json | python3 -m json.tool

The response is an IIIF Image API 3.0 info.json. It contains the @context, an ImageService3 type, the full width and height (2000 x 1500 for the demo image), and the pyramid of sizes and tiles a viewer can request. To serve your own image, drop a file into /var/lib/cantaloupe/images/ and address it by filename.

The IIIF Image API encodes the region, size, rotation and quality you want directly in the URL, and Cantaloupe generates that derivative on the fly. Request the full image, a 500-pixel-wide thumbnail, and a 300 x 300 square crop of the demo image.

export
CANTALOUPE_PW=$(sudo grep '^CANTALOUPE_PASSWORD=' /root/cantaloupe-credentials.txt | cut -d= -f2-)
# Full image at native size curl -sk -u "admin:$CANTALOUPE_PW" "https://127.0.0.1/iiif/3/sample.jpg/full/max/0/default.jpg" -o full.jpg
# A 500 pixel wide thumbnail (aspect preserved)
curl -sk -u "admin:$CANTALOUPE_PW" "https://127.0.0.1/iiif/3/sample.jpg/full/500,/0/default.jpg" -o thumb.jpg
# A 300 x 300 square crop curl -sk -u "admin:$CANTALOUPE_PW" "https://127.0.0.1/iiif/3/sample.jpg/square/300,300/0/default.jpg" -o square.jpg identify full.jpg thumb.jpg square.jpg

Each request returns a JPEG rendered to exactly the region and size in the URL. The IIIF request syntax is {identifier}/{region}/{size}/{rotation}/{quality}.{format}. For example, .../sample.jpg/full/500,/0/default.jpg means the full image, scaled to 500 pixels wide, with no rotation and default quality, as JPEG.

Cantaloupe serves images from /var/lib/cantaloupe/images/ and uses the identifier as the filename. Copy an image in, set the ownership, and address it immediately. No restart or reindex is required.

export
CANTALOUPE_PW=$(sudo grep '^CANTALOUPE_PASSWORD=' /root/cantaloupe-credentials.txt | cut -d= -f2-) sudo cp /var/lib/cantaloupe/images/sample.jpg /var/lib/cantaloupe/images/myimage.jpg
sudo chown cantaloupe:cantaloupe /var/lib/cantaloupe/images/myimage.jpg curl -sk -o /dev/null -w 'myimage info.json -> HTTP %{http_code}\n' -u "admin:$CANTALOUPE_PW" https://127.0.0.1/iiif/3/myimage.jpg/info.json

For large collections, mount a dedicated data disk or a file share at /var/lib/cantaloupe/images/. Cantaloupe can also pull images from cloud object storage and databases through its other sources. See the upstream configuration reference for details.

The active configuration lives at /etc/cantaloupe/cantaloupe.properties. Edit it, then run sudo systemctl restart cantaloupe to apply changes.

Because the API is standard IIIF, any IIIF viewer can display these images with deep zoom. Point OpenSeadragon or Mirador at the image's info.json URL and supply the Basic Auth credentials. For example, use https://<vm-ip>/iiif/3/sample.jpg/info.json.

The viewer reads the tile pyramid from info.json. It then requests only the tiles in view as the user pans and zooms.

The image ships with a per-VM self-signed certificate, so the API is encrypted from first boot. For production, point a DNS record at the VM and replace the certificate with a CA-issued one using certbot.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>

After issuance, restrict the NSG so that only 443 (and 22 from your management network) is reachable. Then serve images over https://<your-domain>/iiif/3/....