1 of 6

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.

Nightly

The nightly build container can be found

Usage

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

Run the NATS server image:

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.

The default ports may be customized by providing either a -p or -P option on the docker run command line.

The following steps illustrate how to run a server with the ports exposed on a docker network.

First, create the docker network 'nats:'

Then start the server:

Creating a NATS Cluster

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

Next, start additional servers pointing them to the seed server to cause them to form a cluster:

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

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

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.

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

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.

Inside the container:

Stopping the seed node, which received the subscription, should trigger an automatic failover to the other nodes:

Output extract:

Publishing again will continue to work after the reconnection:

Tutorial

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

Tutorial

In this tutorial you run the . The Docker image provides an instance of the NATS Server. Synadia actively maintains and supports the nats-server Docker image. The NATS image is only 6 MB in size.

1. Set up Docker.

See for guidance.

The easiest way to run Docker is to use the .

2. Run the nats-server Docker image.

3. Verify that the NATS server is running.

You should see the following:

Followed by this, indicating that the NATS server is running:

Notice how quickly the NATS server Docker image downloads. It is a mere 6 MB in size.

Docker Swarm

Step 1:

Create an overlay network for the cluster (in this example, nats-cluster-example), and instantiate an initial NATS server.

First create an overlay network:

docker network create --driver overlay nats-cluster-example

Next instantiate an initial "seed" server for a NATS cluster listening for other servers to join route to it on port 6222:

Step 2:

The 2nd step is to create another service which connects to the NATS server within the overlay network. Note that we connect to to the server at nats-cluster-node-1:

Step 3:

Now you can add more nodes to the Swarm cluster via more docker services, referencing the seed server in the -routes parameter:

In this case, nats-cluster-node-1 is seeding the rest of the cluster through the autodiscovery feature. Now NATS servers nats-cluster-node-1 and nats-cluster-node-2 are clustered together.

Add in more replicas of the subscriber:

Then confirm the distribution on the Docker Swarm cluster:

The sample output after adding more NATS server nodes to the cluster, is below - and notice that the client is dynamically aware of more nodes being part of the cluster via auto discovery!

Sample output after adding more workers which can reply back (since ignoring own responses):

And so forth...

From here you can experiment adding to the NATS cluster by simply adding servers with new service names, that route to the seed server nats-cluster-node-1. As you've seen above, clients will automatically be updated to know that new servers are available in the cluster.

Python and NGS Running in Docker

Start a lightweight Docker container:

Or you can also mount local creds via a volume:

Install nats.py and dependencies to install nkeys:

Get the Python examples using curl:

Create a subscription that lingers:

Publish a message:

JetStream

This mini-tutorial shows how to run a NATS server with JetStream enabled in a local Docker container. This enables quick and consequence-free experimentation with the many features of JetStream.

Using the official nats image, start a server. The -js option is passed to the server to enable JetStream. The -p option forwards your local 4222 port to the server inside the container, 4222 is the default client connection port.

docker run -p 4222:4222 nats -js

To persist JetStream data to a volume, you can use the -v option in combination with -sd:

docker run -p 4222:4222 -v nats:/data nats -js -sd /data

With the server running, use nats bench to create a stream and publish some messages to it.

JetStream persists the messages (on disk by default). Now consume them with:

You can use nats to inspect various aspects of the stream, for example:

Official and
and

NGS Leaf Nodes

This mini-tutorial shows how to run 2 NATS server in local Docker containers interconnected via Synadia Cloud Platform. NGS is a global managed NATS network of NATS, and the local containers will connect to it as leaf nodes.

Start by creating a free account on https://cloud.synadia.com/.

Once you are logged in, go into the default account (you can manage multiple isolated NGS account within your Synadia Cloud account).

In Settings > Limits, increase Leaf Nodes to 2. Save the configuration change. (Your free account comes with up to 2 leaf connection, but the account is configured to use at most 1 initially).

Now navigate to the Users section of your default account and create 2 users, red and blue. (Users are another way you can isolate parts of your systems customizing permissions, access to data, limits and more)

For each of the two users, select Get Connected and Download Credentials.

You should now have 2 files on your computer: default-red.creds and default-blue.creds.

Create a minimal NATS Server configuration file leafnode.conf, it will work for both leaf nodes:

Let's start the first leafnode (for user red) with:

-p 4222:4222 maps the server port 4222 inside the container to your local port 4222. -v leafnode.conf:/leafnode.conf mounts the configuration file created above at location /leafnode.conf in the container. -v /etc/ssl/cert.pem:/etc/ssl/cert.pem installs root certificates in the container, since the nats image does not bundle them, and they are required to verify the TLS certificate presented by NGS. -v default-red.creds:/ngs.creds installs the credentials for user red at location /ngs.creds inside the container. -c /leafnode.conf are arguments passed to the container entry point (nats-server).

Launching the container, you should see the NATS server starting successfully:

Now start the second leaf nodes with two minor tweaks to the command:

Notice we bind to local port 4333 (since 4222) is busy, and we mount blue credentials.

Congratulations, you have 2 leaf nodes connected to the NGS global network. Despite this being a global shared environment, your account is completely isolated from the rest of the traffic, and vice versa.

Now let's make 2 clients connected to the 2 leaf nodes talk to each other.

Let us start a simple service on the Leafnode of user red:

Using the LeafNode run by user blue, let's send a request:

Congratulations, you just connected 2 Leaf nodes to the global NGS network and used them to send a request and receive a response.

Your messages were routed transparently with millions of others, but they were not visible to anyone outside of your Synadia Cloud account.

Official and
and