mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
GitBook: [master] 326 pages and 16 assets modified
This commit is contained in:
Ginger Collison
committed by
gitbook-bot
gitbook-bot
parent
8b7ba5c3bb
commit
fb0d5c8355
260
nats-server/nats_docker/README.md
Normal file
260
nats-server/nats_docker/README.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# NATS and Docker
|
||||
|
||||
## NATS Server Containerization
|
||||
|
||||
The NATS server is provided as a Docker image on [Docker Hub](https://hub.docker.com/_/nats/) that you can run using the Docker daemon. The NATS server Docker image is extremely lightweight, coming in under 10 MB in size.
|
||||
|
||||
[Synadia](https://synadia.com) actively maintains and supports the NATS server Docker image.
|
||||
|
||||
### Usage
|
||||
|
||||
To use the Docker container image, install Docker and pull the public image:
|
||||
|
||||
```bash
|
||||
> docker pull nats
|
||||
```
|
||||
|
||||
Run the NATS server image:
|
||||
|
||||
```bash
|
||||
> docker run -d --name nats-main nats
|
||||
```
|
||||
|
||||
By default the NATS server exposes multiple ports:
|
||||
|
||||
* 4222 is for clients.
|
||||
* 8222 is an HTTP management port for information reporting.
|
||||
* 6222 is a routing port for clustering.
|
||||
* Use -p or -P to customize.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
$ docker run -d --name nats-main nats
|
||||
[INF] Starting nats-server version 0.6.6
|
||||
[INF] Starting http monitor on port 8222
|
||||
[INF] Listening for route connections on 0.0.0.0:6222
|
||||
[INF] Listening for client connections on 0.0.0.0:4222
|
||||
[INF] nats-server is ready
|
||||
```
|
||||
|
||||
To run with the ports exposed on the host:
|
||||
|
||||
```bash
|
||||
> docker run -d -p 4222:4222 -p 6222:6222 -p 8222:8222 --name nats-main nats
|
||||
```
|
||||
|
||||
To run a second server and cluster them together:
|
||||
|
||||
```bash
|
||||
> docker run -d --name=nats-2 --link nats-main nats --routes=nats-route://ruser:T0pS3cr3t@nats-main:6222
|
||||
```
|
||||
|
||||
**NOTE** Since the Docker image protects routes using credentials we need to provide them above. Extracted [from Docker image configuration](https://github.com/nats-io/nats-docker/blob/master/amd64/nats-server.conf#L16-L20)
|
||||
|
||||
```text
|
||||
# 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
|
||||
}
|
||||
```
|
||||
|
||||
To verify the routes are connected:
|
||||
|
||||
```bash
|
||||
$ docker run -d --name=nats-2 --link nats-main nats --routes=nats-route://ruser:T0pS3cr3t@nats-main:6222 -DV
|
||||
[INF] Starting nats-server version 2.0.0
|
||||
[INF] Starting http monitor on port 8222
|
||||
[INF] Listening for route connections on :6222
|
||||
[INF] Listening for client connections on 0.0.0.0:4222
|
||||
[INF] nats-server is ready
|
||||
[DBG] Trying to connect to route on nats-main:6222
|
||||
[DBG] 172.17.0.52:6222 - rid:1 - Route connection created
|
||||
[DBG] 172.17.0.52:6222 - rid:1 - Route connect msg sent
|
||||
[DBG] 172.17.0.52:6222 - rid:1 - Registering remote route "ee35d227433a738c729f9422a59667bb"
|
||||
[DBG] 172.17.0.52:6222 - rid:1 - Route sent local subscriptions
|
||||
```
|
||||
|
||||
## Clustering With Docker
|
||||
|
||||
Below is are a couple examples of how to setup nats-server cluster using Docker. We put 3 different configurations \(one per nats-server server\) under a folder named conf as follows:
|
||||
|
||||
```text
|
||||
|-- conf
|
||||
|-- nats-server-A.conf
|
||||
|-- nats-server-B.conf
|
||||
|-- nats-server-C.conf
|
||||
```
|
||||
|
||||
Each one of those files have the following content below: \(Here I am using ip 192.168.59.103 as an example, so just replace with the proper ip from your server\)
|
||||
|
||||
### Example 1: Setting up a cluster on 3 different servers provisioned beforehand
|
||||
|
||||
In this example, the three servers are started with config files that know about the other servers.
|
||||
|
||||
#### nats-server-A
|
||||
|
||||
```text
|
||||
# Cluster Server A
|
||||
|
||||
port: 7222
|
||||
|
||||
cluster {
|
||||
host: '0.0.0.0'
|
||||
port: 7244
|
||||
|
||||
routes = [
|
||||
nats-route://192.168.59.103:7246
|
||||
nats-route://192.168.59.103:7248
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### nats-server-B
|
||||
|
||||
```text
|
||||
# Cluster Server B
|
||||
|
||||
port: 8222
|
||||
|
||||
cluster {
|
||||
host: '0.0.0.0'
|
||||
port: 7246
|
||||
|
||||
routes = [
|
||||
nats-route://192.168.59.103:7244
|
||||
nats-route://192.168.59.103:7248
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### nats-server-C
|
||||
|
||||
```text
|
||||
# Cluster Server C
|
||||
|
||||
port: 9222
|
||||
|
||||
cluster {
|
||||
host: '0.0.0.0'
|
||||
port: 7248
|
||||
|
||||
routes = [
|
||||
nats-route://192.168.59.103:7244
|
||||
nats-route://192.168.59.103:7246
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
To start the containers, on each one of your servers, you should be able to start the nats-server image as follows:
|
||||
|
||||
```bash
|
||||
docker run -it -p 0.0.0.0:7222:7222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-A.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 7222 -D -V
|
||||
```
|
||||
|
||||
```text
|
||||
docker run -it -p 0.0.0.0:8222:8222 -p 0.0.0.0:7246:7246 --rm -v $(pwd)/conf/nats-server-B.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 8222 -D -V
|
||||
```
|
||||
|
||||
```text
|
||||
docker run -it -p 0.0.0.0:9222:9222 -p 0.0.0.0:7248:7248 --rm -v $(pwd)/conf/nats-server-C.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 9222 -D -V
|
||||
```
|
||||
|
||||
### Example 2: Setting a nats-server cluster one by one
|
||||
|
||||
In this scenario:
|
||||
|
||||
* We bring up A and get its ip \(nats-route://192.168.59.103:7244\)
|
||||
* Then create B and then use address of A in its configuration.
|
||||
* Get the address of B nats-route://192.168.59.104:7246 and create C and use the addresses of A and B.
|
||||
|
||||
First, we create the Node A and start up a nats-server server with the following config:
|
||||
|
||||
```text
|
||||
# Cluster Server A
|
||||
|
||||
port: 4222
|
||||
|
||||
cluster {
|
||||
host: '0.0.0.0'
|
||||
port: 7244
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-A.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 4222 -D -V
|
||||
```
|
||||
|
||||
Then we proceed to create the next node. We realize that the first node has ip:port as `192.168.59.103:7244` so we add this to the routes configuration as follows:
|
||||
|
||||
```text
|
||||
# Cluster Server B
|
||||
|
||||
port: 4222
|
||||
|
||||
cluster {
|
||||
host: '0.0.0.0'
|
||||
port: 7244
|
||||
|
||||
routes = [
|
||||
nats-route://192.168.59.103:7244
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Then start server B:
|
||||
|
||||
```bash
|
||||
docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-B.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 4222 -D -V
|
||||
```
|
||||
|
||||
Finally, we create another Node C. We now know the routes of A and B so we can add it to its configuration:
|
||||
|
||||
```text
|
||||
# Cluster Server C
|
||||
|
||||
port: 4222
|
||||
|
||||
cluster {
|
||||
host: '0.0.0.0'
|
||||
port: 7244
|
||||
|
||||
routes = [
|
||||
nats-route://192.168.59.103:7244
|
||||
nats-route://192.168.59.104:7244
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Then start it:
|
||||
|
||||
```bash
|
||||
docker run -it -p 0.0.0.0:4222:4222 -p 0.0.0.0:7244:7244 --rm -v $(pwd)/conf/nats-server-C.conf:/tmp/cluster.conf nats -c /tmp/cluster.conf -p 9222 -D -V
|
||||
```
|
||||
|
||||
### Testing the Clusters
|
||||
|
||||
Now, the following should work: make a subscription to Node A then publish to Node C. You should be able to to receive the message without problems.
|
||||
|
||||
```bash
|
||||
nats-sub -s "nats://192.168.59.103:7222" hello &
|
||||
|
||||
nats-pub -s "nats://192.168.59.105:7222" hello world
|
||||
|
||||
[#1] Received on [hello] : 'world'
|
||||
|
||||
# nats-server on Node C logs:
|
||||
[1] 2015/06/23 05:20:31.100032 [TRC] 192.168.59.103:7244 - rid:2 - <<- [MSG hello RSID:8:2 5]
|
||||
|
||||
# nats-server on Node A logs:
|
||||
[1] 2015/06/23 05:20:31.100600 [TRC] 10.0.2.2:51007 - cid:8 - <<- [MSG hello 2 5]
|
||||
```
|
||||
|
||||
## Tutorial
|
||||
|
||||
See the [NATS Docker tutorial](https://github.com/nats-io/nats.docs/tree/51fc56e3090645f7cedb242415e2d5361e1807e7/nats_docker/tutorial.md) for more instructions on using the NATS server Docker image.
|
||||
|
||||
100
nats-server/nats_docker/docker_swarm.md
Normal file
100
nats-server/nats_docker/docker_swarm.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Docker Swarm
|
||||
|
||||
### Step 1:
|
||||
|
||||
Create an overlay network for the cluster \(in this example, `nats-cluster-example`\), and instantiate an initial NATS server.
|
||||
|
||||
First create an overlay network:
|
||||
|
||||
```bash
|
||||
% docker network create --driver overlay nats-cluster-example
|
||||
```
|
||||
|
||||
Next instantiate an initial "seed" server for a NATS cluster listening for other servers to join route to it on port 6222:
|
||||
|
||||
```bash
|
||||
% docker service create --network nats-cluster-example --name nats-cluster-node-1 nats:1.0.0 -cluster nats://0.0.0.0:6222 -DV
|
||||
```
|
||||
|
||||
### Step 2:
|
||||
|
||||
The 2nd step is to create another service which connects to the NATS server within the overlay network. Note that we connect to to the server at `nats-cluster-node-1`:
|
||||
|
||||
```bash
|
||||
% docker service create --name ruby-nats --network nats-cluster-example wallyqs/ruby-nats:ruby-2.3.1-nats-v0.8.0 -e '
|
||||
NATS.on_error do |e|
|
||||
puts "ERROR: #{e}"
|
||||
end
|
||||
NATS.start(:servers => ["nats://nats-cluster-node-1:4222"]) do |nc|
|
||||
inbox = NATS.create_inbox
|
||||
puts "[#{Time.now}] Connected to NATS at #{nc.connected_server}, inbox: #{inbox}"
|
||||
|
||||
nc.subscribe(inbox) do |msg, reply|
|
||||
puts "[#{Time.now}] Received reply - #{msg}"
|
||||
end
|
||||
|
||||
nc.subscribe("hello") do |msg, reply|
|
||||
next if reply == inbox
|
||||
puts "[#{Time.now}] Received greeting - #{msg} - #{reply}"
|
||||
nc.publish(reply, "world")
|
||||
end
|
||||
|
||||
EM.add_periodic_timer(1) do
|
||||
puts "[#{Time.now}] Saying hi (servers in pool: #{nc.server_pool}"
|
||||
nc.publish("hello", "hi", inbox)
|
||||
end
|
||||
end'
|
||||
```
|
||||
|
||||
### Step 3:
|
||||
|
||||
Now you can add more nodes to the Swarm cluster via more docker services, referencing the seed server in the `-routes` parameter:
|
||||
|
||||
```bash
|
||||
% docker service create --network nats-cluster-example --name nats-cluster-node-2 nats:1.0.0 -cluster nats://0.0.0.0:6222 -routes nats://nats-cluster-node-1:6222 -DV
|
||||
```
|
||||
|
||||
In this case, `nats-cluster-node-1` is seeding the rest of the cluster through the autodiscovery feature. Now NATS servers `nats-cluster-node-1` and `nats-cluster-node-2` are clustered together.
|
||||
|
||||
Add in more replicas of the subscriber:
|
||||
|
||||
```bash
|
||||
% docker service scale ruby-nats=3
|
||||
```
|
||||
|
||||
Then confirm the distribution on the Docker Swarm cluster:
|
||||
|
||||
```bash
|
||||
% docker service ps ruby-nats
|
||||
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR
|
||||
25skxso8honyhuznu15e4989m ruby-nats.1 wallyqs/ruby-nats:ruby-2.3.1-nats-v0.8.0 node-1 Running Running 2 minutes ago
|
||||
0017lut0u3wj153yvp0uxr8yo ruby-nats.2 wallyqs/ruby-nats:ruby-2.3.1-nats-v0.8.0 node-1 Running Running 2 minutes ago
|
||||
2sxl8rw6vm99x622efbdmkb96 ruby-nats.3 wallyqs/ruby-nats:ruby-2.3.1-nats-v0.8.0 node-2 Running Running 2 minutes ago
|
||||
```
|
||||
|
||||
The sample output after adding more NATS server nodes to the cluster, is below - and notice that the client is _dynamically_ aware of more nodes being part of the cluster via auto discovery!
|
||||
|
||||
```bash
|
||||
[2016-08-15 12:51:52 +0000] Saying hi (servers in pool: [{:uri=>#<URI::Generic nats://10.0.1.3:4222>, :was_connected=>true, :reconnect_attempts=>0}]
|
||||
[2016-08-15 12:51:53 +0000] Saying hi (servers in pool: [{:uri=>#<URI::Generic nats://10.0.1.3:4222>, :was_connected=>true, :reconnect_attempts=>0}]
|
||||
[2016-08-15 12:51:54 +0000] Saying hi (servers in pool: [{:uri=>#<URI::Generic nats://10.0.1.3:4222>, :was_connected=>true, :reconnect_attempts=>0}]
|
||||
[2016-08-15 12:51:55 +0000] Saying hi (servers in pool: [{:uri=>#<URI::Generic nats://10.0.1.3:4222>, :was_connected=>true, :reconnect_attempts=>0}, {:uri=>#<URI::Generic nats://10.0.1.7:4222>, :reconnect_attempts=>0}, {:uri=>#<URI::Generic nats://10.0.1.6:4222>, :reconnect_attempts=>0}]
|
||||
```
|
||||
|
||||
Sample output after adding more workers which can reply back \(since ignoring own responses\):
|
||||
|
||||
```bash
|
||||
[2016-08-15 16:06:26 +0000] Received reply - world
|
||||
[2016-08-15 16:06:26 +0000] Received reply - world
|
||||
[2016-08-15 16:06:27 +0000] Received greeting - hi - _INBOX.b8d8c01753d78e562e4dc561f1
|
||||
[2016-08-15 16:06:27 +0000] Received greeting - hi - _INBOX.4c35d18701979f8c8ed7e5f6ea
|
||||
```
|
||||
|
||||
## And so forth...
|
||||
|
||||
From here you can experiment adding to the NATS cluster by simply adding servers with new service names, that route to the seed server `nats-cluster-node-1`. As you've seen above, clients will automatically be updated to know that new servers are available in the cluster.
|
||||
|
||||
```bash
|
||||
% docker service create --network nats-cluster-example --name nats-cluster-node-3 nats:1.0.0 -cluster nats://0.0.0.0:6222 -routes nats://nats-cluster-node-1:6222 -DV
|
||||
```
|
||||
|
||||
60
nats-server/nats_docker/nats-docker-tutorial.md
Normal file
60
nats-server/nats_docker/nats-docker-tutorial.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Tutorial
|
||||
|
||||
In this tutorial you run the [NATS server Docker image](https://hub.docker.com/_/nats/). The Docker image provides an instance of the [NATS Server](../../). Synadia actively maintains and supports the nats-server Docker image. The NATS image is only 6 MB in size.
|
||||
|
||||
**1. Set up Docker.**
|
||||
|
||||
See [Get Started with Docker](http://docs.docker.com/mac/started/) for guidance.
|
||||
|
||||
The easiest way to run Docker is to use the [Docker Toolbox](http://docs.docker.com/mac/step_one/).
|
||||
|
||||
**2. Run the nats-server Docker image.**
|
||||
|
||||
```bash
|
||||
> docker run -p 4222:4222 -p 8222:8222 -p 6222:6222 --name nats-server -ti nats:latest
|
||||
```
|
||||
|
||||
**3. Verify that the NATS server is running.**
|
||||
|
||||
You should see the following:
|
||||
|
||||
```bash
|
||||
Unable to find image 'nats:latest' locally
|
||||
latest: Pulling from library/nats
|
||||
2d3d00b0941f: Pull complete
|
||||
24bc6bd33ea7: Pull complete
|
||||
Digest: sha256:47b825feb34e545317c4ad122bd1a752a3172bbbc72104fc7fb5e57cf90f79e4
|
||||
Status: Downloaded newer image for nats:latest
|
||||
```
|
||||
|
||||
Followed by this, indicating that the NATS server is running:
|
||||
|
||||
```bash
|
||||
[1] 2019/06/01 18:34:19.605144 [INF] Starting nats-server version 2.0.0
|
||||
[1] 2019/06/01 18:34:19.605191 [INF] Starting http monitor on 0.0.0.0:8222
|
||||
[1] 2019/06/01 18:34:19.605286 [INF] Listening for client connections on 0.0.0.0:4222
|
||||
[1] 2019/06/01 18:34:19.605312 [INF] Server is ready
|
||||
[1] 2019/06/01 18:34:19.608756 [INF] Listening for route connections on 0.0.0.0:6222
|
||||
```
|
||||
|
||||
Notice how quickly the NATS server Docker image downloads. It is a mere 6 MB in size.
|
||||
|
||||
**4. Test the NATS server to verify it is running.**
|
||||
|
||||
An easy way to test the client connection port is through using telnet.
|
||||
|
||||
```bash
|
||||
> telnet localhost 4222
|
||||
```
|
||||
|
||||
Expected result:
|
||||
|
||||
```bash
|
||||
Trying ::1...
|
||||
Connected to localhost.
|
||||
Escape character is '^]'.
|
||||
INFO {"server_id":"NDP7NP2P2KADDDUUBUDG6VSSWKCW4IC5BQHAYVMLVAJEGZITE5XP7O5J","version":"2.0.0","proto":1,"go":"go1.11.10","host":"0.0.0.0","port":4222,"max_payload":1048576,"client_id":13249}
|
||||
```
|
||||
|
||||
You can also test the monitoring endpoint, viewing `http://localhost:8222` with a browser.
|
||||
|
||||
Reference in New Issue
Block a user