Deploying a Multi-node Cluster with Docker

There are two popular topologies for Couchbase Server multi-node clusters: all Couchbase Server containers on one physical machine and each Couchbase Server container on its own machine.

All Couchbase Server containers on one physical machine - This model is commonly used for scale-minimized deployments simulating production deployments for development and test purposes.

Each Couchbase Server container on its own machine - This model is commonly used for production deployments. This is the only supported topology in production with Couchbase Server version 4.5 and higher.

Deploying Multiple Couchbase Server Containers on One Physical Machine

In this deployment model all containers are placed on the same physical node. Placing all containers on a single physical machine means all containers will compete for the same resources. That is okay for test systems, however it isn’t recommended for applications sensitive to performance.

In this example, we’ll sets up a 3 node Couchbase Server cluster with all Couchbase Server containers running on one physical machine.

Start the Couchbase Server containers, db1, db2 and db3, using the following command:

docker run -d --name db1 couchbase
docker run -d --name db2 couchbase
docker run -d --name db3 -p 8091-8094:8091-8094 -p 11210:11210 couchbase

These commands download and run 3 Couchbase containers tagged "latest" from the Couchbase repo on Docker Hub.

If you are using encrypted communication for Web Console, client and server, and using XDCR, you need to open up additional ports. For details, see Network Configuration.

Check the Docker logs to verify that the containers have started:

docker logs db1
docker logs db2
docker logs db3

If the containers have started, all the above commands should return the following output:

Starting Couchbase Server -- Web UI available at http://<ip>:8091

If Couchbase Server is running locally on the machine without containers, the port mappings above under the -p option may fail. Ensure that you stop your local instance of Couchbase Server before running the above command.

Run docker inspect to discover the local IP addresses for each container. You will need the IP addresses for db1 and db2 to set up the 3 node Couchbase Server cluster. The initial cluster setup will automatically pick up the IP address for db3.
```
docker inspect --format '{{ .NetworkSettings.IPAddress }}' db1
docker inspect --format '{{ .NetworkSettings.IPAddress }}' db2
```
From the browser, access the Web Console using http://localhost:8091. You are now connected to container named db3. If the container is up and running, you will see the Couchbase Server Setup Screen.
Walk through the Setup wizard and accept the default values.

You may need to lower the RAM allocated to various services to fit within the bounds of the resource for the containers. Enable the travel-sample and beer-sample buckets to load some sample data.

For detailed information on configuring the server, see Initializing the Cluster
Next, we need to add the db1 and db2 containers to the cluster.
1. On the Web Console, go to the Server Nodes tab and click Add Server and specify the IP address you captured for db1.
2. Click Add Server again and specify the IP address you captured for db2
3. Click Rebalance.

This is all that is needed for a multi-node Couchbase Server cluster deployment using a single physical machine.

Running a N1QL Query

Open the Web Console at http://localhost:8091 and switch to the Query tab. Run the following N1QL query:

SELECT name FROM `beer-sample` WHERE  brewery_id ="mishawaka_brewing";

To run a query from command line query tool:

Run the interactive shell on the container:
```
bash -c "clear && docker exec -it db1 sh"
```
Navigate to the bin directory:
```
# cd /opt/couchbase/bin
```
Run the cbq command line tool:
```
# ./cbq
```

Execute a N1QL query on the beer-sample bucket:

cbq> SELECT name FROM `beer-sample` WHERE  brewery_id ="mishawaka_brewing";

For more query samples, see Running Your First N1QL Query.

Connect via SDK

Couchbase Server SDKs communicate with Couchbase Server services over various ports using the name that is used to register each node in the Server Nodes tab. Given each node is registered using the local IP address, applications using the SDK need to be within the private IP network the Couchbase Server containers are in. You can do this by running your application in another container on the same physical machine.

For more information about deploying a sample application, click here.

Deploying Couchbase Server Containers across Many Physical Machines

In this deployment model each container is placed on its own physical machine. This is the supported model for production deployments with Couchbase Server containers.

In this example, we’ll set up a 3 nodes Couchbase Server cluster, with each Couchbase Server container running on its own physical machine.

On all 3 physical hosts, start the Couchbase Server container, db, using the following command:
```
docker run -d --name db -v ~/couchbase:/opt/couchbase/var --net=host couchbase
```
This command downloads and runs Couchbase container tagged "latest" from the Couchbase repo on Docker Hub. The docker run -v option is recommended for better IO performance and persists the data stored by Couchbase on the local host. The --net=host option provides better network performance and maps the host network stack to the container.

Check the Docker logs on each host to verify that the containers have started:
```
docker logs db
```
If the containers have started, the command should return the following output:
```
Starting Couchbase Server -- Web UI available at http://<ip>:8091
```
On all 3 physical hosts, run the command docker inspect to discover the local IP addresses for each container. You will need the IP addresses for each container on all the nodes in the Couchbase Server cluster.
```
docker inspect --format '{{ .NetworkSettings.IPAddress }}' db
```
On one of the physical hosts, access the Web Console from the browser using http://node-ip:8091. If the container is up and running, you will see the Couchbase Server Setup Screen.

Click Setup, select the Start a new cluster option, and walk through the Setup wizard . For detailed information on configuring the server, see Initializing the Cluster
On the remaining physical hosts, access the Web Console from the browse using http://node-ip:8091. If the container is up and running, you will see the Couchbase Server Setup Screen on each node.

Click Setup, select the Join a cluster option, and walk through the Setup wizard.
On the last physical host, after you join the cluster, switch to the Server Nodes tab and click Rebalance.

This all that is needed for a multi-node Couchbase Server cluster deployment across multiple physical machines.

Running A N1QL Query on the Cluster

Open the Web Console at http://node-ip:8091 and switch to the Query tab. Run the following N1QL query:

SELECT name FROM `beer-sample` WHERE  brewery_id ="mishawaka_brewing";

To run a query from command line query tool:

Run the interactive shell on the container:
```
bash -c "clear && docker exec -it db sh"
```
Navigate to the bin directory:
```
# cd /opt/couchbase/bin
```
Run the cbq command line tool:
```
# ./cbq
```

Execute a N1QL query on the beer-sample bucket:

cbq> SELECT name FROM `beer-sample` WHERE  brewery_id ="mishawaka_brewing";

For more query samples, see Running Your First N1QL Query.

Connect via SDK

The SDKs communicate with Couchbase Server services over various ports using the name that is used to register each node in the Server Nodes tab. Given each node is registered using the IP address of the hosts, applications using the SDK can be run from any host that can reach the nodes of the cluster.

For more information about deploying a sample application, click here.