Skip to main content

Install

This guide installs the mq-gateway binary or runs the container image. Synadia distributes both. To get access, contact Synadia or start a trial.

Before you start, you need:

  • The download or registry credentials that Synadia gave you.
  • Linux, macOS or Windows, on amd64 or arm64.

The binary needs nothing else on the machine. It connects to your NATS servers, or runs a NATS server inside itself to try it out.

1. Download the archive​

Each release is on artifacts.synadia.io under mq-gateway/v<version>/. The archive is mq-gateway-v<version>-<os>-<arch>.tar.gz. <os> is linux, darwin or windows. Windows archives are .zip.

curl -fLO -u <user>:<password> \
  https://artifacts.synadia.io/mq-gateway/v0.1.2/mq-gateway-v0.1.2-linux-amd64.tar.gz
curl -fLO -u <user>:<password> \
  https://artifacts.synadia.io/mq-gateway/v0.1.2/checksums.txt

2. Check the download​

Compare the archive with checksums.txt. Each file you have prints OK:

sha256sum --check --ignore-missing checksums.txt          # Linux
shasum -a 256 --check --ignore-missing checksums.txt      # macOS

On Windows, compare this output with the line in checksums.txt:

(Get-FileHash mq-gateway-v0.1.2-windows-amd64.zip).Hash.ToLower()

3. Run the binary​

tar -xzf mq-gateway-v0.1.2-linux-amd64.tar.gz
cd mq-gateway-v0.1.2-linux-amd64
./mq-gateway --version
sudo install mq-gateway /usr/local/bin/

--version prints 0.1.2. To serve MQTT on port 1883 and AMQP on port 5672 with your NATS server:

mq-gateway --mqtt --amqp --nats.url nats://nats.example.com:4222

On Windows, unpack the zip and run .\mq-gateway.exe --version.

  • macOS: Apple notarizes the binary. The first run on a machine needs network access, because macOS checks the notarization with Apple.
  • Windows: the binary has no code signature. SmartScreen can ask before the first run. Windows has no SIGUSR2. To start lame duck mode, send the ldm admin request.

Run the container image​

The images are on registry.synadia.io, for linux/amd64 and linux/arm64. Log in with your registry credentials:

docker login registry.synadia.io
docker run --rm registry.synadia.io/mq-gateway:0.1.2 --version

The image holds only the gateway, with no shell. It runs as user 65532 and writes nothing to disk, so a read-only root filesystem works. Arguments after the image name are gateway flags.

Mount the config file read-only. User 65532 must be able to read it and each file it names:

docker run -d --name mq-gateway --read-only -p 1883:1883 \
  -v "$PWD/gateway.yaml:/etc/mq-gateway/gateway.yaml:ro" \
  registry.synadia.io/mq-gateway:0.1.2 \
  --config /etc/mq-gateway/gateway.yaml
  • In nats.url, localhost is the container itself. Use an address that the container can reach.
  • docker stop closes all connections immediately.
  • docker kill --signal SIGUSR2 mq-gateway starts lame duck mode. Lame duck mode closes the connections a few at a time.

Run a licensed build​

A trial uses the licensed build. The licensed build serves only with a Synadia license for MQ Gateway. Other builds ignore a license.

The trial email includes:

  • Links to the archives, named mq-gateway-v<version>-<os>-<arch>-licensed.tar.gz.
  • Credentials for the image registry.synadia.io/mq-gateway-licensed.
  • The license, a JWT.

Install the licensed build with the steps above. Then put the JWT in a file and give the gateway its path:

mq-gateway --config gateway.yaml --license.file /etc/mq-gateway/license.jwt

You can also set license.file in the config file, or MQGW_LICENSE_FILE. To give the JWT itself, use --license.token, MQGW_LICENSE_TOKEN or license.token. If you set both, the gateway uses the file.

In a container, mount the license file read-only:

docker run -d --name mq-gateway --read-only -p 1883:1883 \
  -v /path/to/license.jwt:/etc/mq-gateway/license.jwt:ro \
  registry.synadia.io/mq-gateway-licensed:0.1.2 \
  --mqtt --license.file /etc/mq-gateway/license.jwt \
  --nats.url nats://nats.example.com:4222

Only serving needs the license. check, generate and playground run without one.

Check it works​

mq-gateway --version prints the version.

A licensed build that accepts its license logs its terms at start:

level=INFO msg="license validated" team="Example Corp" contract_type=trial expires_at=2027-01-31T00:00:00Z grace_period_end=2027-02-14T00:00:00Z

If a licensed build refuses its license, it prints the reason. Then it exits with status 1 before it opens a port:

MessageFix
this build needs a licenseSet license.file or license.token.
invalid license: ...Use the JWT from Synadia, with no changes.
license does not entitle MQ GatewayAsk Synadia for an MQ Gateway license.
license expired ... and its grace period ended ...Install a new license.

When the license expires​

  • During the grace period, the gateway starts and logs a warning.
  • A running gateway continues to serve after the expiry. It logs a warning at the expiry and an error when the grace period ends.
  • After the grace period, the gateway refuses to start.

To renew, replace the JWT in the file. Then restart the gateways one at a time.

Next steps​