You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by jb...@apache.org on 2023/09/26 20:54:18 UTC
[activemq-artemis] branch main updated (5eb02d247b -> cd1e9822f5)
This is an automated email from the ASF dual-hosted git repository.
jbertram pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
from 5eb02d247b ARTEMIS-4442 Redistributor Leaking Iterators
new f565e1318e ARTEMIS-4441 add Docker chapter to User Manual
new cd1e9822f5 NO-JIRA few small usability fixes
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
artemis-docker/docker-run.sh | 17 ++--
artemis-docker/readme.adoc | 1 +
artemis-docker/readme.md | 208 -------------------------------------------
docs/user-manual/docker.adoc | 142 +++++++++++++++++++++++++++++
docs/user-manual/index.adoc | 1 +
5 files changed, 149 insertions(+), 220 deletions(-)
create mode 100644 artemis-docker/readme.adoc
delete mode 100644 artemis-docker/readme.md
create mode 100644 docs/user-manual/docker.adoc
[activemq-artemis] 01/02: ARTEMIS-4441 add Docker chapter to User Manual
Posted by jb...@apache.org.
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 <jb...@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]
[activemq-artemis] 02/02: NO-JIRA few small usability fixes
Posted by jb...@apache.org.
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 cd1e9822f597b33474883c3c09397b0a7ef82f8c
Author: Justin Bertram <jb...@apache.org>
AuthorDate: Sat Sep 23 22:53:49 2023 -0500
NO-JIRA few small usability fixes
---
artemis-docker/docker-run.sh | 17 +++++------------
1 file changed, 5 insertions(+), 12 deletions(-)
diff --git a/artemis-docker/docker-run.sh b/artemis-docker/docker-run.sh
index c2b02163d5..f0f806c3c0 100755
--- a/artemis-docker/docker-run.sh
+++ b/artemis-docker/docker-run.sh
@@ -16,11 +16,8 @@
# specific language governing permissions and limitations
# under the License.
-
-
# This is the entry point for the docker images.
-# This file is executed when docker run is called.
-
+# This file is executed when "docker container create" or "docker run" is called.
set -e
@@ -34,19 +31,15 @@ else
LOGIN_OPTION="--require-login"
fi
-CREATE_ARGUMENTS="--user ${ARTEMIS_USER} --password ${ARTEMIS_PASSWORD} --silent ${LOGIN_OPTION} ${EXTRA_ARGS}"
-
-echo CREATE_ARGUMENTS=${CREATE_ARGUMENTS}
-
if ! [ -f ./etc/broker.xml ]; then
+ CREATE_ARGUMENTS="--user ${ARTEMIS_USER} --password ${ARTEMIS_PASSWORD} --silent ${LOGIN_OPTION} ${EXTRA_ARGS}"
+ echo CREATE_ARGUMENTS=${CREATE_ARGUMENTS}
/opt/activemq-artemis/bin/artemis create ${CREATE_ARGUMENTS} .
if [ -d ./etc-override ]; then
for file in `ls ./etc-override`; do echo copying file to etc folder: $file; cp ./etc-override/$file ./etc || :; done
fi
else
- echo "broker already created, ignoring creation"
+ echo "skipping broker instance creation; instance already exists"
fi
-exec ./bin/artemis "$@"
-
-
+exec ./bin/artemis "$@"
\ No newline at end of file