> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nats-io/nats-server/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
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:

<CodeGroup>
  ```bash All Ports theme={null}
  docker run -d --name nats-server \
    -p 4222:4222 \
    -p 8222:8222 \
    -p 6222:6222 \
    nats:latest
  ```

  ```bash Client Only theme={null}
  docker run -d --name nats-server \
    -p 4222:4222 \
    nats:latest
  ```
</CodeGroup>

| 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:

```bash theme={null}
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:

```bash theme={null}
docker run -d --name nats-server \
  -p 4222:4222 \
  -v nats-data:/data \
  nats:latest -js -sd /data
```

### Complete Example

```bash theme={null}
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:

```yaml docker-compose.yml theme={null}
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:

```bash theme={null}
docker-compose up -d
```

## Clustering with Docker Compose

Deploy a 3-node NATS cluster:

```yaml docker-compose-cluster.yml theme={null}
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`:

```conf nats-server.conf theme={null}
# 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:

```bash theme={null}
docker run -d --name nats-server \
  -p 4222:4222 \
  nats:latest \
  --port 4222 \
  --http_port 8222 \
  --cluster_name my-cluster \
  -js \
  --store_dir /data
```

<Info>
  Command-line flags take precedence over configuration file settings.
</Info>

## JetStream with Docker

Enable JetStream with persistent storage:

```bash theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
docker run --rm nats:latest --version
```

## Environment Variables

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

```conf theme={null}
port: $NATS_PORT
monitor_port: $NATS_MONITOR_PORT
```

Then pass them to Docker:

```bash theme={null}
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:

```bash theme={null}
docker logs nats-server
```

Follow logs in real-time:

```bash theme={null}
docker logs -f nats-server
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Named Volumes" icon="database">
    Always use named volumes for JetStream data to ensure persistence across container restarts.
  </Card>

  <Card title="Configure Resource Limits" icon="gauge">
    Set memory and CPU limits to prevent resource exhaustion in production.
  </Card>

  <Card title="Enable Monitoring" icon="chart-line">
    Always expose the monitoring port (8222) for health checks and metrics.
  </Card>

  <Card title="Use Configuration Files" icon="file-code">
    Prefer configuration files over command-line flags for complex deployments.
  </Card>
</CardGroup>

## Troubleshooting

### Container Won't Start

Check logs for configuration errors:

```bash theme={null}
docker logs nats-server
```

### Connection Refused

Verify port mappings:

```bash theme={null}
docker port nats-server
```

### Configuration Not Loading

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

```bash theme={null}
docker exec nats-server cat /nats/conf/nats-server.conf
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Kubernetes Deployment" icon="dharmachakra" href="/deployment/kubernetes">
    Learn how to deploy NATS on Kubernetes
  </Card>

  <Card title="Configuration" icon="gear" href="/deployment/configuration">
    Explore advanced configuration options
  </Card>
</CardGroup>