High-performance dynamic image server in Java
Get started with a release build.
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 -DskipTests
will build a release WAR in thetarget
folder, which can be run like any other.
There are a few ways to do this, in accordance with the options above. The simplest is probably to:
-
Add a new run configuration using the "Java Application" template or its equivalent.
-
Set the main class to
edu.illinois.library.cantaloupe.StandaloneEntry
and add the-Dcantaloupe.config=...
VM option. -
You might have to download servlet-api-3.1.jar and add it to your classpath:
--class-path=/path/to/servlet-api-3.1.jar
Or, in Java 9, your module path:
--module-path=/path/to/containing/dir
For testing, copy test.properties.sample
to test.properties
and fill in
whatever info you have.
The tests are structured into three profiles:
mvn clean test -Pnodeps
will run only the tests that have no dependencies
on third-party services and do not require any exteral tools or libraries.
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:
- FFmpeg (for FfmpegProcessorTest)
- GraphicsMagick (for GraphicsMagickProcessorTest)
- ImageMagick (for ImageMagickProcessorTest)
- OpenJPEG (for OpenJpegProcessorTest)
- Redis (for RedisCacheTest)
mvn clean test
will run all tests, including the ones above. The following
dependencies are required in addition to the ones above:
- An Amazon Web Services account
- A Microsoft Azure account
- Kakadu (for KakaduProcessorTest)
The website is built using Jekyll. With that installed,
run jekyll serve
from the website
directory. Then, open
http://localhost:4000/cantaloupe/ in a
web browser.
An effort is made to keep the documentation in sync with development on the same branch. The "Upgrading" and "Changes" sections of the website are usually current.
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.x
ordevelop
(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.
Different application versions may require different configuration file keys.
It's good practice to use a dedicated configuration file for each version.
Keys are documented on the website through the latest release. If you are
using a newer build, like a snapshot from the develop
branch, newer keys will
be documented in
website/upgrade.html.
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.
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 non-bugfix version is ready for release in develop
, it branches
off into a new release/n.n
branch, where its version is set. Finally, that
is merged into master
, where the release is tagged and the release
distribution 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
.
- Finalize the code to be released, addressing any relevant milestone issues, TODOs, etc.
- 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
) - Ensure that the tests are current, comprehensive, and passing
- Finalize the documentation, including the website, user manual, and change log
- Merge into
release/vX.X
- Update the version in
pom.xml
and commit this change - Merge into
master
- Create the release
.zip
archive withmvn clean package
- Verify that the
.zip
archive is as expected - Tag the release:
git tag -a v{version} -m 'Tag v{version}'
- Push the code:
git push origin master; git push origin release/x.x; git push --tags
- Add the
.zip
archive and change log info to the release tag on GitHub - Deploy the updated website using
build/deploy_website.rb
- Append
-SNAPSHOT
to the version inpom.xml
and commit this change
Cantaloupe is open-source software distributed under the University of Illinois/NCSA Open Source License; see the file LICENSE for terms.