Getting Started

Requirements

The only absolute requirement is Java 8, 9, or 10—either the Oracle JRE or OpenJDK will work. Optional components, like particular sources, processors, or caches, may have additional requirements.

There is a bug when running under Java 9 that causes a barrage of harmless-but-annoying errors in the log. If you have a choice, consider using Java 8 or 10 instead.


Configuration

The distribution archive bundles a sample configuration file, named cantaloupe.properties.sample. Do not edit this file—create a copy and edit that. It can be named anything, but hereafter it will be referred to as cantaloupe.properties.

Next, open the file in a text editor and set FilesystemSource.BasicLookupStrategy.path_prefix to a folder path containing some images.


Running

The application is distributed as a custom WAR file that can be run standalone, using a built-in web server, or deployed to a Servlet container like Tomcat. If you have a choice, standalone mode is generally recommended, as it's more predictable and less prone to conflicts with other applications.

Multiple web applications running in a container share the same Java Virtual Machine (JVM) and can conflict with each other. The Image I/O library, for example, is configured globally, and Cantaloupe makes some runtime adjustments to it that other applications may not expect, and vice versa. If you choose to run other applications in the same container, be aware of this and test them all to ensure they work correctly.

Standalone

From a command prompt:

java -Dcantaloupe.config=/path/to/cantaloupe.properties -Xmx2g -jar cantaloupe-4.0.x.war
java -Dcantaloupe.config=C:\path\to\cantaloupe.properties -Xmx2g -jar cantaloupe-4.0.x.war

Assuming you have an image named image.tif, try accessing:

The -Xmx2g argument tells the JVM that it can use a maximum of 2 GB of heap space, which should be more than enough for evaluation purposes, but maybe not for production—see Memory Considerations.

Servlet Container

Copy the cantaloupe-4.0.x.war file to your container's web application folder. (In Tomcat, this is /webapps inside the main Tomcat folder.)

Add the -Dcantaloupe.config VM argument to your container, in the same format as in the standalone section. In Tomcat 8, this can be done by setting CATALINA_OPTS, located in bin/setenv.sh inside the main Tomcat folder:

export CATALINA_OPTS="$CATALINA_OPTS -Dcantaloupe.config=/path/to/cantaloupe.properties"

Add the -Dcantaloupe.config VM argument to your container, in the same format as in the standalone section. In Tomcat 8, this can be done by setting CATALINA_OPTS, located in bin/setenv.bat inside the main Tomcat folder:

set JAVA_OPTS=%JAVA_OPTS% -Dcantaloupe.config="C:\path\to\cantaloupe.properties"

Then, restart your container.

Assuming you have an image named image.tif, and a container listening on port 8080, try accessing:

  • http://localhost:8080/cantaloupe-4.0.x/iiif/2/image.tif/info.json
  • http://localhost:8080/cantaloupe-4.0.x/iiif/2/image.tif/0,0,200,200/full/0/default.jpg

Docker

The download archive doesn't include any Docker support files, but see these repositories for examples:


Deploying

Before deploying to production, see Deployment for some important notes.