gemmellr commented on code in PR #225:
URL: https://github.com/apache/qpid-broker-j/pull/225#discussion_r1389259459


##########
qpid-docker/docker-build.sh:
##########
@@ -0,0 +1,181 @@
+#!/bin/sh
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from_local_dist=
+from_release=
+local_dist_path=
+qpid_version=
+MY_NAME=$(basename "$0")
+
+print_help()
+{
+  cat << END_OF_HELP
+Usage: $MY_NAME [OPTION]...
+
+ options:
+
+  --release          Apache Qpid Broker-J release version to build with
+  --local-dist-path  Path to the local Apache Qpid Broker-J distribution to 
build with
+  --help, -h, -?     Print this help and exit
+
+END_OF_HELP
+}
+
+parse_parameters()
+{
+  while [ $# -gt 0 ]; do
+    case $1 in
+      --local-dist-path)
+          from_local_dist=true
+          local_dist_path=$2
+          shift;;
+      --release)
+          from_release=true
+          qpid_version=$2
+          shift;;
+      --help | -h | -?)
+          print_help; exit 0;;
+      *)
+          echo "Unknown parameter '$1'"
+          exit 2;;
+    esac
+      shift
+  done
+
+  if [ -n "${local_dist_path}" ] && [ -n "${qpid_version}" ]; then
+    echo "Please specify either building image from local installation or from 
a particular release version, but not both"
+    exit 2
+  fi
+
+  if [ -z "${local_dist_path}" ] && [ -z "${qpid_version}" ]; then
+    print_help
+    echo "Please specify either building image from local installation or from 
a particular release version"
+    exit 2
+  fi
+
+  if [ -n "${local_dist_path}" ]; then
+
+    if [ ! -f "${local_dist_path}" ]; then
+      echo "Local distribution file ${local_dist_path} not found"
+      exit 1
+    fi
+
+    if [ "$(echo ${local_dist_path} | tail -c 7)" != "tar.gz" ]; then
+      echo "Local distribution file ${local_dist_path} should be a tar.gz 
archive"
+      exit 1
+    fi
+  fi
+}
+
+install()
+{
+  qpid_dist_dir="./qpid-broker-j"
+  qpid_dist_file_name=
+
+  # Prepare directory
+  if [ ! -d "${qpid_dist_dir}" ]; then
+    echo "Creating directory ${qpid_dist_dir}"
+    mkdir -p "${qpid_dist_dir}"
+  elif [ ! -z "$(find "${temp_dir}" -name "${qpid_version}" -type d -mmin 
+60)" ]; then
+    echo "Cleaning up directory ${qpid_dist_dir}"
+    rm -rf ${qpid_dist_dir}/*
+  else
+    echo "Using directory ${qpid_dist_dir}"
+  fi
+
+  if [ -n "${from_release}" ]; then
+
+    qpid_dist_file_name="apache-qpid-broker-j-${qpid_version}-bin.tar.gz"
+
+    # Check if the release is already available locally, if not try to 
download it
+    if [ -z "$(ls -A ${qpid_dist_dir})" ]; then
+      cdn="$(curl -s 
https://www.apache.org/dyn/closer.cgi\?preferred=true)/qpid/broker-j/${qpid_version}/binaries/"
+      
archive="https://archive.apache.org/dist/qpid/broker-j/${qpid_version}/binaries/";
+      qpid_base_url=${cdn}
+      curl_output="${qpid_dist_dir}/${qpid_dist_file_name}"
+
+      # Fallback to the apache archive if the version doesn't exist on the CDN 
anymore
+      if [ -z "$(curl -Is ${qpid_base_url}${qpid_dist_file_name} | head -n 1 | 
grep 200)" ]; then
+        qpid_base_url=${archive}
+
+        # If the archive also doesn't work then report the failure and abort
+        if [ -z "$(curl -Is ${qpid_base_url}${qpid_dist_file_name} | head -n 1 
| grep 200)" ]; then
+          echo "Failed to find ${qpid_dist_file_name}. Tried both ${cdn} and 
${archive}."
+          exit 1
+        fi
+      fi
+
+      echo "Downloading ${qpid_dist_file_name} from ${qpid_base_url}..."
+      curl --progress-bar "${qpid_base_url}${qpid_dist_file_name}" --output 
"${curl_output}"
+
+    fi
+
+  elif [ -n "${from_local_dist}" ]; then
+
+    qpid_dist_file_name=$(basename ${local_dist_path})
+    qpid_version=$(echo "$qpid_dist_file_name" | sed -e 
's/apache-qpid-broker-j-\(.*\)-bin.tar.gz/\1/')
+
+    echo "Broker-J distribution file is $qpid_dist_file_name"
+    echo "Broker-J version is $qpid_version"
+
+    echo "Copying ${local_dist_path} to ${qpid_dist_dir}..."
+    cp "$local_dist_path" "$qpid_dist_dir"
+
+  else
+    exit 2
+  fi
+
+  echo "Expanding ${qpid_dist_dir}/${qpid_dist_file_name}..."
+  tar xzf "${qpid_dist_dir}"/"${qpid_dist_file_name}" --directory 
"${qpid_dist_dir}" --strip 1
+
+  echo "Removing ${qpid_dist_dir}/${qpid_dist_file_name}..."
+  rm -rf "${qpid_dist_dir}"/"${qpid_dist_file_name}"
+
+  mkdir -p $qpid_dist_dir/${qpid_version}/docker/
+  cp ./broker.acl "$qpid_dist_dir/${qpid_version}/docker/"
+  cp ./*.json "$qpid_dist_dir/${qpid_version}/docker/"
+  cp ./Containerfile "$qpid_dist_dir/${qpid_version}/docker/"
+  cp -r $qpid_dist_dir/${qpid_version}/lib 
"$qpid_dist_dir/${qpid_version}/docker/"
+  cp ./entrypoint.sh "$qpid_dist_dir/${qpid_version}/docker/"
+}
+
+print_instruction()
+{
+  cat <<HERE
+
+Well done! Now you can continue with building the Docker image:
+
+  # Go to $qpid_dist_dir/${qpid_version}/docker/
+  $ cd $qpid_dist_dir/${qpid_version}/docker/
+
+  # For Ubuntu with JRE 17
+  $ docker build -f ./Containerfile -t qpid-ubuntu .
+
+  # For Alpine with JRE 17
+  $ docker build -f ./Containerfile --build-arg OS_NAME=alpine -t qpid-alpine .
+
+Note: -t qpid-ubuntu and -t qpid-alpine are just a tag names for the purpose 
of this guide
+
+For more info see readme.md

Review Comment:
   Nitpicking, it is actually named README.md



##########
qpid-docker/README.md:
##########
@@ -0,0 +1,234 @@
+## Docker Image Example
+
+This is an example on how a Docker Image For Apache Qpid Broker-J based on 
Eclipse Temurin JRE image can be created.
+
+## Building Container Image
+
+To use an official Apache release in your image run the following command from 
the qpid-docker directory where
+<QPID_RELEASE_VERSION> is the release version you wish to use (e.g. 9.1.0):
+
+```
+cd qpid-docker
+
+docker-build.sh --release <QPID_RELEASE_VERSION>
+```
+
+This will download the Qpid Broker-J release and copy all the files necessary 
to build the pre-configured Docker image
+and provide you with additional instructions. Follow these instructions to 
finish building the image you want based on
+the provided Docker file or even one of your own.
+
+If you would rather prefer to build the docker image from local Broker-J 
distribution, build the parent project using
+the command
+
+```
+mvn clean install -DskipTests=true
+```
+
+Navigate to the module 'qpid-docker':
+
+```
+cd qpid-docker
+```
+
+Execute the command
+
+```
+docker-build.sh --local-dist-path <PATH_TO_LOCAL_QPID_DISTRIBUTION>
+```
+
+This will copy all the files necessary to build the pre-configured Docker 
image and provide you with additional
+instructions. Follow these instructions to finish building the image you want 
based on one of the provided Docker file
+or even one of your own.
+
+### Container Structure
+
+Broker-J files are copied to the folder /qpid-broker-j \
+This folder belongs to user qpid, which is part of the root group. Java 
process is executed under the qpid user as well.
+
+### Running the Container
+
+Container can be started using following command:
+```
+docker run -d -p 5672:5672 -p 8080:8080 --name qpid <IMAGE_NAME>
+```
+There are two ports exposed: 5672 for AMQP connections and 8080 for HTTP 
connections.
+
+There are following environment variables available when running the container:
+
+| Environment Variable | Description                                           
                       |
+|----------------------|------------------------------------------------------------------------------|
+| JAVA_GC              | JVM Garbage Collector parameters, default value 
"-XX:+UseG1GC"               |
+| JAVA_MEM             | JVM memory parameters, default value "-Xmx300m 
-XX:MaxDirectMemorySize=200m" |
+| JAVA_OPTS            | Further JVM parameters, empty by default              
                       |
+
+#### Container Volume
+
+The image will use the directory /qpid-broker-j/work to hold the configuration 
and the data of the running broker.
+To persist the broker configuration and the data outside the container, start 
container with the volume mapping:
+
+```
+docker run -d -p 5672:5672 -p 8080:8080 -v 
<BROKER_DIRECTORY_ON_HOST>:/qpid-broker-j/work --name qpid <IMAGE_NAME>
+```
+or
+```
+podman run -d -p 5672:5672 -p 8080:8080 -v 
<BROKER_DIRECTORY_ON_HOST>:/qpid-broker-j/work:Z --name qpid <IMAGE_NAME>
+```
+
+### Broker Users
+
+Default configuration provides a preconfigured broker user, having read and 
write access to all broker objects:
+- admin (default password 'admin')
+
+Default password of the 'admin' user can be overridden be providing the 
variable QPID_ADMIN_PASSWORD on start:
+
+```
+docker run -d -p 5672:5672 -p 8080:8080 -v 
<BROKER_DIRECTORY_ON_HOST>:/qpid-broker-j/work -e 
QPID_ADMIN_PASSWORD=mypassword --name qpid <IMAGE_NAME>
+```
+
+Further broker users as well as other broker objects (queues, exchanges, 
keystores, truststore, ports etc.)
+can be created via HTTP management interface. Description of the broker REST 
API can be found in broker book (chapter 6.3).
+
+To change user password following command can be used:
+
+```
+curl -d '{"password": "<NEW_PASSWORD>"}' 
http://admin:admin@localhost:8080/api/latest/user/plain/<USERNAME>
+```
+
+## Broker Customization
+
+To customize broker before building the container image, its configuration 
files may be edited to start broker with
+queues, exchanges, users or other objects.
+
+The file config.json contains definitions of the broker objects and references 
a file containing definitions
+of virtualhost objects (exchanges and queues).
+
+It may be helpful first to create broker objects needed via broker web GUI or 
via REST API, and then investigate the
+configuration files and copy the appropriate definitions to the configuration 
files used for container image creation.
+
+An example of the default initial configuration JSON file is provided in 
broker book (chapter 5.7).
+
+### Exchanges
+
+To create exchanges a JSON element "exchanges" should be created containing an 
array of single exchange definitions:
+
+```
+"exchanges" : [ {
+      "name" : "amq.direct",
+      "type" : "direct"
+    }, {
+      "name" : "amq.fanout",
+      "type" : "fanout"
+    }, {
+      "name" : "amq.match",
+      "type" : "headers"
+    }, {
+      "name" : "amq.topic",
+      "type" : "topic"
+    }, {
+      "name" : "request.QUEUE1",
+      "type" : "topic",
+      "durable" : true,
+      "durableBindings" : [ {
+        "arguments" : { },
+        "destination" : "QUEUE1",
+        "bindingKey" : "#"
+    } ],
+    "unroutableMessageBehaviour" : "REJECT"
+  }
+]
+```
+
+Information about exchanges, their types and properties can be found in broker 
book (chapter 4.6).
+
+Please note that each virtualhost pre-declares several exchanges, described in 
the broker book (chapter 4.6.1).
+
+### Queues
+
+To create queue a JSON element "queues" should be created containing an array 
of single queue definitions:
+
+```
+"queues" : [ {
+    "name" : "QUEUE1",
+    "type" : "standard",
+    "durable" : true,
+    "maximumQueueDepthBytes" : 6144000,
+    "maximumQueueDepthMessages" : 6000,
+    "messageDurability" : "ALWAYS",
+    "overflowPolicy" : "REJECT"
+  }, {
+    "name" : "QUEUE2",
+    "type" : "standard",
+    "durable" : true,
+    "maximumQueueDepthBytes" : 6144000,
+    "maximumQueueDepthMessages" : 6000,
+    "messageDurability" : "ALWAYS",
+    "overflowPolicy" : "REJECT"
+  }
+]
+```
+
+Information about queues, their types and properties can be found in broker 
book (chapter 4.7).
+
+### Users
+
+Users can be defined in an authentication provider. Authentication providers 
are defined on broker level (file config.json).
+
+Information about authentication providers, their types and properties can be 
found in broker book (chapter 8.1).
+
+Examples for most commonly used authentication providers can be found below.
+
+#### Anonymous Authentication Provider
+
+```
+"authenticationproviders" : [ {
+    "name" : "anon",
+    "type" : "Anonymous"
+  } ]
+```
+For additional details see broker book (chapter 8.1.5).
+
+#### Plain Authentication Provider
+
+```
+"authenticationproviders" : [{
+    "name" : "plain",
+    "type" : "Plain",
+    "secureOnlyMechanisms" : [],
+    "users" : [ {
+      "name" : "admin",
+      "type" : "managed",
+      "password" : "<PASSWORD>"
+    } ]
+  } ]
+```
+
+For additional details see broker book (chapter 8.1.7).
+
+#### ACL Rules
+
+The ACL rules for users are defined in file broker.acl following the syntax:
+
+```
+ACL {permission} {<group-name>|<user-name>|ALL} {action|ALL} [object|ALL] 
[property=<property-values>]
+```
+
+The predefined broker.acl file contains permissions for the 'admin' user:
+
+```
+# account 'admin' - enabled all actions
+ACL ALLOW-LOG admin ALL ALL
+```
+
+For additional details see broker book (chapter 8.3.2).
+
+### Overriding Broker Configuration
+
+Customized configuration for the Broker-J instance can be used by replacing 
the files residing in the work folder with 
+the custom ones, e.g. config.json or default.json. Put the replacement files 
inside a folder and map it as a volume to:
+
+```
+docker run -d -p 5672:5672 -p 8080:8080 -v 
<DIRECTORY_ON_HOST>:/qpid-broker-j/work-override:Z --name qpid <IMAGE_NAME>
+```
+
+The contents of work-override folder will be copied over to work folder after 
the instance creation so that the broker 
+will start with user-supplied configuration.

Review Comment:
   This could probably be a bit clearer on whether they are copied each time 
the container starts, or only the first time, which would make a big difference 
to how it could actually be used.
   
   The script itself seems quite clear, its just this description that is a 
touch ambiguous, which might be all a user actually sees [or more likely, the 
copy on the website in the book] if using a published image.



##########
qpid-docker/README.md:
##########
@@ -0,0 +1,234 @@
+## Docker Image Example
+
+This is an example on how a Docker Image For Apache Qpid Broker-J based on 
Eclipse Temurin JRE image can be created.
+
+## Building Container Image
+
+To use an official Apache release in your image run the following command from 
the qpid-docker directory where
+<QPID_RELEASE_VERSION> is the release version you wish to use (e.g. 9.1.0):
+
+```
+cd qpid-docker
+
+docker-build.sh --release <QPID_RELEASE_VERSION>
+```
+
+This will download the Qpid Broker-J release and copy all the files necessary 
to build the pre-configured Docker image
+and provide you with additional instructions. Follow these instructions to 
finish building the image you want based on
+the provided Docker file or even one of your own.
+
+If you would rather prefer to build the docker image from local Broker-J 
distribution, build the parent project using
+the command
+
+```
+mvn clean install -DskipTests=true
+```
+
+Navigate to the module 'qpid-docker':
+
+```
+cd qpid-docker
+```
+
+Execute the command
+
+```
+docker-build.sh --local-dist-path <PATH_TO_LOCAL_QPID_DISTRIBUTION>
+```
+
+This will copy all the files necessary to build the pre-configured Docker 
image and provide you with additional
+instructions. Follow these instructions to finish building the image you want 
based on one of the provided Docker file
+or even one of your own.
+
+### Container Structure
+
+Broker-J files are copied to the folder /qpid-broker-j \
+This folder belongs to user qpid, which is part of the root group. Java 
process is executed under the qpid user as well.
+
+### Running the Container

Review Comment:
   Might be worth adding a line somewhere about stopping the started container 
for completeness.



##########
qpid-docker/README.md:
##########
@@ -0,0 +1,234 @@
+## Docker Image Example
+
+This is an example on how a Docker Image For Apache Qpid Broker-J based on 
Eclipse Temurin JRE image can be created.
+
+## Building Container Image
+
+To use an official Apache release in your image run the following command from 
the qpid-docker directory where
+<QPID_RELEASE_VERSION> is the release version you wish to use (e.g. 9.1.0):
+
+```
+cd qpid-docker
+
+docker-build.sh --release <QPID_RELEASE_VERSION>
+```
+
+This will download the Qpid Broker-J release and copy all the files necessary 
to build the pre-configured Docker image
+and provide you with additional instructions. Follow these instructions to 
finish building the image you want based on
+the provided Docker file or even one of your own.
+
+If you would rather prefer to build the docker image from local Broker-J 
distribution, build the parent project using
+the command
+
+```
+mvn clean install -DskipTests=true
+```
+
+Navigate to the module 'qpid-docker':
+
+```
+cd qpid-docker
+```
+
+Execute the command
+
+```
+docker-build.sh --local-dist-path <PATH_TO_LOCAL_QPID_DISTRIBUTION>
+```
+
+This will copy all the files necessary to build the pre-configured Docker 
image and provide you with additional
+instructions. Follow these instructions to finish building the image you want 
based on one of the provided Docker file
+or even one of your own.
+
+### Container Structure
+
+Broker-J files are copied to the folder /qpid-broker-j \
+This folder belongs to user qpid, which is part of the root group. Java 
process is executed under the qpid user as well.
+
+### Running the Container
+
+Container can be started using following command:
+```
+docker run -d -p 5672:5672 -p 8080:8080 --name qpid <IMAGE_NAME>
+```
+There are two ports exposed: 5672 for AMQP connections and 8080 for HTTP 
connections.
+
+There are following environment variables available when running the container:
+
+| Environment Variable | Description                                           
                       |
+|----------------------|------------------------------------------------------------------------------|
+| JAVA_GC              | JVM Garbage Collector parameters, default value 
"-XX:+UseG1GC"               |
+| JAVA_MEM             | JVM memory parameters, default value "-Xmx300m 
-XX:MaxDirectMemorySize=200m" |
+| JAVA_OPTS            | Further JVM parameters, empty by default              
                       |
+
+#### Container Volume
+
+The image will use the directory /qpid-broker-j/work to hold the configuration 
and the data of the running broker.
+To persist the broker configuration and the data outside the container, start 
container with the volume mapping:
+
+```
+docker run -d -p 5672:5672 -p 8080:8080 -v 
<BROKER_DIRECTORY_ON_HOST>:/qpid-broker-j/work --name qpid <IMAGE_NAME>
+```
+or
+```
+podman run -d -p 5672:5672 -p 8080:8080 -v 
<BROKER_DIRECTORY_ON_HOST>:/qpid-broker-j/work:Z --name qpid <IMAGE_NAME>
+```
+
+### Broker Users
+
+Default configuration provides a preconfigured broker user, having read and 
write access to all broker objects:
+- admin (default password 'admin')
+
+Default password of the 'admin' user can be overridden be providing the 
variable QPID_ADMIN_PASSWORD on start:
+
+```
+docker run -d -p 5672:5672 -p 8080:8080 -v 
<BROKER_DIRECTORY_ON_HOST>:/qpid-broker-j/work -e 
QPID_ADMIN_PASSWORD=mypassword --name qpid <IMAGE_NAME>
+```

Review Comment:
   I somewhat expect some folks using this to come asking for the ability to 
configure the as well as its common to offer both. Could just wait for it to be 
requested, but I'd still perhaps avoid putting the username into the env 
variable name to more easily accommodate such change later.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org
For additional commands, e-mail: dev-h...@qpid.apache.org

Reply via email to