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:
The image includes:
nats-server - The NATS Server binarynats - The NATS CLI toolnsc - 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:
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:
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:
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:
# 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:
Builds NATS Server, NSC, and NATS CLI from source
Creates a minimal Alpine-based image
Exposes ports 4222, 8222, 6222, and 5222
Sets the entrypoint to /bin/nats-server
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:
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:
Connection Refused Verify port mappings:
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