repository·develop·Indexed 43 days ago
https://github.com/cantaloupe-project/cantaloupeA high-performance dynamic image server written in Java designed to serve images on demand. It supports various formats and processing engines, featuring multiple caching implementations including S3, Redis, JDBC, Azure Storage, and an in-memory HeapCache.
To run Cantaloupe within an IDE (like IntelliJ IDEA or Eclipse):
edu.illinois.library.cantaloupe.StandaloneEntry.-Dcantaloupe.config=cantaloupe.properties.Upgrading from version 3.1.2 to 3.2 involves adding new processor configuration keys and removing obsolete post-processor keys.
Add these keys from the sample configuration:
FfmpegProcessor.sharpenGraphicsMagickProcessor.sharpenImageMagickProcessor.sharpenJaiProcessor.sharpenJava2dProcessor.upscale_filterJava2dProcessor.downscale_filterJava2dProcessor.sharpenKakaduProcessor.upscale_filterKakaduProcessor.downscale_filterKakaduProcessor.sharpenOpenJpegProcessor.upscale_filterOpenJpegProcessor.downscale_filterOpenJpegProcessor.sharpenPdfBoxProcessor.upscale_filterPdfBoxProcessor.downscale_filterPdfBoxProcessor.sharpenmetadata.*Remove these obsolete keys:
Java2dProcessor.scale_modeKakaduProcessor.post_processor.*OpenJpegProcessor.post_processor.*PdfBoxProcessor.post_processor.*Upgrading from 3.4.x to 4.0 involves significant renaming and architectural changes.
Resolver $\rightarrow$ contains Source (e.g., HttpResolver $\rightarrow$ HttpSource).HttpSource.auth.* $\rightarrow$ HttpSource.BasicLookupStrategy.auth.*AmazonS3Source.* $\rightarrow$ S3Source.*StreamProcessor.retrieval_strategy $\rightarrow$ processor.stream_retrieval_strategyKakaduProcessor.path_to_binaries $\rightarrow$ KakaduDemoProcessor.path_to_binariesAmazonS3Cache.* $\rightarrow$ S3Cache.*Add these keys:
S3Source.endpointS3Source.BasicLookupStrategy.path_prefixS3Source.BasicLookupStrategy.path_suffixprocessor.fallback_retrieval_strategyprocessor.imageio.*S3Cache.endpointcache.server.source.ttl_secondscache.server.derivative.ttl_secondsRemove these keys:
S3Source.bucket.regionprocessor.limit_to_8_bitsS3Cache.bucket.regioncache.server.source.enabledcache.server.ttl_secondsUpgrading from version 2.2 to 3.0 involves significant configuration renames, delegate script restructuring, and database schema changes.
Add these keys from the sample configuration:
admin.*delegate_script.enabledendpoint.iiif.2.restrict_to_sizesStreamProcessor.retrieval_strategycache.sourceAmazonS3Cache.*AzureStorageCache.*redaction.enabledRename these keys:
delegate_script $\rightarrow$ delegate_script.pathnamecache.server $\rightarrow$ cache.derivativeRemove these keys:
JdbcResolver.function.*Add these methods from the sample delegate script:
redactionsCantaloupe::JdbcResolver::get_database_identifierCantaloupe::JdbcResolver::get_media_typeCantaloupe::JdbcResolver::get_lookup_sqlRename these delegate script methods:
Cantaloupe::get_pathname $\rightarrow$ Cantaloupe::FilesystemResolver::get_pathnameCantaloupe::get_url $\rightarrow$ Cantaloupe::HttpResolver::get_urlCantaloupe::get_azure_storage_blob_key $\rightarrow$ Cantaloupe::AzureStorageResolver::get_blob_keyCantaloupe::get_s3_object_key $\rightarrow$ Cantaloupe::AmazonS3Resolver::get_object_keyNote on JdbcResolver: If you use JdbcResolver, the JdbcResolver.function.* configuration keys are now obsolete. These functions must be rewritten as delegate script methods.
If you are using JdbcCache, you must modify your database schema by renaming the last_modified column to last_accessed in the following tables:
ALTER TABLE {JdbcCache.info_table} CHANGE COLUMN last_modified last_accessed;
ALTER TABLE {JdbcCache.derivative_image_table} CHANGE COLUMN last_modified last_accessed;Information previously available on the landing page (/) has moved to the Control Panel (/admin).
adminadmin.password configuration option.Upgrading from 4.1.x to 5.0 involves significant changes to packaging, requirements, and configuration.
http.min_threadshttp.max_threadslog_error_responsesmeta_identifier.*endpoint.iiif.3.enabledendpoint.health.dependency_checkS3Source.region (Note: If you previously used S3Source.endpoint for an AWS endpoint, unset it and use this key instead)processor.ManualSelectionStrategy.xpmprocessor.downscale_linearprocessor.imageio.xpm.readerGrokProcessor.path_to_binariesprocessor.pdf.*S3Cache.region (Note: If you previously used S3Cache.endpoint for an AWS endpoint, unset it and use this key instead)log.application.ConsoleAppender.logstash.enabled, log.application.FileAppender.logstash.enabled, log.application.RollingFileAppender.logstash.enabled, log.error.FileAppender.logstash.enabled, log.error.RollingFileAppender.logstash.enabledhttp.http2.enabledhttps.http2.enabledscale_constraint_suffix.patternscale_constraint_suffix.formatendpoint.iiif.content_dispositiondelegate_script.cache.enabledprocessor.metadata.*GraphicsMagickProcessor.path_to_binariesKakaduDemoProcessor.path_to_binariesImageMagickProcessor.path_to_binariesS3Cache.max_connectionsredaction.enabledendpoint.iiif.2.restrict_to_sizes $\rightarrow$ endpoint.iiif.restrict_to_sizesoverlays.enabled $\rightarrow$ overlays.BasicStrategy.enableddeserialize_meta_identifier(), serialize_meta_identifier(), pre_authorize(), extra_iiif3_information_response_keys(), and metadata().pre_authorize() method may require you to refactor logic previously handled in authorize().edu.illinois.library.cantaloupe.script.Logger to edu.illinois.library.cantaloupe.delegate.Logger.processor.metadata.preserve, switch to the metadata() delegate method.cookie key in the delegate script context hash is now a hash of cookie name-value pairs.X-IIIF-ID is no longer supported. Use X-Forwarded-ID instead.-) to a semicolon (;). To maintain compatibility with URIs like image.jpg-1:2, set meta_identifier.transformer.StandardMetaIdentifierTransformer.delimiter to -.page and time query arguments are deprecated. Use the identifier path component instead (e.g., image.jpg;3 for page 3, or image.jpg;10 for 10 seconds).HttpSource2 from 4.1.x is now HttpSource. The old HttpSource has been removed.KakaduNativeProcessor, install the updated shared library from the deps folder.KakaduNativeProcessor, OpenJpegProcessor, or GrokProcessor.metadata() method, you must purge all cached infos (manually delete .json files/objects or purge the whole cache via API).Upgrading from version 3.2.x to 3.3 requires several configuration changes, key renames, and delegate script updates.
Add these keys from the sample configuration:
delegate_script.cache.enabledendpoint.api.*processor.dcmprocessor.normalizeprocessor.background_colorprocessor.upscale_filterprocessor.downscale_filterprocessor.sharpenprocessor.jpg.progressiveprocessor.jpg.qualityprocessor.tif.compressioncache.server.ttl_secondsoverlays.BasicStrategy.typeoverlays.BasicStrategy.stringoverlays.BasicStrategy.string.*Rename these keys:
watermark.* $\rightarrow$ overlays.*Remove these obsolete keys:
JdbcResolver.max_pool_sizeFfmpegProcessor.sharpenGraphicsMagickProcessor.sharpenGraphicsMagickProcessor.background_colorImageMagickProcessor.sharpenImageMagickProcessor.background_colorJaiProcessor.sharpenJaiProcessor.jpg.qualityJaiProcessor.tif.compressionJava2dProcessor.upscale_filterJava2dProcessor.downscale_filterJava2dProcessor.sharpenJava2dProcessor.jpg.qualityJava2dProcessor.tif.compressionKakaduProcessor.upscale_filterKakaduProcessor.downscale_filterKakaduProcessor.sharpenOpenJpegProcessor.upscale_filterOpenJpegProcessor.downscale_filterOpenJpegProcessor.sharpenPdfBoxProcessor.upscale_filterPdfBoxProcessor.downscale_filterPdfBoxProcessor.sharpenFilesystemCache.ttl_secondsJdbcCache.max_pool_sizeJdbcCache.ttl_secondsAmazonS3Cache.ttl_secondsAzureStorageCache.ttl_secondsIf you are using FilesystemCache, you must purge your cache after the upgrade.
authorized?() or watermark() delegate methods, the contents of the operations argument have changed. Refer to the new sample delegate script.watermark() method, the pathname key in the returned hash must be changed to image.watermark() delegate method to overlay().To upgrade Cantaloupe from version 5.0 to 6.0, perform the following steps:
Add these keys from the sample configuration to your setup:
endpoint.health.enabledHttpSource.proxy.http.hostHttpSource.proxy.http.portHttpSource.BasicLookupStrategy.send_head_requestsprocessor.purge_incompatible_from_source_cacheAdd the following method to your sample delegate script:
jdbcsource_last_modified()If you are using a Java delegate, add the following method to your delegate class:
getJDBCSourceLastModified()To upgrade from 4.0.x to 4.1, follow these steps:
HttpSource.trust_all_certs $\rightarrow$ HttpSource.allow_insecureprocessor.[format] $\rightarrow$ processor.ManualSelectionStrategy.[format]processor.fallback $\rightarrow$ processor.ManualSelectionStrategy.fallbackAdd these keys:
max_scaleHttpSource.chunking.*S3Source.chunking.*AzureStorageSource.chunking.*processor.selection_strategyRemove these keys:
allow_upscalingendpoint.public.auth.*S3Source.max_connectionsprocessor.normalizeredirect() or authorized?(), migrate their logic into authorize() and remove the old methods.endpoint.public.auth.* keys, use the new authorize() delegate method instead.KakaduDemoProcessor is deprecated. Consider migrating to KakaduNativeProcessor or OpenJpegProcessor.To run Cantaloupe from the source code using Maven, first prepare a configuration file by copying the sample properties file. Then, use the exec:java goal to run the embedded web server.
To build a standalone release JAR, use mvn clean package. You can then run the resulting JAR using the java command, ensuring you point to your configuration file via the -Dcantaloupe.config system property and use the edu.illinois.library.cantaloupe.StandaloneEntry main class.
# 1. Prepare configuration
cp cantaloupe.properties.sample cantaloupe.properties
# 2. Build and run using Maven
mvn clean compile exec:java -Dcantaloupe.config=cantaloupe.properties
# 3. Alternatively, build a release JAR and run it directly
mvn clean package -DskipTests
java -cp cantaloupe-{version}.jar -Dcantaloupe.config=cantaloupe.properties edu.illinois.library.cantaloupe.StandaloneEntryTo avoid manually installing all dependencies required for the freedeps profile, use the provided docker-compose.yml file. This spins up all required services in containers and runs the tests in a separate container.
Run the following command from the project root:
docker-compose -f docker/{platform}/docker-compose.yml up --build --exit-code-from cantaloupeWhen using S3Cache, objects are stored in the S3 bucket using a specific naming convention based on their type:
info/ prefix. The key is the MD5 hash of the image identifier followed by .json.{S3CACHE_OBJECT_KEY_PREFIX}/info/{md5(identifier)}.jsonimage/ prefix. The key includes the MD5 hash of the image identifier and the MD5 hash of the operation list string representation.{S3CACHE_OBJECT_KEY_PREFIX}/image/{md5(identifier)}/{md5(op_list_string)}{extension}Note: The {extension} is derived from the preferred extension of the Encode operation in the OperationList (e.g., .jpg, .png).