This version of the manual refers to an earlier version of the software.

Getting Started


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


The distribution archive bundles a sample configuration file, named Do not edit this file—create a copy and edit that. The documentation refers to this file as, but it can be named anything.

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


Cantaloupe 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 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. If you choose to run other applications in the same container, be aware of this and test all of your applications to ensure they are working correctly.


From the command prompt (macOS/Linux):

java -Dcantaloupe.config=/path/to/ -Xmx2g -jar Cantaloupe-3.4.x.war

From the command prompt (Windows):

java -Dcantaloupe.config=C:\path\to\ -Xmx2g -jar Cantaloupe-3.4.x.war

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

Servlet Container

Copy the Cantaloupe-3.4.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/ (Unix) or bin/setenv.bat (Windows) inside the main Tomcat folder:


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


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

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-3.4.x/iiif/2/image.tif/info.json
  • http://localhost:8080/Cantaloupe-3.4.x/iiif/2/image.tif/0,0,200,200/full/0/default.jpg


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


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