NATS Installation, Configuration, and Usage Guide

NATS is a simple, fast, and lightweight message broker written in the Go programming language.

NATS has several data organization features:

• Key-Value: Data within NATS is stored in "key-value" format, where each key corresponds to a specific value.
• Subjects: Data within NATS is organized into so-called "Subjects," which are named channels for message transmission. Subjects can be divided into segments with hierarchical structures.
• Publish/Subscribe (Pub/Sub): Data within NATS is transmitted through a model where "Publishers" send messages to "Subjects," and "Subscribers" can subscribe to these "Subjects" to receive messages.

Unlike many other message brokers (such as Apache Kafka or RabbitMQ), NATS has several significant advantages:

• Simplicity and Performance: Messages are transmitted through a simple and fast Pub/Sub protocol. When a message is sent to a subject, all subscribers immediately receive it. This minimizes delays and other overhead costs.
• Stateless: Information about the state of messages transmitted through the broker is not stored within it, nor is data about subject subscribers. The absence of complex state synchronization allows NATS to scale easily.
• No Default Queues: In standard configuration, NATS does not form message queues. This is important in cases where data timeliness is more important than persistence. It also eliminates queue management overhead.
• Reliable Protocol: Messages within the broker are transmitted using the "at-most-once delivery" method. This means a subscriber either receives a message once or not at all. This increases communication reliability and prevents duplicate responses to forwarded messages.

Thus, NATS enables building fast and reliable communication between multiple different services.

In this guide, we will thoroughly examine how to install, configure, and correctly use NATS in projects running on Ubuntu 22.04.

Downloading NATS

Package Updates

Before installation, it's recommended to update the list of available repositories in the system:

sudo apt update

Downloading the Archive

Next, you need to manually download the ZIP archive with NATS from its official GitHub repository:

wget https://github.com/nats-io/nats-server/releases/download/v2.10.22/nats-server-v2.10.22-linux-amd64.zip

After the download is complete, you can check the file list:

ls

Among them will be the NATS archive:

nats-server-v2.10.22-linux-amd64.zip  resize.log  snap

Extracting the Archive

Next, install the package that performs ZIP archive extraction:

sudo apt install unzip -y

The -y flag is added so that the installer automatically answers 'yes' to all questions.

Now extract the NATS archive using the installed extractor:

unzip nats-server-v2.10.22-linux-amd64.zip

Check the file list:

ls

As you can see, a new folder with the archive contents has appeared:

nats-server-v2.10.22-linux-amd64  nats-server-v2.10.22-linux-amd64.zip  resize.log  snap

We no longer need the archive, so delete it:

rm nats-server-v2.10.22-linux-amd64.zip

Installing NATS

Server Installation

Let's look at the contents of the created folder:

ls nats-server-v2.10.22-linux-amd64

Inside it is the main directory with the NATS server:

LICENSE  nats-server  README.md

This is what we need to copy to the system catalog with binary files:

sudo mv nats-server-v2.10.22-linux-amd64/nats-server /usr/local/bin/

After copying, you need to set the appropriate access permissions:

sudo chmod +x /usr/local/bin/nats-server

The folder with NATS contents, like the archive, can now also be deleted:

rm nats-server-v2.10.22-linux-amd64 -R

Server Verification

Let's verify that the NATS server is installed by requesting its version:

nats-server -v

A similar output should appear in the console terminal:

nats-server: v2.10.22

However, this command doesn't start the server; it only returns its version.

You can start the server as follows:

nats-server

[3704] 2024/11/07 02:59:53.908362 [INF] Starting nats-server
[3704] 2024/11/07 02:59:53.908623 [INF]   Version:  2.10.22
[3704] 2024/11/07 02:59:53.908669 [INF]   Git:      [240e9a4]
[3704] 2024/11/07 02:59:53.908701 [INF]   Name:     NC253DIPURNIY4HUXYQYC5LLAFA6UZEBKUIWTBLLPSMICFH3E2FMSXB7
[3704] 2024/11/07 02:59:53.908725 [INF]   ID:       NC253DIPURNIY4HUXYQYC5LLAFA6UZEBKUIWTBLLPSMICFH3E2FMSXB7
[3704] 2024/11/07 02:59:53.909430 [INF] Listening for client connections on 0.0.0.0:4222
[3704] 2024/11/07 02:59:53.909679 [INF] Server is ready

In this case, the server starts with binding to the console terminal, not as a background service. Therefore, to return to command input mode, you need to press Ctrl + C.

NATS Configuration

Creating a Configuration File

After the broker server is started, you can create a separate directory for the NATS configuration file:

mkdir /etc/nats

And then create the configuration file itself:

sudo nano /etc/nats/nats-server.conf

Its contents will be as follows:

cluster {
	name: "test-nats"
}

store_dir: "/var/lib/nats"
listen: "0.0.0.0:4222"

Specifically in this configuration, the most basic parameters are set:

• name: Server name within the NATS cluster
• store_dir: Path to the directory where working data will be stored
• listen: IP address and port that the NATS server will occupy

Creating a Separate User

For all directories related to NATS, you need to create a separate user:

useradd -r -c 'NATS service' nats

Now create the directories specified in the configuration file:

mkdir /var/log/nats /var/lib/nats

For each directory, assign appropriate access permissions to the previously created user:

chown nats:nats /var/log/nats /var/lib/nats

Creating a Background Service

Earlier we started the NATS server with binding to the console terminal. In this case, when exiting the console, the server will stop working.

To prevent this, you need to create a file for the systemd service:

sudo nano /etc/systemd/system/nats-server.service

Its contents will be:

[Unit]
Description=NATS message broker server
After=syslog.target network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nats-server -c /etc/nats/nats-server.conf
User=nats
Group=nats
LimitNOFILE=65536
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure

[Install]
WantedBy=multi-user.target

This file contains several key parameters:

• Description: Short description of the service
• ExecStart: NATS server startup command with the configuration file explicitly specified
• User: Name of the user created for NATS

Now we need to set up the service to start up at boot: 

systemctl enable nats-server --now

The --now flag immediately starts the specified service.

The corresponding message will appear in the console:

Created symlink /etc/systemd/system/multi-user.target.wants/nats-server.service → /etc/systemd/system/nats-server.service.

Now check the status of the running service:

systemctl status nats-server

If the NATS server service started successfully, the corresponding message will be among the console output:

...
 Active: active (running)
...

Connecting to NATS

You can connect to the NATS server through the console terminal and thus perform message broker testing. For example, publish messages or subscribe to subjects.

Client Installation

To manage the NATS server, you need to install the natscli client. You can download it from the official GitHub repository:

wget https://github.com/nats-io/natscli/releases/download/v0.1.5/nats-0.1.5-amd64.deb

After this, the downloaded archive can be extracted and installed:

dpkg -i nats-0.1.5-amd64.deb

The archive itself can be deleted as it's no longer needed:

rm nats-0.1.5-amd64.deb

Sending Messages

Now you can send a message to the message broker:

nats pub -s 127.0.0.1 "someSubject" "Some message"

In this command, we send the message "Some message" to the subject "someSubject" to the message broker running on IP address 127.0.0.1 and located on the standard NATS port - 4222.

After this, information about the sent data will appear in the console terminal:

10:59:51 Published 12 bytes to "someSubject"

Reading Messages

Currently, no one will see this message since there's no agent subscribed to the specified subject.

We can simulate a service subscribed to the subject and reading messages using another SSH session.

To do this, you need to open another console terminal, connect to the remote machine, and subscribe to the previously specified subject:

nats sub -s 127.0.0.1 "someSubject"

A message about successful subscription will appear in the terminal:

11:11:10 Subscribing on someSubject

Now repeat sending the message from the first terminal:

nats pub -s 127.0.0.1 "someSubject" "Some message"

Information about the new message will appear in the second terminal:

[#1] Received on "someSubject"
Some message

Let's send another message from the first terminal:

nats pub -s 127.0.0.1 "someSubject" "Some message again"

The corresponding notification will appear in the second terminal:

[#2] Received on "someSubject"
Some message again

Note that the console output of received messages has numbering in square brackets.

Go Program + NATS

Let's create a small program in the Golang programming language using the NATS message broker.

Installing Go

First, you need to ensure that the Go compiler is installed in the system:

go version

If the following message appears in the console terminal, then Go is not yet installed:

Command 'go' not found, but can be installed with:
snap install go         # version 1.23.2, or
apt  install golang-go  # version 2:1.18~0ubuntu2
apt  install gccgo-go   # version 2:1.18~0ubuntu2
See 'snap info go' for additional versions.

In this case, you need to download it as an archive from the official website:

wget https://go.dev/dl/go1.23.3.linux-amd64.tar.gz -O go.tar.gz

And then extracted:

sudo tar -xzvf go.tar.gz -C /usr/local

As we no longer need the downloaded archive, we can delete it:

rm go.tar.gz

Next, you need to add the Go compiler to the PATH variable so it can be called from the console terminal:

echo export PATH=$HOME/go/bin:/usr/local/go/bin:$PATH >> ~/.profile

Then apply the changes:

source ~/.profile

Verify that Go is installed successfully by requesting its version:

go version

You will see a similar output:

go version go1.23.3 linux/amd64

Creating a Project

Let's create a separate folder for the Golang program:

mkdir nats_go

Then navigate to it:

cd nats_go

And initialize the Go project:

go mod init nats_go

Installing the Module

After project initialization, you need to install the NATS client from the official GitHub repository. You don't need to download anything manually; it's enough to use the built-in Golang function:

go get github.com/nats-io/nats.go/

Writing Code

Now you can create a file with the program code:

nano nats_go.go

Its contents will be:

package main

import (
	"fmt" // module for working with console
	"os" // module for working with system functions
	"time" // module for working with time

	"github.com/nats-io/nats.go" // module for working with NATS server
)

func main() {
	// get NATS server address from environment variable
	url := os.Getenv("NATS_URL")

	// if there's no address in environment variable, use default address
	if url == "" {
		url = nats.DefaultURL
	}

	// connect to NATS server
	nc, _ := nats.Connect(url)

	// defer message broker cleanup until main() function completion
	defer nc.Drain()

	// send message to subject without subscribers to ensure it disappears
	nc.Publish("people.philosophers", []byte("Hello, Socrates!"))

	// subscribe to all sub-subjects in "people" subject
	sub, _ := nc.SubscribeSync("people.*")

	// extract message
	msg, _ := sub.NextMsg(10 * time.Millisecond)

	// output message status (it's not there because it was sent before subscribing to subjects)
	fmt.Printf("No message? Answer: %v\n", msg == nil)

	// send message to "philosophers" sub-subject of "people" subject
	nc.Publish("people.philosophers", []byte("Hello, Socrates!"))

	// send message to "physicists" sub-subject of "people" subject
	nc.Publish("people.physicists", []byte("Hello, Feynman!"))

	// extract message and output to console
	msg, _ = sub.NextMsg(10 * time.Millisecond)
	fmt.Printf("Message: %q in subject %q\n", string(msg.Data), msg.Subject)

	// extract message and output to console
	msg, _ = sub.NextMsg(10 * time.Millisecond)
	fmt.Printf("Message: %q in subject %q\n", string(msg.Data), msg.Subject)

	// send message to "biologists" sub-subject of "people" subject
	nc.Publish("people.biologists", []byte("Hello, Darwin!"))

	// extract message and output to console
	msg, _ = sub.NextMsg(10 * time.Millisecond)
	fmt.Printf("Message: %q in subject %q\n", string(msg.Data), msg.Subject)
}

Now you can run the created program:

go run .

The program's output will appear in the console terminal:

No message? Answer: true
Message: "Hello, Socrates!" in subject "people.philosophers"
Message: "Hello, Feynman!" in subject "people.physicists"
Message: "Hello, Darwin!" in subject "people.biologists"

Python Program + NATS

As another example, let's consider using the NATS message broker in the Python programming language.

First, you need to ensure that the Python interpreter is installed in the system by requesting its version:

python --version

The corresponding message will appear in the console:

Python 3.10.12

Note that this guide uses Python version 3.10.12.

Installing PIP

To download the NATS client for Python, you first need to install the PIP package manager:

apt install python3-pip -y

The -y flag helps automatically answer positively to all questions during installation.

Installing the Client

Now you can install the NATS client for Python:

pip install nats-py

Creating a Project

For the Python program, let's create a separate directory:

mkdir nats_python

And navigate to it:

cd nats_python

Writing Code

Let's create a file with the program code:

nano nats_python.py

Its contents will be:

import os
import asyncio

# import NATS client
import nats
from nats.errors import TimeoutError

# get environment variable containing NATS server address
servers = os.environ.get("NATS_URL", "nats://localhost:4222").split(",")

async def main():
	# connect to NATS server
	nc = await nats.connect(servers=servers)

	# send message to subject without subscribers to ensure it disappears
	await nc.publish("people.philosophers", "Hello, Socrates!".encode())

	# subscribe to all sub-subjects in "people" subject
	sub = await nc.subscribe("people.*")

	try:
		# extract message
		msg = await sub.next_msg(timeout=0.1)
	except TimeoutError:
		pass

	# send message to "philosophers" sub-subject of "people" subject
	await nc.publish("people.philosophers", "Hello, Socrates!".encode())

	# send message to "physicists" sub-subject of "people" subject
	await nc.publish("people.physicists", "Hello, Feynman!".encode())

	# extract message and output to console
	msg = await sub.next_msg(timeout=0.1)
	print(f"{msg.data.decode('utf-8')} in subject {msg.subject}")

	# extract message and output to console
	msg = await sub.next_msg(timeout=0.1)
	print(f"{msg.data.decode('utf-8')} in subject {msg.subject}")

	# send message to "biologists" sub-subject of "people" subject
	await nc.publish("people.biologists", "Hello, Darwin!".encode())

	# extract message and output to console
	msg = await sub.next_msg(timeout=0.1)
	print(f"{msg.data.decode('utf-8')} in subject {msg.subject}")

	# unsubscribe from subjects
	await sub.unsubscribe()

	# clean up message broker
	await nc.drain()

if __name__ == '__main__':
	asyncio.run(main())

Now you can run the created script:

python nats_python.py

The result of its operation will be the following output in the console terminal:

Hello, Socrates! in subject people.philosophers
Hello, Feynman! in subject people.physicists
Hello, Darwin! in subject people.biologists

As you can notice, the logic of this Python program doesn't differ from the logic of the Go program. The difference is only in the syntactic constructions of the specific programming language.

Conclusion

This guide examined the use of the NATS message broker in sequential stages:

1. Downloading and installing NATS from the official GitHub repository
2. Minimal NATS server configuration
3. Managing the NATS server through the console terminal client
4. Using NATS in a Golang program
5. Using NATS in a Python program

We downloaded all NATS clients used in this guide (for terminal, Go, and Python) from the official NATS repository on GitHub, which hosts modules and libraries for all programming languages supported by NATS.

You can find more detailed information about configuring and using NATS in the official documentation. There are also many examples of using NATS in different programming languages.