The application is configured by an assortment of key-value pairs. The sample configuration file contains an authoritative listing of all available keys, set to reasonable default values.
When the application searches for a value for a given key, it consults the following sources in order of priority:
Key names in the environment are uppercased versions of "ordinary" configuration key names, with all non-alphanumerics replaced with underscores. For example, the following key-value pair in the configuration file:
endpoint.iiif.2.enabled = true
When set in the environment, would become:
ENDPOINT_IIIF_2_ENABLED=true
Environment configuration is read-only.
Configuration files are encoded in the human-friendly .properties format. A sample file, called cantaloupe.properties.sample, is included in the distribution archive. It is recommended to make a copy of this file and use the copy as your main configuration file. It can be located anywhere, and named anything.
Supply the -Dcantaloupe.config VM option, pointing to an absolute or relative path to the file, to tell the application where the file is located. (See Getting Started for examples.)
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.
Keys in child files override ones in parent files. When the same key is defined in multiple files, instances will use the most specific one.
Multiple extends keys in the same file are not supported.
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 inline comments 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.
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. (But not the environment.)
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.