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


Cantaloupe offers a sophisticated and customizable caching subsystem that is capable of meeting a variety of needs while remaining easy to use. Several tiers of cache are available:

  1. Client-side caches, which it has no control over but can provide hints to;
  2. A source cache, which caches source images locally on-demand (if they are not already local) for faster reading;
  3. An info cache, which caches source image metadata in memory;
  4. A derivative cache, which caches processed images and source image metadata such as dimensions.

Client-Side Caching

Cantaloupe can provide caching hints to clients using a Cache-Control response header, which is configurable via the cache.client.* keys in the configuration file. To enable this header, set the cache.client.enabled key to true.

The default settings look something like this:

cache.client.max_age = 2592000
cache.client.shared_max_age =
cache.client.public = true
cache.client.private = false
cache.client.no_cache = false
cache.client.no_store = false
cache.client.must_revalidate = false
cache.client.proxy_revalidate = false
cache.client.no_transform = true

These are reasonable defaults that tell clients they can keep cached images for 2,592,000 seconds (30 days).

Note: the Cache-Control header must have a particular structure—not just any combination of the above will work.

The Cache-Control header will be returned only in HTTP 2xx responses.

Server-Side Caching

Source Cache

Commonly, source images will be served from a local filesystem using FilesystemResolver. There, they are already as local as they can be, so there would be no point in caching them (although a derivative cache could still be of great benefit).

As explained in the Resolvers section, though, images do not have to be served from a local filesystem—they can also be served from a remote web server, cloud storage, or wherever. The source cache can be beneficial when one of these non-filesystem sources performs poorer than ideal. Setting cache.server.source to FilesystemCache will cause all source images from non-FilesystemResolvers to be automatically downloaded and stored in the source cache.

Another reason for a source cache is to work around the incompatibility between certain processors and resolvers. Some processors are only capable of reading source images located on the filesystem. By setting StreamProcessor.retrieval_strategy to CacheStrategy, and then configuring FilesystemCache, the source cache will be utilized to deal with incompatible processor/resolver situations by automatically pre-downloading source images, This makes it possible to use something like OpenJpegProcessor with AmazonS3Resolver.

The source cache is integrated into the larger caching architecture, so all of the information about modes of operation and maintenance is applicable to both the source and derivative caches.

Note that unlike the derivative cache, there is only one available source cache implementation—FilesystemCache—and it will be used independently of the derivative cache.

Derivative Cache

The derivative cache caches post-processed images in order to spare the computational expense of processing the same image request over and over again. Derivative caches are pluggable, in order to enable different cache stores.

Derivative caching is recommended in production, as it will greatly reduce load on the server and improve response times accordingly. There are other ways of caching derivatives, such as by using a caching reverse proxy, but the built-in derivative cache is custom-tailored for this application and easy enough to set up.

Derivative caching is disabled by default. To enable it, set cache.server.derivative.enabled to true, and set cache.server.derivative to the name of a cache, such as FilesystemCache.


The derivative cache can be bypassed on a per-request basis by supplying a cache=false query parameter in the URL. When this parameter is present, the derivative cache will not be read from, nor written to, whether or not it is enabled. The Cache-Control header will also be omitted from responses.


  • Requests for full-sized, unaltered source images are not cached, and are instead streamed through with no processing.
  • IIIF information response representations are not cached—only image metadata, which is the only expensive part to acquire. This means it is possible to change other configuration options that would affect the contents of information responses without invalidating the cache.
  • When derivative caching is enabled, "miss" responses are streamed to the client and cache simultaneously. If the cache I/O is slower than the connection to the client, response times may be impaired.
  • The derivative cache is shared across endpoints. Requests for the same image from different endpoints will return the same cached image.

Info Cache

The info cache (added in version 3.4) caches image info objects in the Java heap, independently of the derivative cache. When both are enabled, the info cache acts as a "level 1" cache in front of the "level 2" derivative cache:

  1. Requested image infos are retrieved from the info cache, if available;
  2. If not, they are retrieved from the derivative cache, if available, and added to the info cache;
  3. If not available in any cache, they are retrieved from a processor, and added to both the info and derivative caches—whichever are enabled.

The info cache can be enabled or disabled via the configuration key.

The info cache is cluster-safe: when multiple instances are sharing the same derivative cache, there will never (for more than a short period of time) be an info in an instance's info cache that isn't also present in the derivative cache.

The info cache does not respect the cache.server.ttl_seconds configuration key. Its content never expires.

The maximum size of the info cache is hard-coded to a reasonable percentage of the maximum heap size, and is not configurable. As infos are very small, the maximum size is unlikely to ever be reached.

The info cache is not persisted; its contents will be lost when the application exits.

Modes of Operation

The source and derivative caches can be configured to operate in one of two ways:

Conservative (cache.server.resolve_first = true)
Source images are looked up and verified to exist before cached representations are returned. This precludes returning a cached representation when the underlying resource no longer exists, but also impairs response times by a variable amount, depending on the resolver.
Aggressive (cache.server.resolve_first = false)
Cached content is returned immediately, if available. This is faster, but inconsistency can develop between the cache and the underlying source image storage, if the latter is not static.


Because cached content is not automatically deleted after becoming invalid, there will likely be a certain amount of invalid content taking up space in the cache at any given time. Without periodic maintenance, the amount can only grow. If this is a problem, it can be dealt with manually or automatically.

Manual (Command Line)

Command-line maintenance is deprecated in verison 3.4 and will be removed in version 4.0. Use the HTTP API instead.

To purge all expired content, launch with the -Dcantaloupe.cache.purge_expired option.

To purge all content, expired or not, launch with the -Dcantaloupe.cache.purge option.

To purge all content related to a given identifier, expired or not launch with the -Dcantaloupe.cache.purge=identifier option.

When any of these arguments are present at launch, the application will run in a special mode in which the web server will not be started, and exit when done. Any of these tasks can be run in a separate process, on the live cache store, while the main server instance remains running.

Manual (HTTP API)

See the HTTP API documentation for more information.


Since version 2.2, a "cache worker" is available that will periodically clean and purge expired items from the cache automatically. (See the cache.server.worker.* configuration options.)


Most caches (with the exception of HeapCache) age-limit their content based on last-accessed or last-modified time. Depending on the amount of source content served, the varieties of derivatives generated, the time-to-live setting, and how often maintenance is performed, the cache may grow very large. Its size is not tracked, as this would be either expensive, or, for some cache implementations, impossible. Managing the cache size is therefore the responsibility of the administrator, and it can be accomplished by any combination of:

  1. Performing maintenance more often;
  2. Reducing the time-to-live (using the cache.server.ttl_seconds configuration key);
  3. Increasing the threshold by allocating more storage to the cache.



FilesystemCache caches content in a filesystem tree. The tree structure looks like:

  • FilesystemCache.pathname/
    • source/ (1)
      • Intermediate subdirectories (2)
        • {hashed identifier} (3)
    • image/
      • Intermediate subdirectories (2)
        • {hashed identifier}_{hashed operation list string representation}.{output format extension} (3)
    • info/
      • Intermediate subdirectories (2)
        • {hashed identifier}.json (3)
  1. Empty unless source caching is enabled.
  2. Some filesystems have per-directory file count limits, or thresholds beyond which performance starts to degrade. To work around this, cache files are stored in subdirectory trees consisting of leading fragments of identifier MD5 hashes, configurable by FilesystemCache.dir.depth and FilesystemCache.dir.name_length.
  3. Identifier and operation list strings in filenames are MD5-hashed in order to allow for lengths longer than the filesystem's filename length limit.

Cache files are created with a .tmp extension and moved into place when closed for writing.

This cache is process-safe: it is safe to point multiple server instances at the same cache directory.

On macOS, files' last-modified time is used instead of their last-accessed time, as the latter is not reliable.


HeapCache, available since version 3.4, caches derivative images and metadata in the Java heap, which is the main area of RAM available to the JVM. This is the fastest of the caches, with the main drawback being that it cannot be shared across instances.

Unlike most of the other caches, this one does not age-limit content. When the target size (HeapCache.target_size) has been exceeded, the minimum number of least-recently-accessed items are purged that will reduce it back down to this size. (The configured target size may be safely changed while the application is running.)

Because this cache is not time-limited, cache.server.ttl_seconds does not apply, and, if enabled, the cache worker will have nothing to do, so will remain idle.

When using this cache, ensure that your heap is able to grow large enough to accommodate the desired target size (using the -Xmx VM option), and that you have enough RAM to accommodate this size.


This cache can persist its contents to disk using the HeapCache.persist and HeapCache.persist.filesystem.pathname configuration keys. When persistence is enabled, the contents of the cache will be written to a file at shutdown, and loaded back in at startup. If persistence is disabled, the cache contents will be lost when the application exits.

Some thought was given to storing cached data using the same on-disk format used by FilesystemCache, so that persisted data would be compatible between these caches. Unfortunately, this is not possible because of the one-way hashing used in the FilesystemCache format.


JdbcCache caches derivative images and metadata in relational database tables. To use this cache, a JDBC driver for your database must be installed on the classpath.

JdbcCache is tested with the H2 database. It is known to not work with the official PostgreSQL driver, as of version 9.4.1207. Other databases may work, but are untested.

JdbcCache can be configured with the following options:

JDBC connection URL; for example, jdbc:postgresql://localhost:5432/mydatabase.
User to connect to the database as.
Password to use when connecting to the database. Can be left blank if not needed.
Table in which to cache derivative (post-processed) images.
Table in which to cache information responses.

JdbcCache will not create its schema automatically—this must be done manually using the following commands, which may have to be altered slightly for your particular database:

CREATE TABLE IF NOT EXISTS {JdbcCache.derivative_image_table} (
   operations VARCHAR(4096) NOT NULL,
   image BLOB,
   last_accessed DATETIME

CREATE TABLE IF NOT EXISTS {JdbcCache.info_table} (
  identifier VARCHAR(4096) NOT NULL,
  info VARCHAR(8192) NOT NULL,
  last_accessed DATETIME

CREATE INDEX operations_idx ON {JdbcCache.derivative_image_table} (operations);
CREATE INDEX identifier_idx ON {JdbcCache.info_table} (identifier);

JdbcCache uses write transactions and is process-safe: it is safe to point multiple server instances at the same database tables.


AmazonS3Cache caches derivative images and metadata into an Amazon Simple Storage Service (S3) bucket.


AmazonS3Cache is configured (excepting credentials) using the following configuration keys:
Name of the bucket to contain cached content.
Name of a region to send requests to, such as us-east-1. Can be commented out or left blank to use a default region. (See S3 Regions.)
String to prepend to object keys—for example, to achieve a virtual folder hierarchy.
Credentials Sources

See the Credentials Sources information for AmazonS3Resolver. AmazonS3Cache works the same way, except that the credentials-related configuration keys, if you choose to use them, are different:

An access key associated with your AWS account. (See AWS Security Credentials.)
A secret key associated with your AWS account. (See AWS Security Credentials.)
Note: Amazon S3 does not provide a last-accessed time in object metadata, so the time-to-live will be on the basis of last-modified time instead.


AzureStorageCache caches derivative images and metadata into a Microsoft Azure Storage container. It can be configured with the following options:

The name of your Azure account.
A key to access your Azure Storage account.
Name of the container from which to serve images.
String to prepend to object keys—for example, to achieve a virtual folder hierarchy.
Note: Azure Storage does not provide a last-accessed time in object metadata, so the time-to-live will be on the basis of last-modified time instead.


RedisCache, available since version 3.4, caches derivative images and metadata using the Redis data structure store. It supports the following configuration options:

  • RedisCache.port
  • RedisCache.ssl
  • RedisCache.password
  • RedisCache.database

Unlike the other caches, cache policy is configured on the Redis side, and cache.server.ttl_seconds will have no effect with this cache. Likewise, if enabled, the cache worker will have nothing to do, so will remain idle.