# Install

This guide installs the `mq-gateway` binary or runs the container image. Synadia distributes both. To get access, [contact Synadia](https://www.synadia.com/contact) or [start a trial](/mq-gateway/0.4/trial.md).

Before you start, you need:

* The download or registry credentials that Synadia gave you. A [licensed build](#run-a-licensed-build) needs none.
* 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](/mq-gateway/0.4/tutorials/playground.md).

## 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.4.0/mq-gateway-v0.4.0-linux-amd64.tar.gz

curl -fLO -u <user>:<password> \

  https://artifacts.synadia.io/mq-gateway/v0.4.0/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.4.0-windows-amd64.zip).Hash.ToLower()
```

## 3. Run the binary

```
tar -xzf mq-gateway-v0.4.0-linux-amd64.tar.gz

cd mq-gateway-v0.4.0-linux-amd64

./mq-gateway --version

sudo install mq-gateway /usr/local/bin/
```

`--version` prints `0.4.0`. 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](/mq-gateway/0.4/reference/admin-subjects.md).

## Run the container image

The images are on `registry.synadia.io`, for `linux/amd64` and `linux/arm64`. To run them on Kubernetes, see [Deploy on Kubernetes](/mq-gateway/0.4/how-to/deploy-on-kubernetes.md). Log in with your registry credentials:

```
docker login registry.synadia.io

docker run --rm registry.synadia.io/mq-gateway:0.4.0 --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.4.0 \

  --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`.
* The license, a JWT.

The archives and the image `registry.synadia.io/mq-gateway-licensed` need no credentials. Install the licensed build with the steps above, with these changes:

* Download the archive from its link in the email, without `-u`. `checksums.txt` is at the same path as the archive.
* Pull the image without `docker login`.

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 `MQG_LICENSE_FILE`. To give the JWT itself, use `--license.token`, `MQG_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.4.0 \

  --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 checked" 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:

| Message                                              | Fix                                        |
| ---------------------------------------------------- | ------------------------------------------ |
| `this build needs a license`                         | Set `license.file` or `license.token`.     |
| `invalid license: ...`                               | Use the JWT from Synadia, with no changes. |
| `license does not entitle MQ Gateway`                | Ask 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](/mq-gateway/0.4/how-to/change-the-config.md).

## Next steps

* [Playground](/mq-gateway/0.4/tutorials/playground.md): a first run, with no NATS server of your own.
* [Provision the streams and buckets](/mq-gateway/0.4/how-to/provision-streams-and-buckets.md) that your config file names.
* [Deploy on Kubernetes](/mq-gateway/0.4/how-to/deploy-on-kubernetes.md) with the Helm chart.
