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:

  1. docker pull nats

Run the NATS server image:

  1. 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:

  1. $ docker network create nats
  1. docker run --name nats --network nats --rm -p 4222:4222 -p 8222:8222 nats
  2. [INF] Starting nats-server version 2.1.0
  3. [INF] Git commit [1cc5ae0]
  4. [INF] Starting http monitor on 0.0.0.0:8222
  5. [INF] Listening for client connections on 0.0.0.0:4222
  6. [INF] Server id is NDHWPPFNP2ASLPHXTMUU63NKUTZIKPJPMVBAHBAWJVAOSJG4QPXVRWL3
  7. [INF] Server is ready
  8. [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:

  1. docker run --name nats-1 --network nats --rm nats --cluster nats://0.0.0.0:6222 --routes=nats://ruser:T0pS3cr3t@nats:6222
  2. 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:

  1. curl http://127.0.0.1:8222/routez
  2. {
  3.   "server_id": "ND34PZ64QLLJKSU5SLSWRS5EUXEKNHW5BUVLCNFWA56R4D7XKDYWJFP7",
  4.   "now": "2019-10-17T21:29:38.126871819Z",
  5.   "num_routes": 2,
  6.   "routes": [
  7.     {
  8.       "rid": 7,
  9.       "remote_id": "NDF4PMDKSKIZBYHUU5R7NA5KXNXLTKHVLN6ALBLQPAWTJKRAWJVPN4HA",
  10.       "did_solicit": false,
  11.       "is_configured": false,
  12.       "ip": "172.17.0.3",
  13.       "port": 59810,
  14.       "pending_size": 0,
  15.       "rtt": "561µs",
  16.       "in_msgs": 0,
  17.       "out_msgs": 0,
  18.       "in_bytes": 0,
  19.       "out_bytes": 0,
  20.       "subscriptions": 0
  21.     },
  22.     {
  23.       "rid": 8,
  24.       "remote_id": "ND6P52R5PASBYXK2MK44P6BYV7Q7PZEMTZJ5O5K7WXF4F54UD3EKVBSC",
  25.       "did_solicit": false,
  26.       "is_configured": false,
  27.       "ip": "172.17.0.4",
  28.       "port": 37882,
  29.       "pending_size": 0,
  30.       "rtt": "772µs",
  31.       "in_msgs": 0,
  32.       "out_msgs": 0,
  33.       "in_bytes": 0,
  34.       "out_bytes": 0,
  35.       "subscriptions": 0
  36.     }
  37.   ]
  38. }

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.

  1. version: "3.5"
  2. services:
  3.   nats:
  4.     image: nats
  5.     ports:
  6.       - "8222:8222"
  7.     networks: ["nats"]
  8.   nats-1:
  9.     image: nats
  10.     command: "--cluster nats://0.0.0.0:6222 --routes=nats://ruser:T0pS3cr3t@nats:6222"
  11.     networks: ["nats"]
  12.     depends_on: ["nats"]
  13.   nats-2:
  14.     image: nats
  15.     command: "--cluster nats://0.0.0.0:6222 --routes=nats://ruser:T0pS3cr3t@nats:6222"
  16.     networks: ["nats"]
  17.     depends_on: ["nats"]
  19. networks:
  20.   nats:
  21.     name: nats

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

  1. $ docker-compose -f nats-cluster.yaml up
  2. Recreating docs_nats_1   ... done
  3. Recreating docs_nats-2_1 ... done
  4. Recreating docs_nats-1_1 ... done
  5. Attaching to docs_nats-2_1, docs_nats_1, docs_nats-1_1
  6. nats-2_1  | [1] 2019/10/19 06:41:26.064501 [INF] Starting nats-server version 2.1.0
  7. nats-2_1  | [1] 2019/10/19 06:41:26.064783 [INF] Git commit [1cc5ae0]
  8. nats_1    | [1] 2019/10/19 06:41:26.359150 [INF] Starting nats-server version 2.1.0
  9. nats_1    | [1] 2019/10/19 06:41:26.359365 [INF] Git commit [1cc5ae0]
  10. nats_1    | [1] 2019/10/19 06:41:26.360540 [INF] Starting http monitor on 0.0.0.0:8222
  11. nats-1_1  | [1] 2019/10/19 06:41:26.578773 [INF] 172.18.0.2:6222 - rid:1 - Route connection created
  12. nats_1    | [1] 2019/10/19 06:41:27.138198 [INF] 172.18.0.4:38900 - rid:2 - Route connection created
  13. nats-2_1  | [1] 2019/10/19 06:41:27.147816 [INF] 172.18.0.2:6222 - rid:1 - Route connection created
  14. nats-2_1  | [1] 2019/10/19 06:41:27.150367 [INF] 172.18.0.3:60702 - rid:2 - Route connection created
  15. 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.

  1. $ docker run --network nats --rm -it synadia/nats-box
  2. ~ # nats-sub -s nats://nats:4222 hello &
  3. Listening on [hello]
  5. ~ # nats-pub -s "nats://nats-1:4222" hello first
  6. ~ # 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:

  1. $ docker stop nats
  3. ... 
  4. Disconnected: will attempt reconnects for 10m
  5. Reconnected [nats://172.17.0.4:4222]

Publishing again will continue to work after the reconnection:

  1. ~ # nats-pub -s "nats://nats-1:4222" hello again
  2. ~ # 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.