Docker

One of the simplest ways to get started with ActiveMQ Artemis is by using one of our Docker images.

1. Official Images

Official Docker images are 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:

$ 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 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.:

$ 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 Command Line Interface chapter for more details.

You can view the container’s logs using:

$ docker logs -f mycontainer

Stop the container using:

$ docker stop mycontainer

The official Docker images are built using these scripts which you can also use to build your own images. Read on for more details.

2. 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.

2.1. 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.:

$ 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.:

$ 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.

2.2. 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):

$ ./prepare-docker.sh --from-release --artemis-version <version>

2.3. Customizing the Image

2.3.1. 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:

${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.:

$ docker run -e ARTEMIS_USER=myUser -e ARTEMIS_PASSWORD=myPass --name mycontainer -it -p 61616:61616 -p 8161:8161 apache/activemq-artemis:latest-alpine

2.3.2. 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.:

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.

2.3.3. 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.