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

Deployment

This page gathers some miscellaneous notes on production deployment. It is not intended to be comprehensive, and there is plenty of relevant information in other sections as well.


Temporary Files

When running in standalone mode, the embedded Jetty server unpacks application files into the system temp directory. Most operating systems will periodically clean out temp files based on their last-accessed time. If any of these cached resources disappear while the application is running, it can cause a variety of errors. Consider configuring your OS's temp-cleaning strategy to clean up only at boot.


Hardware

CPU

Response times tend to benefit from multiple fast CPU cores. Even if a particular processor doesn't support multithreading, the operating system is at least likely to schedule different processing threads (from simultaneous requests) on different cores.

That said, some source formats are more CPU-intensive than others. JPEG2000 via OpenJpegProcessor, for example, will put a lot more pressure on the CPU than uncompressed TIFF via Java2dProcessor.

Memory

Memory requirements will vary greatly depending on source format, source image size, request image size, and the number of concurrent requests. Ideally, it is best to serve only source formats that support tiling or that can be selectively decoded (like TIFF or JPEG2000). Images in other formats will have to be fully loaded into memory before being processed, at great cost.

Storage

Most source formats benefit from fast read performance—in terms of both latency and throughput—in the underlying storage system. Throughput is more important for less efficient source formats—like JPEG, PNG, and mono-resolution TIFF—especially as source image size increases. Local filesystem storage is usually fastest, and often by a lot.


Limiting

A max_pixels configuration option is available to limit the maximum returned size of processed images. This is a "safety net" to prevent clients from bogging down the server. It does not affect requests for full-sized unmodified images, which do not significantly load the server because they are streamed through with no processing.

Note that the authorized? delegate script method can perform the same function as max_pixels, with more options for fine-grained control.


Reverse-Proxying

Cantaloupe can run behind a reverse-proxy web server like Apache or nginx. The proxy should be set up to pass-through encoded URI characters without decoding them. It should also be configured to send the following headers:

Header Description Required?
X-Forwarded-Proto Protocol of the client request; either HTTP or HTTPS. If missing, HTTP will be assumed. No
X-Forwarded-Host FQDN of the client-facing reverse proxy. Yes
X-Forwarded-Port TCP port of the client-facing reverse proxy. Will default to 80 if missing. No
X-Forwarded-Path Path to use as a base path. Will default to none if missing. No
X-Forwarded-For Client IP address. If missing, any features that require a client IP address will either not work (such as IP-based authorization), or be incorrect (such as access logs). No
X-IIIF-ID Originally-requested image identifier. Should be set only when the proxy server will change the value of the identifier in the forwarded request; i.e. when the client is asking for a different identifier than the image server ends up seeing. No

If it is not possible to configure your reverse proxy to send the X-Forwarded-* headers, the base_uri configuration option can be used instead; set it to the URI of the client-facing reverse proxy including any base path.

In a reverse-proxying scenario, you might want to disable the access log, if it would be redundant.

Apache

The following example will make a Cantaloupe server running at http://image-server:8182/ available at http://apache-server/.

<VirtualHost *:80>
  # X-Forwarded-Host will be set automatically by the web server.
  RequestHeader set X-Forwarded-Proto HTTP
  RequestHeader set X-Forwarded-Port 80
  RequestHeader set X-Forwarded-Path /

  ServerName apache-server
  AllowEncodedSlashes NoDecode
  ProxyPassReverseCookiePath / /
  ErrorLog logs/image-error.log
  CustomLog logs/image-access.log combined

  ProxyPass / http://image-server:8182/ nocanon
  ProxyPassReverse / http://image-server:8182/
  ProxyPassReverseCookieDomain image-server:8182 apache-server
  ProxyPreserveHost on
</VirtualHost>

nginx

The following example will make a Cantaloupe server running at http://image-server:8182/ available at http://nginx-server/.

location / {
    if ($request_uri ~* "/(.*)") {
        proxy_pass http://127.0.0.1:8182/$1;
    }
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Forwarded-Path /;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect http://127.0.0.1:8182/ /;
}

SSL/TLS

In standalone mode, Cantaloupe supports TLS connections over HTTPS, configurable via the https.* keys in the configuration file. The general process for getting this working is to add a signed x.509 certificate to either a Java KeyStore (JKS) or PKCS#12 key store, and then refer to the key store file with the https.key_store_path configuration option.

HTTPS can also be enabled on a Servlet container or reverse-proxying web server, in which case Cantaloupe would require no special configuration.