Skip to main content

1. Hello NATS

In this tutorial you install NATS, start a server, and send your first message. You'll subscribe to a subject in one terminal, publish a message to it from another, and watch it arrive. By the end you'll have a working NATS server on your machine, and you'll have moved a message through it from both the CLI and a client.

What you'll need​

  • a terminal you can open two or three tabs in
  • permission to install software (Homebrew, a download, or Docker)
  • about ten minutes

Step 1: Install the NATS server and CLI​

Install nats-server (the server) and nats (the command-line client).

brew install nats-server
brew install nats-io/nats-tools/nats

Check that the CLI is installed:

nats --version

You should see a version number, for example nats version 0.4.0. If you installed the server directly (Homebrew or the Linux script, not Docker), check it too — you should see something like nats-server: v2.11.0:

nats-server --version

Step 2: Start the server​

If you started the server with Docker in Step 1, it's already running — leave that terminal alone and skip to Step 3.

Otherwise, in your first terminal, start the server:

nats-server

You should see startup lines ending with:

[INF] Server is ready

The server now listens on localhost:4222. Leave this terminal running for the rest of the tutorial.

Step 3: Subscribe to a subject​

Open a second terminal. A subscriber registers interest in a subject and receives a copy of every matching message. Subscribe to the greet subject:

#!/bin/bash
# Subscribe to the greet subject and wait for messages.
# Each matching message prints as it arrives. Ctrl-C to stop.
nats sub greet

You should see the subscriber start and wait:

17:42:01 Subscribing on greet

Leave this terminal running and listening.

Step 4: Publish a message​

Open a third terminal. A publisher sends a message to a subject. Publish Hello NATS! to greet:

#!/bin/bash
# Publish one message to the greet subject. The publish is
# fire-and-forget: it hands the message to the server and exits.
nats pub greet "Hello NATS!"

In this third terminal you should see the publish confirmed:

17:42:09 Published 11 bytes to "greet"

Now switch back to your second terminal. The subscriber received the message and printed it:

[#1] Received on "greet"
Hello NATS!

That's one message making the round trip: published to a subject, matched against the subscriber's interest, and delivered.

Step 5: See the flow​

Here's an animation of the publish-to-subscriber path you just ran:

Publish a few more times from the third terminal and watch the counter in the second terminal climb: [#2], [#3], and so on. Each publish delivers a fresh copy to every active subscriber on the subject.

What you built​

You have a running NATS server, and you've sent your first message through it: one terminal subscribed to the greet subject, another published to it, and the message arrived. The same pub/sub works from any NATS client, which is what the code tabs above show.

Next​