NATS and Docker

NATS Server Containerization

The NATS server is provided as a Docker image on Docker Hub that you can run using the Docker daemon. The NATS server Docker image is extremely lightweight, coming in under 10 MB in size.

Synadia actively maintains and supports the NATS server Docker image.

Usage

To use the Docker container image, install Docker and pull the public image:

docker pull nats

Run the NATS server image:

docker run nats

By default the NATS server exposes multiple ports:

• 4222 is for clients.

• 8222 is an HTTP management port for information reporting.

• 6222 is a routing port for clustering.

• Use -p or -P to customize.

Creating a NATS Cluster

First run a server with the ports exposed on a docker network:

$ docker network create nats

docker run --name nats --network nats --rm -p 4222:4222 -p 8222:8222 nats
[INF] Starting nats-server version 2.1.0
[INF] Git commit [1cc5ae0]
[INF] Starting http monitor on 0.0.0.0:8222
[INF] Listening for client connections on 0.0.0.0:4222
[INF] Server id is NDHWPPFNP2ASLPHXTMUU63NKUTZIKPJPMVBAHBAWJVAOSJG4QPXVRWL3
[INF] Server is ready
[INF] Listening for route connections on 0.0.0.0:6222

Next, start another couple of servers and point them to the seed server to make them form a cluster:

docker run --name nats-1 --network nats --rm nats --cluster nats://0.0.0.0:6222 --routes=nats://ruser:T0pS3cr3t@nats:6222
docker run --name nats-2 --network nats --rm nats --cluster nats://0.0.0.0:6222 --routes=nats://ruser:T0pS3cr3t@nats:6222

NOTE Since the Docker image protects routes using credentials we need to provide them above. Extracted from Docker image configuration

To verify the routes are connected, you can make a request to the monitoring endpoint on /routez as follows and confirm that there are now 2 routes:

curl http://127.0.0.1:8222/routez
{
  "server_id": "ND34PZ64QLLJKSU5SLSWRS5EUXEKNHW5BUVLCNFWA56R4D7XKDYWJFP7",
  "now": "2019-10-17T21:29:38.126871819Z",
  "num_routes": 2,
  "routes": [
    {
      "rid": 7,
      "remote_id": "NDF4PMDKSKIZBYHUU5R7NA5KXNXLTKHVLN6ALBLQPAWTJKRAWJVPN4HA",
      "did_solicit": false,
      "is_configured": false,
      "ip": "172.17.0.3",
      "port": 59810,
      "pending_size": 0,
      "rtt": "561µs",
      "in_msgs": 0,
      "out_msgs": 0,
      "in_bytes": 0,
      "out_bytes": 0,
      "subscriptions": 0
    },
    {
      "rid": 8,
      "remote_id": "ND6P52R5PASBYXK2MK44P6BYV7Q7PZEMTZJ5O5K7WXF4F54UD3EKVBSC",
      "did_solicit": false,
      "is_configured": false,
      "ip": "172.17.0.4",
      "port": 37882,
      "pending_size": 0,
      "rtt": "772µs",
      "in_msgs": 0,
      "out_msgs": 0,
      "in_bytes": 0,
      "out_bytes": 0,
      "subscriptions": 0
    }
  ]
}

Creating a NATS Cluster with Docker Compose

It is also straightforward to create a cluster using Docker Compose. Below is a simple example that uses a network named nats to create a full mesh cluster.

version: "3.5"
services:
  nats:
    image: nats
    ports:
      - "8222:8222"
    networks: ["nats"]
  nats-1:
    image: nats
    command: "--cluster nats://0.0.0.0:6222 --routes=nats://ruser:T0pS3cr3t@nats:6222"
    networks: ["nats"]
    depends_on: ["nats"]
  nats-2:
    image: nats
    command: "--cluster nats://0.0.0.0:6222 --routes=nats://ruser:T0pS3cr3t@nats:6222"
    networks: ["nats"]
    depends_on: ["nats"]

networks:
  nats:
    name: nats

Now we use Docker Compose to create the cluster that will be using the nats network:

$ docker-compose -f nats-cluster.yaml up
Recreating docs_nats_1   ... done
Recreating docs_nats-2_1 ... done
Recreating docs_nats-1_1 ... done
Attaching to docs_nats-2_1, docs_nats_1, docs_nats-1_1
nats-2_1  | [1] 2019/10/19 06:41:26.064501 [INF] Starting nats-server version 2.1.0
nats-2_1  | [1] 2019/10/19 06:41:26.064783 [INF] Git commit [1cc5ae0]
nats_1    | [1] 2019/10/19 06:41:26.359150 [INF] Starting nats-server version 2.1.0
nats_1    | [1] 2019/10/19 06:41:26.359365 [INF] Git commit [1cc5ae0]
nats_1    | [1] 2019/10/19 06:41:26.360540 [INF] Starting http monitor on 0.0.0.0:8222
nats-1_1  | [1] 2019/10/19 06:41:26.578773 [INF] 172.18.0.2:6222 - rid:1 - Route connection created
nats_1    | [1] 2019/10/19 06:41:27.138198 [INF] 172.18.0.4:38900 - rid:2 - Route connection created
nats-2_1  | [1] 2019/10/19 06:41:27.147816 [INF] 172.18.0.2:6222 - rid:1 - Route connection created
nats-2_1  | [1] 2019/10/19 06:41:27.150367 [INF] 172.18.0.3:60702 - rid:2 - Route connection created
nats-1_1  | [1] 2019/10/19 06:41:27.153078 [INF] 172.18.0.4:6222 - rid:3 - Route connection created

Testing the Clusters

Now, the following should work: make a subscription on one of the nodes and publish it from another node. You should be able to receive the message without problems.

$ docker run --network nats --rm -it synadia/nats-box
~ # nats-sub -s nats://nats:4222 hello &
Listening on [hello]

~ # nats-pub -s "nats://nats-1:4222" hello first
~ # nats-pub -s "nats://nats-2:4222" hello second

Also stopping the seed node to which the subscription was done, should trigger an automatic failover to the other nodes:

$ docker stop nats

... 
Disconnected: will attempt reconnects for 10m
Reconnected [nats://172.17.0.4:4222]

Publishing again will continue to work after the reconnection:

~ # nats-pub -s "nats://nats-1:4222" hello again
~ # nats-pub -s "nats://nats-2:4222" hello again

Tutorial

See the NATS Docker tutorial for more instructions on using the NATS server Docker image.