Docker Deployment

Deploy NATS Server using Docker containers with official images

NATS Server provides official Docker images that make it easy to run NATS in containerized environments. The images are available on Docker Hub and include the server along with useful utilities.

Official Docker Image

The official NATS Server image is available at:

docker pull nats:latest

The image includes:

• nats-server - The NATS Server binary
• nats - The NATS CLI tool
• nsc - The NATS Security CLI

Quick Start

Run a basic NATS Server with default settings:

docker run -d --name nats-server -p 4222:4222 nats:latest

This exposes the client port (4222) on your host machine.

Port Mappings

NATS Server uses several ports for different purposes:

All Ports

docker run -d --name nats-server \
  -p 4222:4222 \
  -p 8222:8222 \
  -p 6222:6222 \
  nats:latest

Port	Purpose	Description
4222	Client	Main port for client connections
8222	Monitoring	HTTP monitoring endpoint
6222	Cluster	Port for cluster route connections
5222	MQTT	MQTT protocol support (when enabled)

Volume Mounts

Configuration File

Mount a custom configuration file:

docker run -d --name nats-server \
  -p 4222:4222 \
  -v /path/to/nats-server.conf:/nats/conf/nats-server.conf \
  nats:latest -c /nats/conf/nats-server.conf

Data Persistence

For JetStream deployments, mount a volume for data persistence:

docker run -d --name nats-server \
  -p 4222:4222 \
  -v nats-data:/data \
  nats:latest -js -sd /data

Complete Example

docker run -d --name nats-server \
  -p 4222:4222 \
  -p 8222:8222 \
  -p 6222:6222 \
  -v /path/to/nats-server.conf:/nats/conf/nats-server.conf \
  -v nats-data:/data \
  nats:latest -c /nats/conf/nats-server.conf

Docker Compose

For more complex deployments, use Docker Compose:

docker-compose.yml

version: '3.8'

services:
  nats:
    image: nats:latest
    container_name: nats-server
    ports:
      - "4222:4222"  # Client connections
      - "8222:8222"  # HTTP monitoring
      - "6222:6222"  # Cluster routing
    volumes:
      - ./nats-server.conf:/nats/conf/nats-server.conf
      - nats-data:/data
    command: ["-c", "/nats/conf/nats-server.conf"]
    restart: unless-stopped
    networks:
      - nats-network

volumes:
  nats-data:
    driver: local

networks:
  nats-network:
    driver: bridge

Start the service:

docker-compose up -d

Clustering with Docker Compose

Deploy a 3-node NATS cluster:

docker-compose-cluster.yml

version: '3.8'

services:
  nats-1:
    image: nats:latest
    ports:
      - "4222:4222"
      - "8222:8222"
    command: [
      "--cluster_name", "nats-cluster",
      "--cluster", "nats://0.0.0.0:6222",
      "--routes", "nats://nats-2:6222,nats://nats-3:6222",
      "--http_port", "8222"
    ]
    networks:
      - nats-cluster

  nats-2:
    image: nats:latest
    command: [
      "--cluster_name", "nats-cluster",
      "--cluster", "nats://0.0.0.0:6222",
      "--routes", "nats://nats-1:6222,nats://nats-3:6222"
    ]
    networks:
      - nats-cluster

  nats-3:
    image: nats:latest
    command: [
      "--cluster_name", "nats-cluster",
      "--cluster", "nats://0.0.0.0:6222",
      "--routes", "nats://nats-1:6222,nats://nats-2:6222"
    ]
    networks:
      - nats-cluster

networks:
  nats-cluster:
    driver: bridge

Default Configuration

The Docker image includes a default configuration file at /nats/conf/nats-server.conf:

nats-server.conf

# Client port of 4222 on all interfaces
port: 4222

# HTTP monitoring port
monitor_port: 8222

# This is for clustering multiple servers together.
cluster {
  # Route connections to be received on any interface on port 6222
  port: 6222

  # Routes are protected, so need to use them with --routes flag
  # e.g. --routes=nats-route://ruser:T0pS3cr3t@otherdockerhost:6222
  authorization {
    user: ruser
    password: T0pS3cr3t
    timeout: 2
  }

  # Routes are actively solicited and connected to from this server.
  routes = []
}

Command Line Flags

You can override configuration using command-line flags:

docker run -d --name nats-server \
  -p 4222:4222 \
  nats:latest \
  --port 4222 \
  --http_port 8222 \
  --cluster_name my-cluster \
  -js \
  --store_dir /data

Command-line flags take precedence over configuration file settings.

JetStream with Docker

Enable JetStream with persistent storage:

docker run -d --name nats-jetstream \
  -p 4222:4222 \
  -p 8222:8222 \
  -v nats-data:/data \
  nats:latest \
  -js \
  -sd /data

Health Checks

Add a health check to your Docker configuration:

services:
  nats:
    image: nats:latest
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8222/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Or using curl:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8222/healthz"]
  interval: 30s
  timeout: 10s
  retries: 3

Inspecting the Image

The NATS Docker image is built using a multi-stage Dockerfile that:

1. Builds NATS Server, NSC, and NATS CLI from source
2. Creates a minimal Alpine-based image
3. Exposes ports 4222, 8222, 6222, and 5222
4. Sets the entrypoint to /bin/nats-server
5. Includes a default configuration file

View the installed version:

docker run --rm nats:latest --version

Environment Variables

While NATS Server primarily uses configuration files, you can use environment variables in your configuration:

port: $NATS_PORT
monitor_port: $NATS_MONITOR_PORT

Then pass them to Docker:

docker run -d --name nats-server \
  -e NATS_PORT=4222 \
  -e NATS_MONITOR_PORT=8222 \
  -p 4222:4222 \
  -v ./nats-server.conf:/nats/conf/nats-server.conf \
  nats:latest -c /nats/conf/nats-server.conf

Logging

View container logs:

docker logs nats-server

Follow logs in real-time:

docker logs -f nats-server

Best Practices

Use Named Volumes

Always use named volumes for JetStream data to ensure persistence across container restarts.

Configure Resource Limits

Set memory and CPU limits to prevent resource exhaustion in production.

Enable Monitoring

Always expose the monitoring port (8222) for health checks and metrics.

Use Configuration Files

Prefer configuration files over command-line flags for complex deployments.

Troubleshooting

Container Won’t Start

Check logs for configuration errors:

docker logs nats-server

Connection Refused

Verify port mappings:

docker port nats-server

Configuration Not Loading

Ensure the config file path is correct and the file is mounted properly:

docker exec nats-server cat /nats/conf/nats-server.conf

Next Steps

Kubernetes Deployment

Learn how to deploy NATS on Kubernetes

Configuration

Explore advanced configuration options