Skip to content

Getting Started

Installation from an Archive

SwiftMQ 13.0.0+ ships with a bundled GraalVM CE runtime — no separate JDK installation is required.

  1. Download the distribution archive for your OS and architecture.
  2. Extract it to a directory of your choice.
  3. Navigate to the scripts/ directory and start the router:
./router [<preconfig-file> ...]

On Windows, enclose preconfig file paths in quotes.

Heap Memory

Set SWIFTMQ_JVMPARAM to adjust the JVM heap (default: -Xmx2G):

export SWIFTMQ_JVMPARAM="-Xmx4G"

Web Proxy

If the router needs outbound HTTP access through a proxy:

export proxyhost=192.168.178.34
export proxyport=9080

Directory Structure

Router Directory

data/
  config/
    routerconfig.xml
  deploy/
    dummy.txt
  log/
    dummy.txt
  preconfig/
    01-upgrade-to-12.1.0.xml
    02-upgrade-to-13.0.0.xml
    03-upgrade-to-13.1.0.xml
    04-upgrade-to-13.1.2.xml
  store/
    backup/
    db/
    durables/
    log/
    swap/
  streamlib/
    dummy.txt
  trace/
    dummy.txt
external-licenses/
  dom4j-license.txt
  GRAALVM_LICENSE.txt
  GRAALVM_THIRD_PARTY_LICENSE.txt
  jline-license.txt
  jquery-MIT-license.txt
  LICENSE-2.0.txt
LICENSE
NOTICE
optional-swiftlets/
  extension/
    dummy.txt
samples/
  amqp/
    ReceiverNonTransacted.java
    ReceiverNonTransactedDurable.java
    ReceiverTransactedAcquisition.java
    ReceiverTransactedRetirement.java
    ReplierNonTransacted.java
    RequestorNonTransacted.java
    SenderNonTransacted.java
    SenderTransacted.java
    starter
    starter.bat
  cli/
    AdminClient.java
    AdminClient$1.class
    CLIMessageInterface.java
    starter
    starter.bat
  Readme.txt
  router_network/
    P2PReceiver.java
    P2PReplier.java
    P2PRequestor.java
    P2PSender.java
    PubSubPublisher.java
    PubSubReplier.java
    PubSubRequestor.java
    PubSubSubscriber.java
    starter
    starter.bat
  streams/
    management/
    nuclear/
    ordercollect/
    replier/
scripts/
  checkconfig
  checkstore
  cli
  cli.bat
  cliamqp
  cliamqp.bat
  clis
  clis.bat
  repoamqp
  repoamqp.bat
  repojms
  repojms.bat
  router
  router.bat
  shutdown.cli
streams/
  lastvalue.js
  mailout.js
  messagescheduler.js
  routeannouncer.js
  streammonitor.js
  streamregistry.js
  streamrepository.js
version.properties
Directory Content
certs/ Self-signed TLS certificates and keystores
data/config/ Router configuration (routerconfig.xml)
data/log/ Log files (stdout.log, stderr.log)
data/store/ Persistent message store
data/preconfig/ Configuration patches applied on startup
data/deploy/ Extension Swiftlet deployment directory
graalvm-jdk/ Bundled GraalVM CE runtime
jars/ Java archive files
kernel/ Kernel Swiftlet jars and metadata
optional-swiftlets/extension/ Extension Swiftlets location
samples/ JMS, AMQP, CLI, and router network examples
scripts/ Shell scripts for router and CLI
streams/ System streams

Client Directory

  • scripts/ — Shell scripts for CLI and repository tools

Starting the Router

The router Script

Starts the SwiftMQ router. Optionally accepts additional preconfig XML files as a comma-delimited list (no spaces).

./router mypreconfig.xml
Parameters: [<preconfig1.xml,preconfig2.xml,...>]

The router script:

  • Sets SWIFTMQ_JVMPARAM for JVM heap size and system properties (can be customized)
  • Uses the bundled GraalVM CE runtime
  • Scans data/preconfig/ for configuration patches and applies them before startup
  • Logs output to data/log/stdout.log and data/log/stderr.log

Standard Configuration

The distribution ships with a single router named router and the following defaults:

Resource Protocol Port Details
JMS Listener PlainSocket 4001 JNDI names: plainsocket@router, ConnectionFactory, QueueConnectionFactory, TopicConnectionFactory
AMQP Listener Non-TLS 5672 AMQP 1.0
MQTT Listener Non-TLS 1883 MQTT 3.1.1
Routing Listener Non-TLS 4100 Inter-router routing

Predefined destinations:

  • Queue: testqueue (JNDI lookup available)
  • Topic: testtopic (JNDI lookup available)

Authentication is disabled by default. Log in as anonymous (press return) or use the administrator account (admin / secret).

Running as a Docker Container

Pull the Image

docker pull iitsoftware/swiftmq-ce:latest

<routername>/
    preconfig/
    data/

Basic Startup

docker run -d \
  -v /opt/myrouter/preconfig:/swiftmq/preconfig \
  -v /opt/myrouter/data:/swiftmq/data \
  -p 4001:4001 -p 5672:5672 -p 1883:1883 -p 4100:4100 \
  -e SWIFTMQ_PRECONFIG=/swiftmq/preconfig/preconfig.xml \
  iitsoftware/swiftmq-ce:latest
Option Purpose
-v <local>:/swiftmq/data Persist router data outside the container
-v <local>:/swiftmq/preconfig Mount preconfig XML files
-p <host>:<container> Expose listener ports
-e SWIFTMQ_PRECONFIG=... Comma-separated list of preconfig files
-e SWIFTMQ_JVMPARAM="-Xmx4G" JVM parameters (default: -Xmx2G)
### Preconfig for Docker

When JMS/JNDI clients connect from inside the container, add an internal listener:

<listener name="internal" port="5001" connectaddress="localhost"/>

For clients connecting from outside the container, use host.docker.internal (resolved automatically by Docker) as the connect address:

<listener name="external" port="5002" connectaddress="host.docker.internal"/>

Shutdown

Always use docker stop for a graceful shutdown — never docker kill, as it can corrupt the persistent store:

docker stop <container-id>

Docker Compose

services:
  swiftmq:
    image: "iitsoftware/swiftmq-ce:latest"
    ports:
      - "4001:4001"
      - "5672:5672"
      - "1883:1883"
      - "4100:4100"
    environment:
      - SWIFTMQ_PRECONFIG=/swiftmq/preconfig/mynode.xml
    volumes:
      - ./router/preconfig:/swiftmq/preconfig
      - ./router/data:/swiftmq/data

Router Networks on a Single Host

Multiple SwiftMQ containers can form a routing network. Expose the routing listener port (4100) on the first node and configure routing connectors in the other nodes' preconfig files. Use host.docker.internal to reach the Docker host:

<router name="edge2">
  <swiftlet name="sys$routing">
    <connectors _op="clear">
      <connector _op="add" name="edge1" hostname="host.docker.internal" port="4100"/>
    </connectors>
  </swiftlet>
</router>

On Linux, add extra_hosts: ["host.docker.internal:host-gateway"] to your Compose service if host.docker.internal is not available by default.

Connecting with the CLI

SwiftMQ provides several CLI scripts for managing the router:

cli

Starts an interactive CLI session, connecting to localhost:4001.

./cli

cliamqp

Connects via AMQP to localhost:5672. Optionally executes a CLI script file.

./cliamqp
Parameters: [<scriptfile>]

clis

Executes a CLI script file. Username and password are set inside the script.

./clis shutdown.cli
Parameters: <scriptfile>

repoamqp

Repository tool using AMQP protocol.

./repoamqp
Parameters: <command> [<args>]

repojms

Repository tool using JMS protocol.

./repojms
Parameters: <command> [<args>]

Shutting Down

To shut down the router gracefully, use the clis script with the bundled shutdown.cli script:

./clis shutdown.cli

This connects to the router, sends a shutdown command, and exits.

Client Tools

repoamqp

Repository tool using AMQP protocol.

./repoamqp

repojms

Repository tool using JMS protocol.

./repojms