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 the key names in the configuration file, with all non-alphanumerics replaced with underscores. For example, the following key-value pair in the configuration file:
endpoint.iiif.2.enabled = true
Would be set in the environment as:
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.
At startup, supply the -Dcantaloupe.config VM option, pointing to an absolute or relative path to the file. (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.
A dedicated application thread constantly watches the configuration file for changes and automatically reloads it 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.
Change-watching depends on the event notification features of the underlying filesystem, which are platform-dependent and not necessarily predictable. This feature is meant only to make configuration more convenient and should not be depended on for other purposes.
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.