This is an automated email from the ASF dual-hosted git repository.
jbertram pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
commit f565e1318e39d1f6e04766933ed7368b125948fc
Author: Justin Bertram <jbert...@apache.org>
AuthorDate: Thu Sep 21 16:40:34 2023 -0500
ARTEMIS-4441 add Docker chapter to User Manual
---
artemis-docker/readme.adoc | 1 +
artemis-docker/readme.md | 208 -------------------------------------------
docs/user-manual/docker.adoc | 142 +++++++++++++++++++++++++++++
docs/user-manual/index.adoc | 1 +
4 files changed, 144 insertions(+), 208 deletions(-)
diff --git a/artemis-docker/readme.adoc b/artemis-docker/readme.adoc
new file mode 100644
index 0000000000..74623201ac
--- /dev/null
+++ b/artemis-docker/readme.adoc
@@ -0,0 +1 @@
+See the Docker documentation in the
xref:../docs/user-manual/docker.adoc[ActiveMQ Artemis User Manual].
\ No newline at end of file
diff --git a/artemis-docker/readme.md b/artemis-docker/readme.md
deleted file mode 100644
index c245ab32de..0000000000
--- a/artemis-docker/readme.md
+++ /dev/null
@@ -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.
diff --git a/docs/user-manual/docker.adoc b/docs/user-manual/docker.adoc
new file mode 100644
index 0000000000..f8a4016e8d
--- /dev/null
+++ b/docs/user-manual/docker.adoc
@@ -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.
diff --git a/docs/user-manual/index.adoc b/docs/user-manual/index.adoc
index bdbc2bcbbd..4063e5d396 100644
--- a/docs/user-manual/index.adoc
+++ b/docs/user-manual/index.adoc
@@ -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]
