How to Deploy NATS – High-Performance Messaging

3 min readUpdated 17 December 2025

NATS is a lightweight, high-performance messaging system designed for distributed and cloud-native applications. It supports publish-subscribe, request-reply, and streaming workloads through JetStream. NATS is widely used for microservices communication, event-driven systems, IoT messaging, and real-time data pipelines.

This article explains how to deploy NATS using Docker Compose, enable JetStream persistence, configure authentication and authorization, and verify client connectivity using the NATS CLI.

Prerequisites

Before you begin, you need to:

Have access to an Ubuntu 24.04-based server as a non-root user with sudo privileges.
Install Docker and Docker Compose.

Set Up the Directory Structure and Environment Variables

In this section, you create the required directory structure for NATS and define environment variables in a .env file that Docker Compose loads automatically.

Create the project directory.
CONSOLE
$ mkdir -p ~/nats-stack/{data,config}
Powered by Vultr AgentBeta
Navigate into the project directory.
CONSOLE
$ cd ~/nats-stack
Powered by Vultr AgentBeta
Create and edit the .env file.
CONSOLE
$ nano .env
Powered by Vultr AgentBeta
Add the following variables:
INI
NATS_CLIENT_PORT=4222 NATS_CLUSTER_PORT=6222
Powered by Vultr AgentBeta
Replace:
- NATS_CLIENT_PORT with the client connection port.
- NATS_CLUSTER_PORT with the cluster communication port.
Save and close the file.

Install NATS CLI and Create the NATS Configuration

In this section, you install the NATS CLI, generate secure credentials, and configure NATS with JetStream, authentication, and authorization.

Download the NATS CLI binary.
CONSOLE
$ curl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh
Powered by Vultr AgentBeta
Move the binary into your system PATH.
CONSOLE
$ sudo mv nats /usr/local/bin/
Powered by Vultr AgentBeta
Verify the installation.
CONSOLE
$ nats --version
Powered by Vultr AgentBeta
Generate a password hash for the system or application user.
CONSOLE
$ nats server passwd
Powered by Vultr AgentBeta
Enter the password twice and copy the generated hash.
Your output should be similar to the one below:
$2a$11$C6sj6xxxxx....
Repeat this step for each user you want to define.
Create the NATS configuration file.
CONSOLE
$ nano config/nats.conf
Powered by Vultr AgentBeta
Add the following configuration:
INI
# Client port port: 4222 monitor_port: 8222 server_name: "NATS_SERVER_NAME" # System account system_account: SYS accounts { SYS { users = [ { user: "sysadmin", password: "SYSTEM_PASSWORD_HASH" } ] } } # JetStream jetstream { store_dir: "/data/jetstream" max_mem_store: 1GB max_file_store: 5GB } authorization { default_permissions = { publish = "SANDBOX.*" subscribe = ["PUBLIC.>", "_INBOX.>"] } ADMIN = { publish = ">" subscribe = ">" } users = [ {user: USERNAME, password: "USER_PASSWORD_HASH", permissions: $ADMIN} ] }
Powered by Vultr AgentBeta
In the above configuration:
- server_name identifies the NATS server in logs, monitoring output, and system events.
- system_account enables internal system features required for monitoring and JetStream management.
- accounts defines authentication boundaries for system and application users.
- authorization enforces subject-level access control, with an admin permission set that grants full publish and subscribe access.
- JetStream enables message persistence with defined memory and disk limits.
Replace the following values before starting the service:
- NATS_SERVER_NAME with a descriptive server name.
- SYSTEM_PASSWORD_HASH with the bcrypt hash generated for the system user.
- USERNAME with your application user name.
- USER_PASSWORD_HASH with the bcrypt hash generated for the application user.
Save and close the file.

Deploy with Docker Compose

In this section, you create the Docker Compose manifest that deploys NATS with JetStream persistence and monitoring enabled.

Create the Docker Compose manifest.
CONSOLE
$ nano docker-compose.yaml
Powered by Vultr AgentBeta
Add the following content:
YAML
services: nats: image: nats:2.12 container_name: nats command: - "-c" - "/etc/nats/nats.conf" ports: - "${NATS_CLIENT_PORT}:4222" - "${NATS_CLUSTER_PORT}:6222" volumes: - "./data:/data" - "./config/nats.conf:/etc/nats/nats.conf:ro" restart: unless-stopped healthcheck: test: ["CMD", "nats", "server", "ping"] interval: 10s timeout: 5s retries: 5
Powered by Vultr AgentBeta
Save and close the file.
In this manifest:
- image: Uses the official NATS 2.12 image.
- command: Loads the custom NATS configuration at startup.
- ports:
  - 4222: Client connections.
  - 8222: Monitoring endpoint (localhost only).
  - 6222: Cluster communication.
- volumes:
  - ./data: Persists JetStream messages.
  - ./config/nats.conf: Injects the server configuration.
- healthcheck: Confirms the server responds to pings.
- restart: unless-stopped: Restarts the service automatically.
Start the NATS service.
CONSOLE
$ docker compose up -d
Powered by Vultr AgentBeta
Verify that the NATS service is running.
CONSOLE
$ docker compose ps
Powered by Vultr AgentBeta
Ensure that the output shows the NATS container is healthy and running.
View logs if needed.
CONSOLE
$ docker compose logs
Powered by Vultr AgentBeta
For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Verify NATS Connectivity

In this section, you verify that the NATS server is reachable and accepting client connections.

Test connectivity using the NATS CLI.

CONSOLE

$ nats --server nats://sysadmin:SYS_USER_PASSWORD@SERVER_IP:4222 server ping

Replace SYS_USER_PASSWORD and SERVER_IP with the system user password and server IP.

Output:

NATS_SERVER_NAME                                             rtt=338.443125ms

---- ping statistics ----
1 replies max: 338.00 min: 338.00 avg: 338.00

Successful output confirms that the NATS server is reachable and authenticated correctly.

Conclusion

You successfully deployed NATS using Docker Compose with JetStream persistence enabled. You configured secure authentication and authorization, enabled persistent message storage, exposed the required messaging and verified client connectivity using the NATS CLI.

Set Up the Directory Structure and Environment Variables

In this section, you create the required directory structure for NATS and define environment variables in a .env file that Docker Compose loads automatically.

Create the project directory.

CONSOLE

$ mkdir -p ~/nats-stack/{data,config}

Navigate into the project directory.

CONSOLE

$ cd ~/nats-stack

Create and edit the .env file.

CONSOLE

$ nano .env

Add the following variables:

INI
NATS_CLIENT_PORT=4222
NATS_CLUSTER_PORT=6222
Powered by Vultr AgentBeta

Replace:

NATS_CLIENT_PORT with the client connection port.
NATS_CLUSTER_PORT with the cluster communication port.

Save and close the file.

Install NATS CLI and Create the NATS Configuration

In this section, you install the NATS CLI, generate secure credentials, and configure NATS with JetStream, authentication, and authorization.

Download the NATS CLI binary.

CONSOLE

$ curl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh

Move the binary into your system PATH.

CONSOLE
$ sudo mv nats /usr/local/bin/
Powered by Vultr AgentBeta

Verify the installation.

CONSOLE

$ nats --version

Generate a password hash for the system or application user.

CONSOLE

$ nats server passwd

Enter the password twice and copy the generated hash.

Your output should be similar to the one below:

$2a$11$C6sj6xxxxx....

Repeat this step for each user you want to define.

Create the NATS configuration file.

CONSOLE

$ nano config/nats.conf

Add the following configuration:

INI
# Client port
port: 4222
monitor_port: 8222
server_name: "NATS_SERVER_NAME"

# System account
system_account: SYS

accounts {
  SYS {
    users = [
      { user: "sysadmin", password: "SYSTEM_PASSWORD_HASH" }
    ]
  }
}

# JetStream
jetstream {
  store_dir: "/data/jetstream"
  max_mem_store: 1GB
  max_file_store: 5GB
}

authorization {
  default_permissions = {
    publish = "SANDBOX.*"
    subscribe = ["PUBLIC.>", "_INBOX.>"]
  }
  ADMIN = {
    publish = ">"
    subscribe = ">"
  }
  users = [
    {user: USERNAME, password: "USER_PASSWORD_HASH", permissions: $ADMIN}
  ]
}
Powered by Vultr AgentBeta

In the above configuration:

server_name identifies the NATS server in logs, monitoring output, and system events.
system_account enables internal system features required for monitoring and JetStream management.
accounts defines authentication boundaries for system and application users.
authorization enforces subject-level access control, with an admin permission set that grants full publish and subscribe access.
JetStream enables message persistence with defined memory and disk limits.

Replace the following values before starting the service:

NATS_SERVER_NAME with a descriptive server name.
SYSTEM_PASSWORD_HASH with the bcrypt hash generated for the system user.
USERNAME with your application user name.
USER_PASSWORD_HASH with the bcrypt hash generated for the application user.

Save and close the file.

Deploy with Docker Compose

In this section, you create the Docker Compose manifest that deploys NATS with JetStream persistence and monitoring enabled.

Create the Docker Compose manifest.

CONSOLE

$ nano docker-compose.yaml

Add the following content:

YAML
services:
  nats:
    image: nats:2.12
    container_name: nats
    command:
      - "-c"
      - "/etc/nats/nats.conf"

    ports:
      - "${NATS_CLIENT_PORT}:4222"
      - "${NATS_CLUSTER_PORT}:6222"

    volumes:
      - "./data:/data"
      - "./config/nats.conf:/etc/nats/nats.conf:ro"

    restart: unless-stopped

    healthcheck:
      test: ["CMD", "nats", "server", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
Powered by Vultr AgentBeta

Save and close the file.

In this manifest:

image: Uses the official NATS 2.12 image.
command: Loads the custom NATS configuration at startup.
ports:
- 4222: Client connections.
- 8222: Monitoring endpoint (localhost only).
- 6222: Cluster communication.
volumes:
- ./data: Persists JetStream messages.
- ./config/nats.conf: Injects the server configuration.
healthcheck: Confirms the server responds to pings.
restart: unless-stopped: Restarts the service automatically.

Start the NATS service.

CONSOLE

$ docker compose up -d

Verify that the NATS service is running.

CONSOLE

$ docker compose ps

Ensure that the output shows the NATS container is healthy and running.

View logs if needed.

CONSOLE

$ docker compose logs

For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Verify NATS Connectivity

In this section, you verify that the NATS server is reachable and accepting client connections.

Test connectivity using the NATS CLI.

CONSOLE

$ nats --server nats://sysadmin:SYS_USER_PASSWORD@SERVER_IP:4222 server ping

Replace SYS_USER_PASSWORD and SERVER_IP with the system user password and server IP.

Output:

NATS_SERVER_NAME                                             rtt=338.443125ms

---- ping statistics ----
1 replies max: 338.00 min: 338.00 avg: 338.00

Successful output confirms that the NATS server is reachable and authenticated correctly.

How to Deploy NATS – High-Performance Messaging

Prerequisites

Set Up the Directory Structure and Environment Variables

Install NATS CLI and Create the NATS Configuration

Deploy with Docker Compose

Verify NATS Connectivity

Conclusion

About the Author

Aashish Chaurasiya

More to Explore

Tech Talk: Running a Self-Improving AI Agent with Hermes on Vultr

Tech Talk: Implementing Fine-Grained Access Control with Vultr IAM

Tech Talk: Getting Started with Vultr IAM

Tech Talk: Simplifying Zero-Trust Networking with NetBird on Vultr Marketplace

0 Comments

How to Deploy NATS – High-Performance Messaging

Prerequisites

Set Up the Directory Structure and Environment Variables

Install NATS CLI and Create the NATS Configuration

Deploy with Docker Compose

Verify NATS Connectivity

Conclusion

About the Author

Aashish Chaurasiya

More to Explore

Tech Talk: Running a Self-Improving AI Agent with Hermes on Vultr

Tech Talk: Implementing Fine-Grained Access Control with Vultr IAM

Tech Talk: Getting Started with Vultr IAM

Tech Talk: Simplifying Zero-Trust Networking with NetBird on Vultr Marketplace

0 Comments