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

Getting Started

Requirements

The only absolute requirement is Java 7 or newer—either the Oracle JRE or OpenJDK will work. Optional components, such as particular processors, may have additional requirements. See the relevant sections of the user manual for details.


Configuration

The distribution archive bundles a sample configuration file, named cantaloupe.properties.sample. Do not edit this file—instead, create a copy and edit that.


Running

As of version 3.0, Cantaloupe is distributed as a custom .war file that can be run standalone (using a built-in web server) or deployed in a Servlet container such as Tomcat. Standalone mode is simpler, lighter-weight, and starts up almost instantly, while remaining production-ready; while Servlet container mode enables uniform integration into an existing Java web application infrastructure.

Standalone

From the command prompt (OS X/Linux):

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

From the command prompt (Windows):

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

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

Servlet Container

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

Unix

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

Windows

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

Then, restart your container.

Docker

Cantaloupe can be run in Docker. The download archive doesn't include any Docker support files, but see the kaji/cantaloupe fork for an example Dockerfile that might be able to help you get started.


Testing

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


Control Panel

The Control Panel is an optional web-based administrative interface—essentially a GUI configuration file editor. To enable it, set admin.enabled to true and set a password in admin.password. Then, navigate to /admin in a web browser and log in with that password and a username of "admin."