Configuration

The Cantaloupe image server is configured through a .properties file and some environment variables.

The Github repository holds a sample file with all the available options, their default value, and a short description.

To configure your own Cantaloupe, you can start from that file (as recommended per the official website) and simply set a local path to expose your images.

Sample configuration

We use a simplified configuration file which enables the following features:

  • IIIF v2 and v3 endpoints;

  • Debug logging;

  • Stack traces on error pages (which may not be suitable in production for your use case);

  • Using a local MinIO server as source for image;

  • Exposing all the buckets on that S3-compatible server;

  • Caching the generated info.json;

  • Caching the rendered images;

  • Using an S3 bucket to store all cached files;

  • Using Progressive JPEG algorithm for faster rendering.

Expose local files

To expose local files instead of an S3 bucket, you need to:

  1. Set source.static = FilesystemSource to enable the local file lookup.

  2. Set FilesystemSource.lookup_strategy = BasicLookupStrategy so that Cantaloupe directly uses local files (instead of using an external script when ScriptLookupStrategy is used).

  3. Set FilesystemSource.BasicLookupStrategy.path_prefix = /path/to/images/ where you replace /path/to/images/ towards a folder where your images are stored.

You need to add a trailing slash to path_prefix value, otherwise the generated paths will be invalid and you’ll get HTTP 404 errors.

A sample configuration file is available.

Expose files on a S3 bucket

To expose files on a S3 bucket (meaning from an S3-compatible hosting service, either local or from a cloud provider), you need to:

  1. Set source.static = S3Source to enable the S3 bucket lookup;

  2. Set S3Source.BasicLookupStrategy.bucket.name = your-bucket-name where your-bucket-name must be replaced by the name of your bucket hosting your images;

  3. Set S3Source.endpoint = <URL> to the URL of your S3 service.

S3 credentials

As you may have noticed, the sample configuration does not hold any S3 credentials even though they are required to access any S3 bucket.

They are instead exposed as environment variables out of security concerns (not committed):

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

These credentials need read access to all the image files hosted on your bucket.

Expose all available buckets

Our docker build of Cantaloupe expose a custom plugin that allows an administrator to expose all available buckets through Cantaloupe. The url must contain the name of the bucket as the first part of the IIIF path.

For example if your S3 bucket sample-bucket holds an image named test.jpg, you’ll access it through: http://<SERVER_URL>/sample-bucket%2Ftest.jpg

The / character in the IIIF image path is replaced by its url-encoded value %2F.

To enable multiple buckets support, you need to:

  1. Set source.static = S3Source to enable the S3 bucket lookup;

  2. Set S3Source.lookup_strategy = ScriptLookupStrategy to use our custom plugin;

  3. Set S3Source.BasicLookupStrategy.bucket.name = to explicitly disable the single bucket usage described above;

  4. Set S3Source.endpoint = <URL> to the URL of your S3 service.

Use S3 bucket as cache

You can also use a dedicated single S3 bucket to host your cached files:

  1. Set cache.server.derivative = S3Cache to enable caching on a S3 bucket;

  2. Set S3Cache.endpoint = <URL> to the URL of your S3 service;

  3. Set S3Cache.bucket.name = <BUCKET> to the name of your caching bucket.

Only one set of S3 credentials is currently supported by Cantaloupe, so the credentials used to read images must also be able to read & write on the caching bucket.