The source code of artemis-container serving to build and use image is free & opensource software. It's licensed under the Apache 2.0 license. This source code is available to anonymous download on Bitbucket platform.

These source files allows to build a modified version of the container image if needed. The container image build, its recovery and use requires the prior installation of Docker on the target system. An Internet connection is also required for those tasks. To build a new image, assuming location is root of the cloned local repository:

This command downloads stuff needed from remote sites and builds the image to make it available locally. This may take a time from few tens seconds, to few tens minutes depending on the performance of your local site and network speed. Of course, you can choose a different tag instead of « ameddeb/artemis-container:1.0 ». The custom tag must follows the Docker tag rules. To locally recover the image stored on Docker hub public registry:

To run a standalone without TLS container, assuming location is root of the cloned local repository:

Launch the container in this way may help for purpose of software development using Artemis MoM. It helps, also, for test and debug a custom image in case you need it. The stop parameter allows to stop container.

To deploy the container as a cluster, you should first configure the nodes to use. Then copy all the files in the deployment/ folder to a manager node. Finally, on this manager node, in the folder that contains those files, execute:

This command deploy the artemis container cluster according to the settings contained in the provided configuration files. This can help to tuning a real deployment but you should not necessarily use these settings. Especially for credentials and the certificates keystores. See the setup section for further details about how to configure the cluster deployment.

Security warning: The provided certificates keystores and the credentials in the container configuration file must never used as is in real deployment on production platform. For such deployment you must change credentials and make your own certificates.

Needed messages addresses must be added to the main configuration file template: broker.xml.tmpl. This customization is done within <addresses> element. The location of this addition is indicated by the comment: “Add here the configuration of your addresses”. The following example add an address called functionalTrace.accounting:

We may setting a role-based security policy through a customization of the <security-settings> element. The default configuration, simply allows some rights for default amq role. Adding other roles and/or modifying existing configuration should done in this element within configuration file template. The location of this addition is indicated by the comment: “Add here the configuration of your additional role-based security settings”. The following example add security setting for added functionalTrace.accounting address, assuming that functrace is an additional role (see below):

For further details about configuring messages addresses and role-based security in the broker.xml configuration file see this topic in the Artemis documents.

The users list and users/roles mapping are setting through two files (file names are mandatory). Customizing these files allows to define several user / role combinations when needed.

• artemis-users.properties: Contains authorized users credentials list, one per line
• artemis-roles.properties: Contains roles/users mapping, one role per line

This configuration is done through parameters stored in the container configuration file. This file is supplied through CONTAINER_CONFIG environment variable. Those parameters are:

TLS parameter	Content	Possible values	JVM parameter	Content	Possible values
kspwd	Server certificate keystore password	strong strength password value	minmem	JVM heap minimum memory allocation	Value that depends on the RAM allocated to the container
tspwd	Server trusted certificates keystore password	strong strength password value	maxmem	JVM heap maximum memory allocation	Value that depends on the RAM allocated to the container
ksipwd	Cluster internal certificate keystore password	strong strength password value	jvmgc	JVM Garbage collector setting	G1GC or ConcMarkSweepGC
twowayauth	Enabling Two-Way client authentication	true or false	ipv4	IP v4 preference enabling	true or false
verifyhost	Client host domain verification	true or false

When Two-Way client authentication is enabled, the clients who want to connect and use the servers cluster must provide a certificate that trusted by servers. In addition, if client host domain verification is enabled, the client must be running on a host in the domaine contained in the provided certificate.

At each startup, the Artemis container executes the entrypoint.sh script. This script uses the contents of container image embedded environment variables and the supplied configuration file template to build the Apache Artemis broker.xml master configuration file. This construction is done by the substitution of the tags contained in the template by the content of some environment variables. Other environment variables are used to specify configuration files and authentication certificates.

The swarm-deploy.yml deployment descriptor file is used to define the contents of these environment variables, the configuration and certificate files. This allows to reset these contents and parameters each time the container is restarted allowing configuration update.

The tags in the broker.xml.tmpl template file are used to setting the master configuration file broker.xml as following:

Tag	Content	Replacement	Origin type	Replacement origin
{ARTEMISHOST}	Container host FQN	hostname -f command	Dynamic	entrypoint.sh command script
{KSFILE}	Server certificate keystore full qualified file name	KEYSTORE_FILE	Environement variable	Supplied certificate file
{TSFILE}	Server trusted certificates keystore full qualified file name	TRUSTSTORE_FILE	Environement variable	Supplied certificate file
{KSIFILE}	Server to server, cluster internal, authentication certificate keystore file name	KEYSTORE_FILE_INT	Environement variable	Supplied certificate file
{KSPWD}	Server certificate keystore password	kspwd parameter value	Parameter value	Container configuration file
{TSPWD}	Server trusted certificates keystore password	tspwd parameter value	Parameter value	Conteiner configuration file
{KSIPWD}	Server to server, cluster internal, authentication certificate keystore password	ksipwd parameter value	Parameter value	Container configuration file
{ARTEMISCLUSTERUSER}	Server to server, cluster internal authentication, username	clusteruser parameter value	Parameter value	Container configuration file
{ARTEMISCLUSTERPWD}	Server to server, cluster internal authentication, password	clusterpwd parameter value	Parameter value	Container configuration file

Those files are supplied to container at startup through Docker config and Docker secret. These mechanisms allows to easy rotate the contents of the parameters:

• The server certificate keystore file
• The trusted certificates keystore file
• The server to server certificate keystore file
• artemis-users.properties: Authorized users credentials list
• artemis-roles.properties: Authorized users/roles mapping
• The container configuration file that referred by CONTAINER_CONFIG environment variable