# **DEPRECATION NOTICE** The NATS Streaming Server is being deprecated. Critical bug fixes and security fixes will be applied until June of 2023. NATS enabled applications requiring persistence should use [JetStream](https://docs.nats.io/jetstream/jetstream). # Quick reference - **Maintained by**: [the NATS Project](https://github.com/nats-io/nats-streaming-docker) - **Where to get help**: [the Docker Community Slack](https://dockr.ly/comm-slack), [Server Fault](https://serverfault.com/help/on-topic), [Unix & Linux](https://unix.stackexchange.com/help/on-topic), or [Stack Overflow](https://stackoverflow.com/help/on-topic) # Supported tags and respective `Dockerfile` links (See ["What's the difference between 'Shared' and 'Simple' tags?" in the FAQ](https://github.com/docker-library/faq#whats-the-difference-between-shared-and-simple-tags).) ## Simple Tags - [`0.25.5-alpine3.18`, `0.25-alpine3.18`, `alpine3.18`, `0.25.5-alpine`, `0.25-alpine`, `alpine`](https://github.com/nats-io/nats-streaming-docker/blob/d8dd9e2f5f7943f6a4d08de304f2bce513cc6735/0.25.5/alpine3.18/Dockerfile) - [`0.25.5-scratch`, `0.25-scratch`, `scratch`, `0.25.5-linux`, `0.25-linux`, `linux`](https://github.com/nats-io/nats-streaming-docker/blob/d8dd9e2f5f7943f6a4d08de304f2bce513cc6735/0.25.5/scratch/Dockerfile) - [`0.25.5-windowsservercore-1809`, `0.25-windowsservercore-1809`, `windowsservercore-1809`](https://github.com/nats-io/nats-streaming-docker/blob/d8dd9e2f5f7943f6a4d08de304f2bce513cc6735/0.25.5/windowsservercore-1809/Dockerfile) - [`0.25.5-nanoserver-1809`, `0.25-nanoserver-1809`, `nanoserver-1809`](https://github.com/nats-io/nats-streaming-docker/blob/d8dd9e2f5f7943f6a4d08de304f2bce513cc6735/0.25.5/nanoserver-1809/Dockerfile) ## Shared Tags - `0.25.5`, `0.25`, `latest`: - [`0.25.5-scratch`](https://github.com/nats-io/nats-streaming-docker/blob/d8dd9e2f5f7943f6a4d08de304f2bce513cc6735/0.25.5/scratch/Dockerfile) - [`0.25.5-nanoserver-1809`](https://github.com/nats-io/nats-streaming-docker/blob/d8dd9e2f5f7943f6a4d08de304f2bce513cc6735/0.25.5/nanoserver-1809/Dockerfile) - `0.25.5-windowsservercore`, `0.25-windowsservercore`, `windowsservercore`: - [`0.25.5-windowsservercore-1809`](https://github.com/nats-io/nats-streaming-docker/blob/d8dd9e2f5f7943f6a4d08de304f2bce513cc6735/0.25.5/windowsservercore-1809/Dockerfile) - `0.25.5-nanoserver`, `0.25-nanoserver`, `nanoserver`: - [`0.25.5-nanoserver-1809`](https://github.com/nats-io/nats-streaming-docker/blob/d8dd9e2f5f7943f6a4d08de304f2bce513cc6735/0.25.5/nanoserver-1809/Dockerfile) # Quick reference (cont.) - **Where to file issues**: [https://github.com/nats-io/nats-streaming-docker/issues](https://github.com/nats-io/nats-streaming-docker/issues?q=) - **Supported architectures**: ([more info](https://github.com/docker-library/official-images#architectures-other-than-amd64)) [`amd64`](https://hub.docker.com/r/amd64/nats-streaming/), [`arm32v6`](https://hub.docker.com/r/arm32v6/nats-streaming/), [`arm32v7`](https://hub.docker.com/r/arm32v7/nats-streaming/), [`arm64v8`](https://hub.docker.com/r/arm64v8/nats-streaming/), [`windows-amd64`](https://hub.docker.com/r/winamd64/nats-streaming/) - **Published image artifact details**: [repo-info repo's `repos/nats-streaming/` directory](https://github.com/docker-library/repo-info/blob/master/repos/nats-streaming) ([history](https://github.com/docker-library/repo-info/commits/master/repos/nats-streaming)) (image metadata, transfer size, etc) - **Image updates**: [official-images repo's `library/nats-streaming` label](https://github.com/docker-library/official-images/issues?q=label%3Alibrary%2Fnats-streaming) [official-images repo's `library/nats-streaming` file](https://github.com/docker-library/official-images/blob/master/library/nats-streaming) ([history](https://github.com/docker-library/official-images/commits/master/library/nats-streaming)) - **Source of this description**: [docs repo's `nats-streaming/` directory](https://github.com/docker-library/docs/tree/master/nats-streaming) ([history](https://github.com/docker-library/docs/commits/master/nats-streaming)) # [NATS Streaming](https://nats.io): A high-performance cloud native messaging streaming system.  `nats-streaming` is a high performance streaming server for the NATS Messaging System. # Backward compatibility note Note that the Streaming server itself is backward compatible with previous releases, however, v0.15.0+ now embeds a NATS Server 2.0, which means that if you run with the embedded NATS server and want to route it to your existing v0.14.3- servers, it will fail due to NATS Server routing protocol change. You can however use v0.15.0+ and connect it to existing NATS cluster and therefore have a mix of v0.15.0 and v0.14.3- streaming servers. # Windows Docker images Due to restrictions on how the Windows Docker Image is built, running the image without argument will run the NATS Streaming server with memory based store on port 4222 and the monitoring port 8222. If you need to specify any additional argument, or modify these options, you need to specify the executable name as this: ```bash $ docker run -p 4223:4223 -p 8223:8223 nats-streaming nats-streaming-server -p 4223 -m 8223 ``` If you need to specify the entrypoint: ```bash $ docker run --entrypoint c:/nats-streaming-server/nats-streaming-server -p 4222:4222 -p 8222:8222 nats-streaming ``` # Non Windows Docker images If you need to provide arguments to the NATS Streaming server, just pass them to the command line. For instance, to change the listen and monitoring port to 4223 and 8223 respectively: ```bash $ docker run -p 4223:4223 -p 8223:8223 nats-streaming -p 4223 -m 8223 ``` If you need to specify the entrypoint: ```bash $ docker run --entrypoint /nats-streaming-server -p 4222:4222 -p 8222:8222 nats-streaming ``` # Example usage ```bash # Run a NATS Streaming server # Each server exposes multiple ports # 4222 is for clients. # 8222 is an HTTP management port for information reporting. # # To actually publish the ports when running the container, use the Docker port mapping # flag "docker run -p :" to publish and map one or more ports, # or the -P flag to publish all exposed ports and map them to high-order ports. # # This should not be confused with the NATS Streaming Server own -p parameter. # For instance, to run the NATS Streaming Server and have it listen on port 4444, # you would have to run like this: # # docker run -p 4444:4444 nats-streaming -p 4444 # # Or, if you want to publish the port 4444 as a different port, for example 5555: # # docker run -p 5555:4444 nats-streaming -p 4444 # # Check "docker run" for more information. $ docker run -d -p 4222:4222 -p 8222:8222 nats-streaming ``` Output that you would get if you had started with `-ti` instead of `d` (for daemon): ```bash [1] 2022/10/11 14:57:50.404688 [INF] STREAM: Starting nats-streaming-server[test-cluster] version 0.25.2 [1] 2022/10/11 14:57:50.404739 [INF] STREAM: ServerID: fbZJjwGYLBpNM5I8z23NSN [1] 2022/10/11 14:57:50.404741 [INF] STREAM: Go version: go1.19.2 [1] 2022/10/11 14:57:50.404743 [INF] STREAM: Git commit: [9e599667] [1] 2022/10/11 14:57:50.406004 [INF] Starting nats-server [1] 2022/10/11 14:57:50.406009 [INF] Version: 2.9.3 [1] 2022/10/11 14:57:50.406011 [INF] Git: [25e82d7] [1] 2022/10/11 14:57:50.406013 [INF] Name: NDQOBTB34ECZWAKAJAREPEXQPXGKUEJEZINCHV2CIHGGJQCSCVPQPU5W [1] 2022/10/11 14:57:50.406015 [INF] ID: NDQOBTB34ECZWAKAJAREPEXQPXGKUEJEZINCHV2CIHGGJQCSCVPQPU5W [1] 2022/10/11 14:57:50.406423 [INF] Listening for client connections on 0.0.0.0:4222 [1] 2022/10/11 14:57:50.406679 [INF] Server is ready [1] 2022/10/11 14:57:50.434935 [INF] STREAM: Recovering the state... [1] 2022/10/11 14:57:50.434945 [INF] STREAM: No recovered state [1] 2022/10/11 14:57:50.435271 [INF] STREAM: Message store is MEMORY [1] 2022/10/11 14:57:50.435303 [INF] STREAM: ---------- Store Limits ---------- [1] 2022/10/11 14:57:50.435306 [INF] STREAM: Channels: 100 * [1] 2022/10/11 14:57:50.435308 [INF] STREAM: --------- Channels Limits -------- [1] 2022/10/11 14:57:50.435310 [INF] STREAM: Subscriptions: 1000 * [1] 2022/10/11 14:57:50.435311 [INF] STREAM: Messages : 1000000 * [1] 2022/10/11 14:57:50.435313 [INF] STREAM: Bytes : 976.56 MB * [1] 2022/10/11 14:57:50.435315 [INF] STREAM: Age : unlimited * [1] 2022/10/11 14:57:50.435316 [INF] STREAM: Inactivity : unlimited * [1] 2022/10/11 14:57:50.435318 [INF] STREAM: ---------------------------------- [1] 2022/10/11 14:57:50.435320 [INF] STREAM: Streaming Server is ready ``` To use a file based store instead, you would run: ```bash $ docker run -d -p 4222:4222 -p 8222:8222 nats-streaming -store file -dir datastore [1] 2022/10/11 14:59:45.818823 [INF] STREAM: Starting nats-streaming-server[test-cluster] version 0.25.2 [1] 2022/10/11 14:59:45.818874 [INF] STREAM: ServerID: mNhpLEpCO6WFqrnD9CYEZa [1] 2022/10/11 14:59:45.818876 [INF] STREAM: Go version: go1.19.2 [1] 2022/10/11 14:59:45.818877 [INF] STREAM: Git commit: [9e599667] [1] 2022/10/11 14:59:45.820192 [INF] Starting nats-server [1] 2022/10/11 14:59:45.820196 [INF] Version: 2.9.3 [1] 2022/10/11 14:59:45.820198 [INF] Git: [25e82d7] [1] 2022/10/11 14:59:45.820200 [INF] Name: NCDMFFEVOSPVVGQZVEQ3O5434LHF2KAPOR5LKAI7YEIAFIABTHQLZRLA [1] 2022/10/11 14:59:45.820202 [INF] ID: NCDMFFEVOSPVVGQZVEQ3O5434LHF2KAPOR5LKAI7YEIAFIABTHQLZRLA [1] 2022/10/11 14:59:45.820688 [INF] Listening for client connections on 0.0.0.0:4222 [1] 2022/10/11 14:59:45.820849 [INF] Server is ready [1] 2022/10/11 14:59:45.848443 [INF] STREAM: Recovering the state... [1] 2022/10/11 14:59:45.848737 [INF] STREAM: No recovered state [1] 2022/10/11 14:59:45.849050 [INF] STREAM: Message store is FILE [1] 2022/10/11 14:59:45.849054 [INF] STREAM: Store location: datastore [1] 2022/10/11 14:59:45.849070 [INF] STREAM: ---------- Store Limits ---------- [1] 2022/10/11 14:59:45.849072 [INF] STREAM: Channels: 100 * [1] 2022/10/11 14:59:45.849073 [INF] STREAM: --------- Channels Limits -------- [1] 2022/10/11 14:59:45.849075 [INF] STREAM: Subscriptions: 1000 * [1] 2022/10/11 14:59:45.849076 [INF] STREAM: Messages : 1000000 * [1] 2022/10/11 14:59:45.849077 [INF] STREAM: Bytes : 976.56 MB * [1] 2022/10/11 14:59:45.849078 [INF] STREAM: Age : unlimited * [1] 2022/10/11 14:59:45.849079 [INF] STREAM: Inactivity : unlimited * [1] 2022/10/11 14:59:45.849080 [INF] STREAM: ---------------------------------- [1] 2022/10/11 14:59:45.849082 [INF] STREAM: Streaming Server is ready ``` You can also connect to a remote NATS Server running in a docker image. First, run NATS Server: ```bash $ docker run -d --name=nats-main -p 4222:4222 -p 6222:6222 -p 8222:8222 nats ``` Now, start the Streaming server and link it to the above docker image: ```bash $ docker run -d --link nats-main nats-streaming -store file -dir datastore -ns nats://nats-main:4222 [1] 2022/10/11 15:00:56.780184 [INF] STREAM: Starting nats-streaming-server[test-cluster] version 0.25.2 [1] 2022/10/11 15:00:56.780235 [INF] STREAM: ServerID: jVQkB4KiIN4IVIuVoSumE0 [1] 2022/10/11 15:00:56.780237 [INF] STREAM: Go version: go1.19.2 [1] 2022/10/11 15:00:56.780241 [INF] STREAM: Git commit: [9e599667] [1] 2022/10/11 15:00:56.809173 [INF] STREAM: Recovering the state... [1] 2022/10/11 15:00:56.810336 [INF] STREAM: Recovered 0 channel(s) [1] 2022/10/11 15:00:56.810612 [INF] STREAM: Message store is FILE [1] 2022/10/11 15:00:56.810617 [INF] STREAM: Store location: datastore [1] 2022/10/11 15:00:56.810633 [INF] STREAM: ---------- Store Limits ---------- [1] 2022/10/11 15:00:56.810635 [INF] STREAM: Channels: 100 * [1] 2022/10/11 15:00:56.810636 [INF] STREAM: --------- Channels Limits -------- [1] 2022/10/11 15:00:56.810637 [INF] STREAM: Subscriptions: 1000 * [1] 2022/10/11 15:00:56.810639 [INF] STREAM: Messages : 1000000 * [1] 2022/10/11 15:00:56.810640 [INF] STREAM: Bytes : 976.56 MB * [1] 2022/10/11 15:00:56.810641 [INF] STREAM: Age : unlimited * [1] 2022/10/11 15:00:56.810642 [INF] STREAM: Inactivity : unlimited * [1] 2022/10/11 15:00:56.810643 [INF] STREAM: ---------------------------------- [1] 2022/10/11 15:00:56.810644 [INF] STREAM: Streaming Server is ready ``` Notice that the output shows that the NATS Server was not started, as opposed to the first output. # Commandline Options ```bash Streaming Server Options: -cid, --cluster_id Cluster ID (default: test-cluster) -st, --store Store type: MEMORY|FILE|SQL (default: MEMORY) --dir For FILE store type, this is the root directory -mc, --max_channels Max number of channels (0 for unlimited) -msu, --max_subs Max number of subscriptions per channel (0 for unlimited) -mm, --max_msgs Max number of messages per channel (0 for unlimited) -mb, --max_bytes Max messages total size per channel (0 for unlimited) -ma, --max_age Max duration a message can be stored ("0s" for unlimited) -mi, --max_inactivity Max inactivity (no new message, no subscription) after which a channel can be garbage collected (0 for unlimited) -ns, --nats_server Connect to this external NATS Server URL (embedded otherwise) -sc, --stan_config Streaming server configuration file -hbi, --hb_interval Interval at which server sends heartbeat to a client -hbt, --hb_timeout How long server waits for a heartbeat response -hbf, --hb_fail_count Number of failed heartbeats before server closes the client connection --ft_group Name of the FT Group. A group can be 2 or more servers with a single active server and all sharing the same datastore -sl, --signal [=] Send signal to nats-streaming-server process (stop, quit, reopen, reload - only for embedded NATS Server) --encrypt Specify if server should use encryption at rest --encryption_cipher Cipher to use for encryption. Currently support AES and CHAHA (ChaChaPoly). Defaults to AES --encryption_key Encryption Key. It is recommended to specify it through the NATS_STREAMING_ENCRYPTION_KEY environment variable instead --replace_durable Replace the existing durable subscription instead of reporting a duplicate durable error Streaming Server Clustering Options: --clustered Run the server in a clustered configuration (default: false) --cluster_node_id ID of the node within the cluster if there is no stored ID (default: random UUID) --cluster_bootstrap Bootstrap the cluster if there is no existing state by electing self as leader (default: false) --cluster_peers Comma separated list of cluster peer node IDs to bootstrap cluster state --cluster_log_path Directory to store log replication data --cluster_log_cache_size Number of log entries to cache in memory to reduce disk IO (default: 512) --cluster_log_snapshots Number of log snapshots to retain (default: 2) --cluster_trailing_logs Number of log entries to leave after a snapshot and compaction --cluster_sync Do a file sync after every write to the replication log and message store --cluster_raft_logging Enable logging from the Raft library (disabled by default) --cluster_allow_add_remove_node Enable the ability to send NATS requests to the leader to add/remove cluster nodes Streaming Server File Store Options: --file_compact_enabled Enable file compaction --file_compact_frag File fragmentation threshold for compaction --file_compact_interval Minimum interval (in seconds) between file compactions --file_compact_min_size Minimum file size for compaction --file_buffer_size File buffer size (in bytes) --file_crc Enable file CRC-32 checksum --file_crc_poly Polynomial used to make the table used for CRC-32 checksum --file_sync Enable File.Sync on Flush --file_slice_max_msgs Maximum number of messages per file slice (subject to channel limits) --file_slice_max_bytes Maximum file slice size - including index file (subject to channel limits) --file_slice_max_age Maximum file slice duration starting when the first message is stored (subject to channel limits) --file_slice_archive_script Path to script to use if you want to archive a file slice being removed --file_fds_limit Store will try to use no more file descriptors than this given limit --file_parallel_recovery On startup, number of channels that can be recovered in parallel --file_truncate_bad_eof Truncate files for which there is an unexpected EOF on recovery, dataloss may occur --file_read_buffer_size Size of messages read ahead buffer (0 to disable) --file_auto_sync Interval at which the store should be automatically flushed and sync'ed on disk (<= 0 to disable) Streaming Server SQL Store Options: --sql_driver Name of the SQL Driver ("mysql" or "postgres") --sql_source Datasource used when opening an SQL connection to the database --sql_no_caching Enable/Disable caching for improved performance --sql_max_open_conns Maximum number of opened connections to the database --sql_bulk_insert_limit Maximum number of messages stored with a single SQL "INSERT" statement Streaming Server TLS Options: -secure Use a TLS connection to the NATS server without verification; weaker than specifying certificates. -tls_client_key Client key for the streaming server -tls_client_cert Client certificate for the streaming server -tls_client_cacert Client certificate CA for the streaming server Streaming Server Logging Options: -SD, --stan_debug= Enable STAN debugging output -SV, --stan_trace= Trace the raw STAN protocol -SDV Debug and trace STAN --syslog_name On Windows, when running several servers as a service, use this name for the event source (See additional NATS logging options below) Embedded NATS Server Options: -a, --addr Bind to host address (default: 0.0.0.0) -p, --port Use port for clients (default: 4222) -P, --pid File to store PID -m, --http_port Use port for http monitoring -ms,--https_port Use port for https monitoring -c, --config Configuration file Logging Options: -l, --log File to redirect log output -T, --logtime= Timestamp log entries (default: true) -s, --syslog Enable syslog as log method -r, --remote_syslog Syslog server addr (udp://localhost:514) -D, --debug= Enable debugging output -V, --trace= Trace the raw protocol -DV Debug and trace Authorization Options: --user User required for connections --pass Password required for connections --auth Authorization token required for connections TLS Options: --tls= Enable TLS, do not verify clients (default: false) --tlscert Server certificate file --tlskey Private key for server certificate --tlsverify= Enable TLS, verify client certificates --tlscacert Client certificate CA for verification NATS Clustering Options: --routes Routes to solicit and connect --cluster Cluster URL for solicited routes Common Options: -h, --help Show this message -v, --version Show version --help_tls TLS help. ``` # Configuration Details on how to configure further the NATS Streaming server can be found [here](https://docs.nats.io/nats-streaming-server/configuring) # Image Variants The `nats-streaming` images come in many flavors, each designed for a specific use case. ## `nats-streaming:` This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. ## `nats-streaming:-alpine` This image is based on the popular [Alpine Linux project](https://alpinelinux.org), available in [the `alpine` official image](https://hub.docker.com/_/alpine). Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general. This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use [musl libc](https://musl.libc.org) instead of [glibc and friends](https://www.etalabs.net/compare_libcs.html), so software will often run into issues depending on the depth of their libc requirements/assumptions. See [this Hacker News comment thread](https://news.ycombinator.com/item?id=10782897) for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images. To minimize image size, it's uncommon for additional related tools (such as `git` or `bash`) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the [`alpine` image description](https://hub.docker.com/_/alpine/) for examples of how to install packages if you are unfamiliar). ## `nats-streaming:-windowsservercore` This image is based on [Windows Server Core (`microsoft/windowsservercore`)](https://hub.docker.com/r/microsoft/windowsservercore/). As such, it only works in places which that image does, such as Windows 10 Professional/Enterprise (Anniversary Edition) or Windows Server 2016. For information about how to get Docker running on Windows, please see the relevant "Quick Start" guide provided by Microsoft: - [Windows Server Quick Start](https://msdn.microsoft.com/en-us/virtualization/windowscontainers/quick_start/quick_start_windows_server) - [Windows 10 Quick Start](https://msdn.microsoft.com/en-us/virtualization/windowscontainers/quick_start/quick_start_windows_10) # License View [license information](https://github.com/nats-io/nats-streaming-server/blob/master/LICENSE) for the software contained in this image. As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained). Some additional license information which was able to be auto-detected might be found in [the `repo-info` repository's `nats-streaming/` directory](https://github.com/docker-library/repo-info/tree/master/repos/nats-streaming). As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.