Requirements

SwiftMQ requires Java 11 or later.

The Streams Swiftlet requires a JavaScript scripting engine which is part of the JDK up to Java 14 (Nashorn scripting engine). From Java 15 onwards the Nashorn scripting engine has been removed from the JDK. SwiftMQ detects that during startup and disables the Streams Swiftlet automatically. So, all functionality provided from this Swiftlet like the message scheduler will be unavailable.

To use Java 15 or later with Streams Swiftlet, you need to run SwiftMQ with GraalVM CE which is a next-generation polyglot JVM, based on the standard OpenJDK and provided by Oracle. SwiftMQ has been highly optimized for GraalVM and we recommend using it instead of the standard OpenJDK.

GraalVM CE is free and can be obtained from https://graalvm.org.

Installation from an Archive

Distribution Content

After you have unpacked the archive, you will find the following directory structure below the distribution's top-level directory:

Directory

Content

certs

Self signed TLS certificates and server/client key stores.

data

All dynamic data of the router like configuration, logs, persistent store

hatest

Scripts and config files for the HA test suite

jars

jar files

kernel

jar files and config meta data of all Kernel Swiftlets

opt

Standard file based and JDBC Store Swiftlets (internal use).

optional-swiftlets

Extension Swiftlets JMS, AMQP, JavaMail Bridges and Replicator and Kernel Swiftlet replacements Authentication JDBC and Store JDBC.

preconfig

Collection of preconfig files to configure a HA instance initially

samples

SwiftMQ samples

scripts

Shell scripts to start the router and cli

shared

Default location of a shared file store

streams

SwiftMQ system streams

Initial configuration of a HA Instance with preconfig

The distribution (and the docker image too) contains the configuration of a single HA instance. It is REQUIRED that preconfig files are applied so that 2 HA instances are created.

Directory preconfig/ contains the following preconfig files (the preconfig files can be downloaded separately for docker installations):

  • hostports.xml (AMQP, JMS, MQTT, Routing hosts/ports)

  • repllistener.xml (Replication channel listener)

  • replconnector.xml (Replication channel connector)

  • replicatedstore.xml (Replicated File Store)

  • sharedstore.xml (Shared File Store)

  • jdbcstore.xml (JDBC File Store)

These files need to be changed according to your requirements and can then be combined to configure each of the 2 HA instances.

A SwiftMQ HA instance deploys all available Extension Swiftlets during the first startup. You need to stop and start the Docker container to apply preconfig files for Extension Swiftlets after the initial deployment.

Example

Say you have a Primary instance on hostA and a Secondary instance on hostB. On both hosts you have a fresh distribution copy. You want a Replicated File Store where the Primary should have the replication channel listener and the Secondary the connector. The router name should be testrouter. You only need a JMS listener, no AMQP/MQTT/Routing.

Primary (hostA)

hostports.xml:

<router name="testrouter">
  <swiftlet name="sys$amqp">
    <listeners _op="clear" />
  </swiftlet>

  <swiftlet name="sys$jms">
    <listeners _op="replace">
      <listener name="plainsocket" hostname="localhost" port="4001" hostname2="localhost" port2="4001" 
                connectaddress="hostA" connectaddress2="hostB"/>
    </listeners>
  </swiftlet>

  <swiftlet name="sys$mqtt">
    <listeners _op="clear" />
      <listener name="mqtt"/>
  </swiftlet>

  <swiftlet name="sys$routing">
    <listeners _op="clear"/>
  </swiftlet>
</router>
XML

All other preconfig files remain unchanged, we use the defaults.

We apply these preconfig files to the Primary:

hostports.xml,repllistener.xml,replicatedstore.xml
CODE
Secondary (hostB)

hostports.xml (identical with Primary):

<router name="testrouter">
  <swiftlet name="sys$amqp">
    <listeners _op="clear" />
  </swiftlet>

  <swiftlet name="sys$jms">
    <listeners _op="replace">
      <listener name="plainsocket" hostname="localhost" port="4001" hostname2="localhost" port2="4001" 
                connectaddress="hostA" connectaddress2="hostB"/>
    </listeners>
  </swiftlet>

  <swiftlet name="sys$mqtt">
    <listeners _op="clear" />
      <listener name="mqtt"/>
  </swiftlet>

  <swiftlet name="sys$routing">
    <listeners _op="clear"/>
  </swiftlet>
</router>
XML

replconnector.xml:

<router>
  <swiftlet name="sys$hacontroller">
    <replication-channel _op="replace">
      <connectors>
        <connector name="1" hostname="hostA" port="2001"/>
      </connectors>
    </replication-channel>
  </swiftlet>
</router>
XML

All other preconfig files remain unchanged, we use the defaults.

We apply these preconfig files to the Secondary:

hostports.xml,replconnector.xml,replicatedstore.xml
CODE

Starting the HA Instance

To start a HA instance, go to the scripts directory and perform a:

./router <list of preconfig files>
BASH

<list of preconfig files> is a comma-separated list (no spaces) of the preconfig files you apply to this HA instance.

If you start it under Windows, please set the preconfig files in double quotes!

For the example above this would be:

Primary on hostA:

./router ../preconfig/hostports.xml,../preconfig/repllistener.xml,../preconfig/replicatedstore.xml
BASH

Secondary on hostB:

./router ../preconfig/hostports.xml,../preconfig/replconnector.xml,../preconfig/replicatedstore.xml
BASH

Running SwiftMQ HA as Docker Container with Docker Compose

Directory Structure

The recommended directory structure for a HA instance is:

<routername>
    data/
    jdbc-driver/ <-- only necessary if you use the JDBC Store Swiftlet
    preconfig/
CODE

Download SwiftMQ HA Docker Distribution and Load

For each host (usually 2) you need to download the Docker distribution and load it as a Docker image:

docker load < <name of the tar.gz>
BASH

The Docker image is then available as:

swiftmq-ha:<version>  (i.e. swiftmq-ha:12.1.0)
CODE

Download and modify the Preconfig Files

Download the preconfig zip file and unpack it so that the XML files are stored under:

<routername>/preconfig
CODE

Modify it according to the instructions above.

Docker Compose File for HA Instance 1

We assume HA instance 1 has the replication listener on port 2001 and the JMS listener enabled:

version: '3'
services:
  swiftmq:
    image: "swiftmq-ha:12.1.0"
    ports:
      - "4001:4001" # JMS
      - "2001:2001" # HA Replication Listener
    environment:
      - SWIFTMQ_PRECONFIG=/swiftmq/preconfig/hostports.xml,/swiftmq/preconfig/repllistener.xml,/swiftmq/preconfig/replicatedstore.xml
      - SWIFTMQ_JVMPARAM=-Xmx4G  
     #- SWIFTMQ_STORETYPE=JDBC
    volumes:
        - ${pwd}/preconfig:/swiftmq/preconfig
        - ${pwd}/data:/swiftmq/data
      # - ${pwd}/jdbc-driver:/swiftmq/jdbc-driver
YAML

Environment variable SWIFTMQ_PRECONFIG contains the preconfiguration of that instance. Note the repllistener.xml which preconfigures the replication listener for this instance. All directory names are /swiftmq/preconfig as this directory is mapped in the volumes section to the local preconfig/directory.

In case you use the JDBC Store Swiftlet, you need the jdbcstore.xml instead of the replicatedstore.xml and you need to store the jar files with the JDBC driver under <routername>/jdbc-driver. You further need to uncomment the above SWIFTMQ_STORETYPE environment variable and the jdbc-driver mapping under volumes.

To overwrite the default JVM parameters, set environment variable SWIFTMQ_JVMPARAM accordingly:

-e SWIFTMQ_JVMPARAM="-Xmx4G"
YAML

The default setting is -Xmx2G. Since SwiftMQ runs on GraalVM inside the Docker container, you must use the settings for GraalVM.

Store this content as docker-compose.yml under the <routername>/ directory.

Docker Compose File for HA Instance 2

HA instance 2 is similar, except it has the replication connector:

version: '3'
services:
  swiftmq:
    image: "swiftmq-ha:12.1.0"
    ports:
      - "4001:4001" # JMS
    environment:
      - SWIFTMQ_PRECONFIG=/swiftmq/preconfig/hostports.xml,/swiftmq/preconfig/replconnector.xml,/swiftmq/preconfig/replicatedstore.xml
      - SWIFTMQ_JVMPARAM=-Xmx4G  
     #- SWIFTMQ_STORETYPE=JDBC
    volumes:
        - ${pwd}/preconfig:/swiftmq/preconfig
        - ${pwd}/data:/swiftmq/data
      # - ${pwd}/jdbc-driver:/swiftmq/jdbc-driver
YAML

Start Script per HA Instance

On each HA instance create a script file under <routername>/ with the following content and make it executable:

#!/bin/bash

export myIP=`ifconfig $(netstat -rn | grep -E "^default|^0.0.0.0" | head -1 | awk '{print $NF}') | grep 'inet ' | awk '{print $2}' | grep -Eo '([0-9]*\.){3}[0-9]*'`
export pwd=`pwd`

case "$1" in
  start)
        docker-compose up -d
    ;;
  stop)
        docker-compose down
    ;;
  status)
        docker ps
    ;;
  *)
    echo "Usage: $N {start|stop|status}"
    exit 1
    ;;
esac
exit 0
BASH

You can now start and stop each HA instance. You'll find the output of the startup under;

<routername>/data/log/stdout.log
<routername>/data/log/stderr.log
CODE

Standard HA Configuration

The standard HA configuration is for a single HA instance and identical to SwiftMQ UR except that it adds attributes for the second instance for JMS/Routing and adds a replication listener on port 2001.

Starting CLI

To start CLI, SwiftMQ's command-line interface, perform a

./cli
Copy
CODE

from the scripts directory. As username/password press the return key (anonymous) or use admin, password secret.

Examples

SwiftMQ HA contains the same examples as SwiftMQ UR.