Apache
/
activemq-artemis
mirror of https://github.com/apache/activemq-artemis.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

ARTEMIS-4441 add Docker chapter to User Manual

This commit is contained in:
Justin Bertram 2023-09-21 16:40:34 -05:00
parent 5eb02d247b
commit f565e1318e
4 changed files with 144 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
artemis-docker/readme.adoc Normal file
View File

@ -0,0 +1 @@
See the Docker documentation in the xref:../docs/user-manual/docker.adoc[ActiveMQ Artemis User Manual].

208
artemis-docker/readme.md
View File

@ -1,208 +0,0 @@
# Docker Image Example
This is an example on how you could create your own Docker Image For Apache
ActiveMQ Artemis based on CentOS or Ubuntu (Eclipse Temurin JDK images).
# Preparing
You need a set of activemq binary distribution files to build the Docker Image.
These can be your local distribution files, in which case you need to build the project first,
or they can be pulled automatically from the official ActiveMQ release repository.
## Using a Local Binary Distribution
If you want to use a local binary distribution, build the project from the root of the ActiveMQ source tree using maven.
```
mvn install -DskipTests=true
```
Following the build, the distribution files will be in your local distribution directory.
```
artemis-distribution/target/apache-artemis-2.17.0-SNAPSHOT-bin/apache-artemis-2.17.0-SNAPSHOT
```
In the artemis-docker directory, run the script ./prepare-docker.sh to copy the docker files into your
local binary distribution.
Below is shown the command to prepare the build of the Docker Image starting
from the local distribution (from the source codes of ActiveMQ Artemis)
```
# Prepare for build the Docker Image from the local distribution. Replace the
# {local-distribution-directory} with your directory.
$ ./prepare-docker.sh --from-local-dist --local-dist-path {local-distribution-directory}
```
The output of the previous command is shown below.
```
$ ./prepare-docker.sh --from-local-dist --local-dist-path ../artemis-distribution/target/apache-artemis-2.17.0-SNAPSHOT-bin/apache-artemis-2.17.0-SNAPSHOT
Using ../artemis-distribution/target/apache-artemis-2.17.0-SNAPSHOT-bin/apache-artemis-2.17.0-SNAPSHOT
Cleaning up ../artemis-distribution/target/apache-artemis-2.17.0-SNAPSHOT-bin/apache-artemis-2.17.0-SNAPSHOT/docker
Well done! Now you can continue with building the Docker image:
# Go to ../artemis-distribution/target/apache-artemis-2.17.0-SNAPSHOT-bin/apache-artemis-2.17.0-SNAPSHOT
$ cd ../artemis-distribution/target/apache-artemis-2.17.0-SNAPSHOT-bin/apache-artemis-2.17.0-SNAPSHOT
# For CentOS with full JDK 11
$ docker build -f ./docker/Dockerfile-centos7-11 -t artemis-centos .
# For Ubuntu with full JDK 11
$ docker build -f ./docker/Dockerfile-ubuntu-11 -t artemis-ubuntu .
# For Ubuntu with just JRE 11
$ docker build -f ./docker/Dockerfile-ubuntu-11-jre -t artemis-ubuntu-jre .
# For Alpine with full JDK 17
$ docker build -f ./docker/Dockerfile-alpine-17 -t artemis-alpine .
# For Alpine with just JRE 11
$ docker build -f ./docker/Dockerfile-alpine-11-jre -t artemis-alpine-jre .
# For Ubuntu on Linux ARMv7/ARM64 with full JDK
$ docker buildx build --platform linux/arm64,linux/arm/v7 --push -t {your-repository}/apache-artemis:2.17.0-SNAPSHOT -f ./docker/Dockerfile-ubuntu-11 .
Note: -t artemis-centos and -t artemis-ubuntu are just tag names for the purpose of this guide
For more info see readme.md.
```
## Using the Official ActiveMQ Binary Release
The command to prepare the build of the Docker Image starting from the official
release of ActiveMQ Artemis is shown below
```
# Prepare for build the Docker Image from the release version. Replace the
# {release-version} with the version that you want
$ ./prepare-docker.sh --from-release --artemis-version {release-version}
```
The output of the previous command is shown below.
```
$ ./prepare-docker.sh --from-release --artemis-version 2.16.0
Creating _TMP_/artemis/2.16.0
Downloading apache-artemis-2.16.0-bin.tar.gz from https://downloads.apache.org/activemq/activemq-artemis/2.16.0/...
################################################################################################################################################################################################################################ 100,0%
Expanding _TMP_/artemis/2.16.0/apache-artemis-2.16.0-bin.tar.gz...
Removing _TMP_/artemis/2.16.0/apache-artemis-2.16.0-bin.tar.gz...
Well done! Now you can continue with building the Docker image:
# Go to _TMP_/artemis/2.16.0
$ cd _TMP_/artemis/2.16.0
# For CentOS with full JDK
$ docker build -f ./docker/Dockerfile-centos7-11 -t artemis-centos .
# For Ubuntu with full JDK
$ docker build -f ./docker/Dockerfile-ubuntu-11 -t artemis-ubuntu .
# For Ubuntu with just JRE
$ docker build -f ./docker/Dockerfile-ubuntu-11-jre -t artemis-ubuntu .
# For Ubuntu on Linux ARMv7/ARM64 with full JDK
$ docker buildx build --platform linux/arm64,linux/arm/v7 --push -t {your-repository}/apache-artemis:2.16.0 -f ./docker/Dockerfile-ubuntu-11 .
Note: -t artemis-centos and -t artemis-ubuntu are just tag names for the purpose of this guide
For more info read the readme.md
```
# Building
Go to `$ARTEMIS_DIST` where you prepared the binary with Docker files.
## For CentOS
From within the `$ARTEMIS_DIST` folder:
```
$ docker build -f ./docker/Dockerfile-centos7-11 -t artemis-centos .
```
## For Ubuntu
From within the `$ARTEMIS_DIST` folder:
```
$ docker build -f ./docker/Dockerfile-ubuntu-11 -t artemis-ubuntu .
```
## Smaller Ubuntu image with just JRE
From within the `$ARTEMIS_DIST` folder:
```
$ docker build -f ./docker/Dockerfile-ubuntu-11-jre -t artemis-ubuntu .
```
## For Ubuntu (Build for linux ARMv7/ARM64)
```
$ docker buildx build --platform linux/arm64,linux/arm/v7 --push -t {your-repository}/apache-artemis:2.17.0-SNAPSHOT -f ./docker/Dockerfile-ubuntu-11 .
```
**Note:**
`-t artemis-centos` and `-t artemis-ubuntu` are just tag names for the purpose of this guide
# Environment Variables
Environment variables determine the options sent to `artemis create` on first execution of the Docker
container. The available options are:
**`ARTEMIS_USER`**
The administrator username. The default is `artemis`.
**`ARTEMIS_PASSWORD`**
The administrator password. The default is `artemis`.
**`ANONYMOUS_LOGIN`**
Set to `true` to allow anonymous logins. The default is `false`.
**`EXTRA_ARGS`**
Additional arguments sent to the `artemis create` command. The default is `--http-host 0.0.0.0 --relax-jolokia`.
Setting this value will override the default. See the documentation on `artemis create` for available options.
**Final broker creation command:**
The combination of the above environment variables results in the `docker-run.sh` script calling
the following command to create the broker instance the first time the Docker container runs:
${ARTEMIS_HOME}/bin/artemis create --user ${ARTEMIS_USER} --password ${ARTEMIS_PASSWORD} --silent ${LOGIN_OPTION} ${EXTRA_ARGS}
Note: `LOGIN_OPTION` is either `--allow-anonymous` or `--require-login` depending on the value of `ANONYMOUS_LOGIN`.
# Mapping point
- `/var/lib/artemis-instance`
It's possible to map a folder as the instance broker.
This will hold the configuration and the data of the running broker. This is useful for when you want the data persisted outside of a container.
# Lifecycle of the execution
A broker instance will be created during the execution of the instance. If you pass a mapped folder for `/var/lib/artemis-instance` an image will be created or reused depending on the contents of the folder.
# Overriding files in etc folder
You can use customized configuration for the artemis instance by replacing the files residing in `etc` folder with the custom ones, eg. `broker.xml` or `artemis.profile`. Put the replacement files inside a folder and map it as a volume to:
- `/var/lib/artemis-instance/etc-override`
The contents of `etc-override` folder will be copied over to etc folder after the instance creation. Therefore, the image will always start with user-supplied configuration.
It you are mapping the whole `var/lib/artemis-instance` to an outside folder for persistence, you can place an `etc-override` folder inside the mapped one, its contents will again be copied over etc folder after creating the instance.
## Running a CentOS image
The image just created in the previous step allows both stateless or stateful runs.
The stateless run is achieved by:
```
$ docker run --rm -it -p 61616:61616 -p 8161:8161 artemis-centos
```
The image will also support mapped folders and mapped ports. To run the image with the instance persisted on the host:
```
docker run -it -p 61616:61616 -p 8161:8161 -v <broker folder on host>:/var/lib/artemis-instance artemis-centos
```
where `<broker folder on host>` is a folder where the broker instance is supposed to
be saved and reused on each run.

142
docs/user-manual/docker.adoc Normal file
View File

@ -0,0 +1,142 @@
= Docker
:idprefix:
:idseparator: -
One of the simplest ways to get started with ActiveMQ Artemis is by using one of our Docker images.
== Official Images
Official https://www.docker.com/[Docker] images are https://hub.docker.com/r/apache/activemq-artemis/tags[available on dockerhub].
Images are pushed along with all the other distribution artifacts for every release.
The fastest, simplest way to get started is with this command which will create and start a detached container named `mycontainer`, expose the main messaging port (i.e. `61616`) and HTTP port (i.e. `8161`), and remove it when it terminates:
[,console]
----
$ docker run --detach --name mycontainer -p 61616:61616 -p 8161:8161 --rm apache/activemq-artemis:latest-alpine
----
Once the broker starts you can open the xref:management-console.adoc[web management console] at http://localhost:8161 and log in with the default username & password `artemis`.
You can also use the `shell` command to interact with the running broker using the default username & password `artemis`, e.g.:
[,console]
----
$ docker exec -it mycontainer /var/lib/artemis-instance/bin/artemis shell --user artemis --password artemis
----
Using the `shell` command you can execute basic tasks like creating & deleting addresses and queues, sending and browsing messages, viewing queue statistics, etc.
See the xref:using-cli.adoc#command-line-interface[Command Line Interface] chapter for more details.
You can view the container's logs using:
[,console]
----
$ docker logs -f mycontainer
----
Stop the container using:
[,console]
----
$ docker stop mycontainer
----
The official Docker images are built using https://github.com/apache/activemq-artemis/tree/main/artemis-docker[these scripts] which you can also use to build your own images.
Read on for more details.
== Build your own Image
In order to build an image you need an ActiveMQ Artemis binary distribution.
This can be sourced *locally* (in which case you need to build the project first) or *remotely* based on an official Apache release.
=== Using a Local Release
If you want to use a local binary distribution then build it from the root of the ActiveMQ source tree, e.g.:
[,console]
----
$ mvn -Prelease package -DskipTests
----
Following the build the distribution files will be in your local distribution directory.
Here `<version>` is the version of the distribution that you built.
----
artemis-distribution/target/apache-artemis-<version>-bin/apache-artemis-<version>
----
Then switch to the `artemis-docker` directory and use the `prepare-docker.sh` script with the proper parameters to copy the Docker files into your local binary distribution, e.g.:
[,console]
----
$ cd artemis-docker
$ ./prepare-docker.sh --from-local-dist --local-dist-path ../artemis-distribution/target/apache-artemis-<version>-bin/apache-artemis-<version>/
----
This will copy all the files necessary to build any of the pre-configured Docker images and provide you with additional instructions.
Follow these instructions to finish building the image you want based on one of the provided Docker files or even one of your own.
=== Using an Official Apache Release
If you would rather use an official Apache release in your image rather than a local release then run the following command from the `artemis-docker` directory where `<version>` is the release version you wish to use (e.g. `2.30.0`):
[,console]
----
$ ./prepare-docker.sh --from-release --artemis-version <version>
----
This will copy all the files necessary to build any of the pre-configured Docker images and provide you with additional instructions.
Follow these instructions to finish building the image you want based on one of the provided Docker files or even one of your own.
=== Customizing the Image
==== Environment Variables
Environment variables determine the options configured for the `artemis create` command when running `docker build`.
The available options are:
`ARTEMIS_USER`::
The administrator username. The default is `artemis`.
`ARTEMIS_PASSWORD`::
The administrator password. The default is `artemis`.
`ANONYMOUS_LOGIN`::
Set to `true` to allow anonymous logins. The default is `false`.
`EXTRA_ARGS`::
Additional arguments sent to the `artemis create` command. The default is `--http-host 0.0.0.0 --relax-jolokia`.
Setting this value will override the default. See the documentation on `artemis create` for available options.
The combination of the above environment variables results in the `docker-run.sh` script calling the following command to create the broker instance the first time the Docker container runs:
[,console]
----
${ARTEMIS_HOME}/bin/artemis create --user ${ARTEMIS_USER} --password ${ARTEMIS_PASSWORD} --silent ${LOGIN_OPTION} ${EXTRA_ARGS}
----
Note: `LOGIN_OPTION` is either `--allow-anonymous` or `--require-login` depending on the value of `ANONYMOUS_LOGIN`.
These variables can be set in the relevant Dockerfile or, for example, on the command-line, e.g.:
[,console]
----
$ docker run -e ARTEMIS_USER=myUser -e ARTEMIS_PASSWORD=myPass --name mycontainer -it -p 61616:61616 -p 8161:8161 apache/activemq-artemis:latest-alpine
----
==== Mapping point
The image will use the directory `/var/lib/artemis-instance` to hold the configuration and the data of the running broker.
You can map this to a folder on the host for when you want the configuration and data persisted *outside* of a container, e.g.:
[,console]
----
docker run -it -p 61616:61616 -p 8161:8161 -v <broker folder on host>:/var/lib/artemis-instance apache/activemq-artemis:latest-alpine
----
In this case the value `<broker folder on host>` is a directory where the broker instance is supposed to
be saved and reused on each run.
==== Overriding files in `etc` folder
You can use customized configuration for the ActiveMQ Artemis instance by replacing the files residing in the `etc` folder with the custom ones, e.g. `broker.xml` or `artemis.profile`.
Put the replacement files inside a folder and map it as a volume to:
----
/var/lib/artemis-instance/etc-override
----
The contents of `etc-override` folder will be copied over to `etc` folder after the instance creation so that the broker will always start with user-supplied configuration.
It you are mapping the whole `var/lib/artemis-instance` to an outside folder for persistence then you can place an `etc-override` folder inside the mapped one.
Its contents will again be copied over `etc` folder after creating the instance.

1
docs/user-manual/index.adoc
View File

@ -37,6 +37,7 @@ image::images/activemq-logo.png[align="center"]
== Getting Started
* xref:docker.adoc#docker[Docker]
* xref:using-server.adoc#using-the-server[Using the Server]
* xref:using-cli.adoc#command-line-interface[Using the Command-Line Interface]
* xref:client-classpath.adoc#the-client-classpath[JMS & Jakarta Client Classpath]