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



Cantaloupe obtains its configuration from a .properties file. A sample configuration file, called, is included in the distribution archive. It is recommended to make a copy of this file and use the copy as your primary configuration file.

To tell the image server where the file is located, supply the -Dcantaloupe.config VM option, pointing to an absolute or relative path to the file. The file can be located anywhere, and named anything. (See Getting Started for examples.)


Since version 3.4, configuration files may contain an extends key pointing to the pathname or same-directory filename of another configuration file. This enables multiple instances to share common configuration keys.

Child files override parent files. When the same key is defined in multiple files, instances will use the most specific one.

Live Changes

The configuration file will be automatically reloaded within a few seconds of a change. Changes to most keys take effect immediately, but some require a restart; see the sample configuration file for documentation of which.

When using inheritance, any file in the extends chain that changes will be reloaded by all instances in whose extends chain it appears.

Remote Changes

The configuration can be updated remotely via the HTTP API. When a change is received, it will be activated immediately and written out to the configuration file, if it is writable.

When using inheritance, a key will be written to the most specific file that already contains it, or to the main (child) file, if none already contain it.