Getting Started

Requirements

The only absolute requirement is Java 8, 10, or 11. Later Java versions may also work, but are untested. Optional components, like particular sources, processors, or caches, may have additional requirements.


Configuration

The distribution archive bundles a sample configuration file, named cantaloupe.properties.sample. Make a copy of it. The copy can be named anything, but hereafter it will be referred to as cantaloupe.properties.

Next, open it 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 recommended, as it's a more controlled environment that is less prone to conflicting with other applications. If you do choose to run other applications in the same container, be sure to test them all to ensure they are working correctly.

Standalone

From a command prompt:

java -Dcantaloupe.config=/path/to/cantaloupe.properties -Xmx2g -jar cantaloupe-4.1.x.war
java -Dcantaloupe.config=C:\path\to\cantaloupe.properties -Xmx2g -jar cantaloupe-4.1.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.1.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.1.x/iiif/2/image.tif/info.json
  • http://localhost:8080/cantaloupe-4.1.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:

Also see Deployment for some important notes on Docker use.


Deploying

Before deploying a production server, see Deployment for some important notes.