README.md 4.48 KB
Newer Older
Sebastian Schüpbach's avatar
Sebastian Schüpbach committed
1
2
# Cantaloupe on Docker

3
4
5
This repository provides the Dockerfiles for creating Docker images of
[Cantaloupe](https://cantaloupe-project.github.io), a IIIF imageserver.

6
7
8
9
10
11
12
13
14
15
## Run container

```sh
docker run --name cantaloupe --rm -d -p8182:8182 -v<path_to_host_image_folder>:/home/cantaloupe/images cantaloupe:<version>
```

You need at least to open a port for communication (image delivery and
optionally communication via REST API and admin UI) and a folder where you
keep your media files.

Sebastian Schüpbach's avatar
Sebastian Schüpbach committed
16
17
18
19
20
21
22
### Helm charts

For the purpose of running Cantaloupe container inside the Kubernetes cluster
used for Memobase, there are some Helm charts available in the `helm-charts/`
directory. If you want to deploy a container to Kubernetes in another context,
these charts can probably be used as a starting point for your own setup.

23
24
## Version management

Sebastian Schüpbach's avatar
Sebastian Schüpbach committed
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
This repository offers Docker images for different master versions of
the Cantaloupe. Additionally, all versions come in a range of "flavors" which
represent some combinations of processors. For a comprehensive list see the
[container
registry](https://gitlab.switch.ch/memoriav/memobase-2020/services/cantaloupe-docker/container_registry/261).

### Cantaloupe versions

In order to build an image out of a specific version, use the
respective branch. At the moment, there are branches for the two latest major
versions of Cantaloupe: `4.x` and `5.x`. This naming convention is the same as
used for the image tags. The `latest` image tag points to the branch with the
latest stable major version of Cantaloupe, that means as of today to `5.x`.
Duly updated, the branches use the latest minor versions of the respective
major version of Cantaloupe:

- `4.x` -> `4.1.9`
- `5.x.` -> `5.0.3`

### Processor versions

Available processors are `ffmpeg` (for video), `kakadu` and
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
`openjpeg` for JPEG2000 (the former proprietary, the latter free software) and
`graphicsmagick`. If you need another combination or replace `graphicsmagick`
with `imagemagick` see below.

Readily available flavors:

- `<version>-all`: `ffmpeg`, `kakadu`, `graphicsmagick`
- `<version>-all-free`: `ffmpeg`, `kakadu`, `graphicsmagick`
- `<version>-images`: `graphicsmagick`
- `<version>-images-jp2`: `kakadu`, `graphicsmagick`
- `<version>-images-jp2-free`: `openjpeg`, `graphicsmagick`
- `<version>-jp2`: `kakadu`
- `<version>-jp2-free`: `openjpeg`
- `<version>-vanilla`: no additional processors
- `<version>-video`: `ffmpeg`


64
65
66
67
68
69
70
71
72
73
74
75
## Configuration

You have different options to change the default configuration of Cantaloupe.
Notice that some changes can affect the overall working of the container
(e.g. changing the port used by Cantaloupe)

1. Change the `cantaloupe.properties` file in this directory and rebuild the
   image
2. Mount your own `cantaloupe.properties` file on container startup by
   providing the argument
`-v<path_to_your_config>:/home/cantaloupe/app/cantaloupe.properties`
3. Selectively override properties by setting appropriate environment
Sebastian Schüpbach's avatar
Sebastian Schüpbach committed
76
   variables on container startup (`-e<key>:<value>). The key translates to
77
78
79
uppercase letters, `.` being replaced by `_` (e.g. `https.key_store_path` ->
`HTTPS_KEY_STORE_PATH`).

80
### Reconfigure Processor support
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

Cantaloupe supports different backends for processing media resources.
To keep the image small, none of these processors is enabled in the image per
default. However you can build the image with the required processor backends
by providing one or several keys in the build arg `BUILD_WITH` (example
see below):

- [`ffmpeg`](https://ffmpeg.org/): Used for video processing
- [`graphicsmagick`](http://www.graphicsmagick.org/): Used for general
  image processing
- [`imagemagick`](https://www.imagemagick.org/): More or less like GraphicsMagick
- [`kakadu`](https://kakadusoftware.com/): Fast processor for JPEG2000,
  proprietary
- [`openjpeg`](http://www.openjpeg.org/): Like kakadu, but open source software

```sh
docker run --name cantaloupe --rm -d -p8182:8182 -v<path_to_host_image_folder>:/home/cantaloupe/images -e BUILD_WITH="ffmpeg imagemagick" cantaloupe:<tag>
```

100
### Use with Redis
101
102
103
104
105
106
107
108
109
110
111
112

Cantaloupe supports [Redis](https://redis.io) as an external key-value store for caching.

```sh
docker network create cantaloupe
docker run -d --name redis \
  --restart on-failure \
  --network cantaloupe \
  redis:5-buster
docker run -d --name cantaloupe \
  --rm -p 8182:8182 \
  --network cantaloupe \
113
  -eCACHE_SERVER_DERIVATIVE_ENABLED=true \
114
115
116
  -eCACHE_SERVER_DERIVATIVE=RedisCache \
  -eREDISCACHE_HOST=redis \
  -v<path_to_host_image_folder>:/home/cantaloupe/images \
Sebastian Schüpbach's avatar
Sebastian Schüpbach committed
117
  cantaloupe:4.x
118
```