? Cantaloupe
High-performance dynamic image server in Java
Users
Get started with a release build.
Developers
Build & run
Command line
mvn exec:java -Dcantaloupe.config=...will build the project and run in
standalone mode, using the embedded Servlet container listening on the
port(s) specified incantaloupe.properties.mvn clean package -DskipTestswill build a release WAR in thetarget
folder, which can be run like any other.
IDE
There are a few ways to do this. The simplest is probably:
-
Add a new run configuration using the "Java Application" template or its
equivalent. -
Set the main class to
edu.illinois.library.cantaloupe.StandaloneEntryand
add the-Dcantaloupe.config=...VM option. -
Set the run configuration to include dependencies with
providedscope.
(IntelliJ has a checkbox for this.) Alternatively, download
servlet-api-3.1.jar
and add it to your classpath:--class-path=/path/to/servlet-api-3.1.jarOr, in Java 9+, your module path:
--module-path=/path/to/containing/dir
Test
Testing the code
Copy test.properties.sample to test.properties and fill in whatever info
you have.
The code tests are structured into three Maven profiles:
1. Tests with no dependencies
mvn clean test -Pnodeps will run only the tests that have no dependencies
on third-party services and do not require any external tools or libraries.
2. Tests with free dependencies
mvn clean test -Pfreedeps will run all of the above tests, plus any that
depend on open-source tools or libraries. These are the tests run in
continuous integration. The following dependencies are required:
- DynamoDB or dynamodb-local
(for DynamoDBCacheTest) - FFmpeg (for FfmpegProcessorTest)
- OpenJPEG (for OpenJpegProcessorTest)
- Redis (for RedisCacheTest)
- TurboJPEG with Java binding (for TurboJpegProcessorTest)
3. All tests
mvn clean test will run all tests, including the ones above. The following
dependencies are required in addition to the ones above:
- Kakadu native library (for KakaduNativeProcessorTest) - see the
KakaduNativeProcessor section of the user manual for information. - A Microsoft Azure account
Docker
Because it can be a chore to install all of the dependencies needed to get all
of the tests in the freedeps profile passing, there is a Docker testing image
available that contains all needed dependencies. See the /.travis.yml file.
Output testing
There is an output tester tool
that enables visual inspection of image output.
Performance testing
Performance tests use JMH.
Run them with mvn clean test -Pbenchmark.
Contribute
Contributions are welcome. The suggested process for contributing code changes
is:
- Submit a "heads-up" issue in the tracker, ideally before beginning any
work. - Create a fork.
- Create a feature branch, starting from either
release/x.xordevelop
(see the "Versioning" section.) - Make your changes.
- Commit your changes (
git commit -am 'Add some feature'). - Push the branch (
git push origin feature/my-new-feature). - Create a pull request.
Other Notes
Configuration keys
Different application versions may require different configuration file keys.
It's good practice to use a dedicated configuration file for each version.
Key changes are documented in UPGRADING.md.
Versioning
Cantaloupe roughly uses semantic versioning. Major releases (n) involve major
rearchitecting that breaks backwards compatibility in a significant way. Minor
releases (n.n) either do not break compatibility, or only in a minor way.
Patch releases (n.n.n) are for bugfixes only.
Branching
Cantaloupe uses the
Gitflow
branching model. develop is the main branch that tracks the current state of
the next non-bugfix release. Significant features branch off of that into
feature branches (feature/feature-name), from which they can be integrated
into a particular release.
When a major or minor version is ready for release in develop, it branches
off into a release/n.n branch, where its version is set. Finally, that is
merged into master, where the release is tagged and the release archive is
created.
Bugfixes that would increment a minor version of a release are applied to the
release branch for that release, and merged back into develop.
Prerelease
- Run the Maven Verifier plugin (
mvn verify -DskipTests=true) - Run an OWASP dependency check (
mvn org.owasp:dependency-check-maven:check) - Run Findbugs (
mvn clean compile findbugs:findbugs findbugs:gui) - Run the tests:
- JUnit
- Endpoint tests
- Finalize the code to be released, addressing any relevant milestone issues,
TODOs, etc. - Finalize the documentation, including the website, user manual, and change
log
Releasing
- Merge into
release/vX.X - Update the version in
pom.xmland commit this change - Merge into
master - Push the code:
git push origin master; git push origin release/x.x - Wait for CI tests to pass
- Create the release
.ziparchive withmvn clean package -DskipTests - Verify that the
.ziparchive is as expected - Tag the release:
git tag -a v{version} -m 'Tag v{version}' - git push --tags
- Add the
.ziparchive and change log info to the release tag on GitHub - Deploy the updated website (usually not necessary for bugfix releases)
- Close the release's GitHub milestone
License
Cantaloupe is open-source software distributed under the University of
Illinois/NCSA Open Source License; see the file LICENSE.txt for terms.