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

# Installation

> Install NATS Server on your platform using Docker, binary downloads, or package managers

NATS Server is distributed as a single binary with no external dependencies, making installation straightforward on any platform.

## System requirements

<Note>
  NATS Server has minimal system requirements and can run on resource-constrained devices including Raspberry Pi.
</Note>

**Minimum requirements:**

* **CPU**: 1 core (2+ cores recommended for production)
* **Memory**: 128 MB RAM (varies based on workload)
* **Disk**: 50 MB for binary (additional storage needed for JetStream)
* **OS**: Linux, macOS, Windows, or any platform with Go support

**Default ports:**

* **4222**: Client connections
* **6222**: Cluster routing
* **8222**: HTTP monitoring (when enabled)
* **5222**: Gateway connections (for super-clusters)

## Installation methods

<Tabs>
  <Tab title="Docker">
    Docker is the fastest way to get started with NATS Server.

    ### Pull the official image

    ```bash theme={null}
    docker pull nats:latest
    ```

    The Docker image includes:

    * `nats-server` - The NATS Server binary
    * `nats` - The NATS CLI tool
    * `nsc` - The NATS Security CLI

    ### Run the server

    ```bash theme={null}
    # Basic run
    docker run -p 4222:4222 -p 8222:8222 nats:latest

    # With JetStream enabled
    docker run -p 4222:4222 -p 8222:8222 -v /path/to/storage:/data \
      nats:latest -js --store_dir /data

    # With custom configuration
    docker run -p 4222:4222 -p 8222:8222 \
      -v /path/to/nats-server.conf:/nats/conf/nats-server.conf \
      nats:latest -c /nats/conf/nats-server.conf
    ```

    ### Exposed ports in Docker image

    The official Docker image exposes these ports by default:

    ```dockerfile theme={null}
    EXPOSE 4222 8222 6222 5222
    ```

    <Info>
      The default Docker configuration file is located at `/nats/conf/nats-server.conf` and includes basic settings for client and cluster ports.
    </Info>

    ### Docker Compose example

    ```yaml theme={null}
    version: '3.8'
    services:
      nats:
        image: nats:latest
        ports:
          - "4222:4222"
          - "8222:8222"
          - "6222:6222"
        command: ["-js", "--store_dir", "/data", "-m", "8222"]
        volumes:
          - nats-data:/data

    volumes:
      nats-data:
    ```
  </Tab>

  <Tab title="Binary Download">
    Download pre-built binaries for your platform from the GitHub releases page.

    ### Download and install

    <CodeGroup>
      ```bash Linux/macOS theme={null}
      # Download the latest release
      curl -L https://github.com/nats-io/nats-server/releases/latest/download/nats-server-v2.x.x-linux-amd64.tar.gz -o nats-server.tar.gz

      # Extract
      tar -xzf nats-server.tar.gz

      # Move to PATH
      sudo mv nats-server-v2.x.x-linux-amd64/nats-server /usr/local/bin/

      # Verify installation
      nats-server --version
      ```

      ```powershell Windows theme={null}
      # Download from GitHub releases page
      # https://github.com/nats-io/nats-server/releases

      # Extract the ZIP file

      # Add to PATH or run directly
      .\nats-server.exe --version
      ```
    </CodeGroup>

    ### Available platforms

    Binaries are available for:

    * Linux (amd64, arm64, arm6, arm7)
    * macOS (amd64, arm64)
    * Windows (amd64, arm64)
    * FreeBSD (amd64)

    <Tip>
      Visit [GitHub Releases](https://github.com/nats-io/nats-server/releases/) to download the appropriate binary for your platform.
    </Tip>
  </Tab>

  <Tab title="Package Managers">
    Install NATS Server using your operating system's package manager.

    ### macOS (Homebrew)

    ```bash theme={null}
    brew install nats-server
    ```

    ### Linux (Snap)

    ```bash theme={null}
    sudo snap install nats-server
    ```

    ### Windows (Chocolatey)

    ```powershell theme={null}
    choco install nats-server
    ```

    ### Arch Linux (AUR)

    ```bash theme={null}
    yay -S nats-server
    ```

    ### Verify installation

    ```bash theme={null}
    nats-server --version
    ```
  </Tab>

  <Tab title="Build from Source">
    Build NATS Server from source code if you need the latest development version or want to customize the build.

    ### Prerequisites

    * Go 1.20 or later
    * Git

    ### Build steps

    ```bash theme={null}
    # Clone the repository
    git clone https://github.com/nats-io/nats-server.git
    cd nats-server

    # Build
    go build -o nats-server

    # Optionally install
    sudo mv nats-server /usr/local/bin/

    # Verify
    nats-server --version
    ```

    ### Build with version information

    ```bash theme={null}
    VERSION=$(git describe --tags --always)
    GIT_COMMIT=$(git rev-parse HEAD)

    go build -trimpath \
      -ldflags "-w -X server.serverVersion=${VERSION} -X server.gitCommit=${GIT_COMMIT}" \
      -o nats-server .
    ```

    <Info>
      The build process is the same as used in the official Docker image, which uses Go's build system with CGO disabled for maximum portability.
    </Info>
  </Tab>
</Tabs>

## Post-installation steps

### Verify installation

Check that NATS Server is installed correctly:

```bash theme={null}
# Check version
nats-server --version

# View help
nats-server --help

# Test configuration (if you have a config file)
nats-server -c /path/to/nats-server.conf -t
```

### Start the server

Start NATS Server with default settings:

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

Common startup options:

```bash theme={null}
# Specify host and port
nats-server -a 0.0.0.0 -p 4222

# Enable monitoring
nats-server -m 8222

# Enable JetStream
nats-server -js --store_dir /var/lib/nats

# Use configuration file
nats-server -c /etc/nats/nats-server.conf

# Enable debug logging
nats-server -D
```

<Warning>
  The default configuration binds to `0.0.0.0:4222` which accepts connections from any network interface. For production deployments, bind to specific interfaces and enable authentication.
</Warning>

## Configuration

### Configuration file location

NATS Server looks for configuration files in these locations:

* **Docker**: `/nats/conf/nats-server.conf`
* **Linux**: `/etc/nats/nats-server.conf` (conventional)
* **macOS**: `/usr/local/etc/nats-server.conf` (conventional)
* **Windows**: `C:\nats\nats-server.conf` (conventional)

You can specify a custom location with the `-c` flag:

```bash theme={null}
nats-server -c /path/to/your/config.conf
```

### Basic configuration example

Create a basic configuration file:

```conf nats-server.conf theme={null}
# Client port
port: 4222

# HTTP monitoring port
monitor_port: 8222

# Clustering configuration
cluster {
  # Cluster port
  port: 6222

  # Routes for clustering
  routes = [
    nats-route://nats1:6222
    nats-route://nats2:6222
  ]

  # Cluster authorization
  authorization {
    user: ruser
    password: T0pS3cr3t
    timeout: 2
  }
}

# JetStream configuration
jetstream {
  store_dir: "/data/nats/jetstream"
  max_memory_store: 1GB
  max_file_store: 10GB
}
```

<Tip>
  Use `nats-server -c your-config.conf -t` to test your configuration file for syntax errors before starting the server.
</Tip>

### Simple configuration example from source

From the NATS Server repository:

```conf simple.conf theme={null}
listen: 127.0.0.1:4222

authorization {
  include 'includes/users.conf'
  timeout: 0.5
}
```

## Running as a service

### Linux (systemd)

Create a systemd service file at `/etc/systemd/system/nats-server.service`:

```ini theme={null}
[Unit]
Description=NATS Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nats-server -c /etc/nats/nats-server.conf
ExecReload=/bin/kill -s HUP $MAINPID
Restart=on-failure
User=nats
Group=nats

[Install]
WantedBy=multi-user.target
```

Enable and start the service:

```bash theme={null}
sudo systemctl enable nats-server
sudo systemctl start nats-server
sudo systemctl status nats-server
```

### macOS (launchd)

Create a plist file at `~/Library/LaunchAgents/io.nats.server.plist`:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>io.nats.server</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/nats-server</string>
    <string>-c</string>
    <string>/usr/local/etc/nats-server.conf</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>
```

Load the service:

```bash theme={null}
launchctl load ~/Library/LaunchAgents/io.nats.server.plist
```

## Command-line reference

Here's an overview of common command-line options from the source:

### Server options

```bash theme={null}
-a, --addr, --net <host>         Bind to host address (default: 0.0.0.0)
-p, --port <port>                Use port for clients (default: 4222)
-n, --name, --server_name <name> Server name (default: auto)
-P, --pid <file>                 File to store PID
-m, --http_port <port>           HTTP monitoring port
-c, --config <file>              Configuration file
-t                               Test configuration and exit
-sl, --signal <signal>[=<pid>]   Send signal (ldm, stop, quit, term, reopen, reload)
```

### Logging options

```bash theme={null}
-l, --log <file>                 File to redirect log output
-T, --logtime                    Timestamp log entries (default: true)
-D, --debug                      Enable debugging output
-V, --trace                      Trace the raw protocol
-DV                              Debug and trace
```

### JetStream options

```bash theme={null}
-js, --jetstream                 Enable JetStream functionality
-sd, --store_dir <dir>           Set the storage directory
```

### Authorization options

```bash theme={null}
--user <user>                    User required for connections
--pass <password>                Password required for connections
--auth <token>                   Authorization token
```

### TLS options

```bash theme={null}
--tls                            Enable TLS
--tlscert <file>                 Server certificate file
--tlskey <file>                  Private key for certificate
--tlsverify                      Enable TLS, verify clients
--tlscacert <file>               Client certificate CA
```

### Cluster options

```bash theme={null}
--routes <rurl-1, rurl-2>        Routes to solicit and connect
--cluster <cluster-url>          Cluster URL for solicited routes
--cluster_name <string>          Cluster name
--cluster_listen <url>           Cluster URL for incoming routes
```

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Follow the quickstart guide to send your first message
  </Card>

  <Card title="Configuration" icon="gear" href="/deployment/configuration">
    Learn about advanced configuration options
  </Card>

  <Card title="Security" icon="lock" href="/operations/security">
    Secure your NATS Server deployment
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/features/monitoring">
    Set up monitoring and observability
  </Card>
</CardGroup>