Setting Up A Couchbase Cluster In 10 Minutes With Docker And Docker Compose

Today a tutorial on how to setup a Couchbase cluster on your local machine using Docker.

We often describe Docker as a lightweight solution for isolating your production processes. But sometimes we may forget to say how easy it is to use Docker for setting up your development environment.

Recently I developed a Couchbase adapter and I had to test failure scenarios among which a node failover and a disaster recovery scenario.
In our production environment, we installed 2 Couchbase clusters of 3 nodes each (3 nodes is the minimum for having the auto-failover mode enabled).

I wanted to test my adapter on my development environment but I let you imagine how heavy it would be to install manually 6 nodes considering especially that Couchbase manages many ports for administration and clustering. I would have configured manually each server node to prevent port collisions.

Because Docker provides environment isolation, let’s see how easy it is to create and configure the following Couchbase cluster with 3 nodes and one port mapped on your local machine exposing the admin console:


To instantiate the three Docker nodes, run the following commands:

$docker run -d -v ~/couchbase/node1:/opt/couchbase/var couchbase:3.1.0
$docker run -d -v ~/couchbase/node2:/opt/couchbase/var couchbase:3.1.0
$docker run -d -v ~/couchbase/node3:/opt/couchbase/var -p 8091:8091 couchbase:3.1.0

Each command starts a new Docker instance (the -v option allows to create a volume for persisting the Couchbase node data).

The last command maps the admin console port on your local machine.

The next step is to retrieve the internal container IP address of the node3.
Execute the command hereunder by replacing <node3_docker_id> by the node3 container id:

$docker inspect --format '{{ .NetworkSettings.IPAddress }}' <node3_docker_id>

Connect to your local admin console (http://localhost:8091), follow the setup steps and enter the previously retrieved IP in the hostname field.

The last step is to add node1 and node2 in the cluster. Retrieve their internal IP with:

$docker inspect --format '{{ .NetworkSettings.IPAddress }}' <node1_docker_id>
$docker inspect --format '{{ .NetworkSettings.IPAddress }}' <node2_docker_id>

In the admin console, go in Server Nodes menu and click on Add Servers button. Add the node1 and node2 internal IP addresses.

That’s it! Your Couchbase cluster is configured. If you want to create another cluster for testing Couchbase XDCR mechanism, for example, you just have to repeat these operations (don’t forget though to map the admin console port on another one).

Now, what if you want to have the capability to instantiate this cluster on the fly, during an automated testing process for instance?
There is nothing easier! Let’s use Docker Compose, a simple but powerful tool to define and run multi-container applications.

Create a docker-compose.yml file with the following content:

version: '2'
      image: couchbase:3.1.0
        - "~/couchbase/node1:/opt/couchbase/var"
      image: couchbase:3.1.0
        - "~/couchbase/node2:/opt/couchbase/var"
      image: couchbase:3.1.0
        - "~/couchbase/node3:/opt/couchbase/var"
        - "8091:8191"

In this file, we are simply reusing the information on the Couchbase cluster configuration in a Docker Compose file format.

Start your Couchbase cluster with:

$docker-compose up

This command starts automatically each node and lets Couchbase setting up the cluster based on the configuration you previously made in the admin console.

<3 Couchbase

<3 Docker