143 lines
6.3 KiB
Plaintext
143 lines
6.3 KiB
Plaintext
= 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.
|