How to deploy CouchDB as a cluster with Docker

Recently, I showed you how to deploy CouchDB as a standalone NoSQL database server, which could serve you well in small instances. This time around, I want to show you a neat trick for deploying CouchDB as a cluster using Docker. Although this method might not be ideal for production usage, it’s a great way for developers to be able to work with CouchDB in a test environment.

Without further ado, let’s get to the deployment.

SEE: Hiring kit: Back-end Developer (TechRepublic Premium)

What you’ll need

To make this work, you’ll need a server with an OS that supports Docker. I’ll demonstrate with Ubuntu Server 22.04, but you can use whichever platform you’re comfortable with.

How to install Docker

On the off-chance you don’t already have Docker installed, here’s how you do it.

First, add the official Docker GPG key with the command:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Next, add the required repository:

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install the required dependencies with:

sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release -y

Finally, we can install the latest version of the Docker engine:

sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io -y

Add your user to the docker group with the command:

sudo usermod -aG docker $USER

Make the system aware of the change with:

newgrp docker

How to deploy the CouchDB containers

We’re going to deploy three CouchDB containers, each using a unique external port. The first will use port 5984 and is deployed with:

docker run -itd -p 5984:5984 -p 5986:5986 --name=couchdb0 -e NODENAME='couchdb-0.local.com' --mount 'source=volume-0,target=/opt/couchdb/data' couchdb:2.3.0

The second container is deployed (using port 15984) with:

docker run -itd -p 15984:5984 -p 15986:5986 --name=couchdb1 -e  NODENAME='couchdb-1.local.com' --mount 'source=volume-1,target=/opt/couchdb/data' couchdb:2.3.0

The final container is deployed *using port 25984) with:

docker run -itd -p 25984:5984 -p 25986:5986 --name=couchdb2 -e NODENAME='couchdb-2.local.com' --mount 'source=volume-2,target=/opt/couchdb/data' couchdb:2.3.0

If you issue the command docker ps -a | grep couchdb you should see all three instances up and running.

How to create the administrator user

We now need to create an administrator on each container. In each instance, replace PASSWORD with a strong password (make sure it’s the same for each). The commands for this will be:

curl -X PUT http://localhost:5984/_node/[email protected]/_config/admins/admin -d '"PASSWORD"
curl -X PUT http://localhost:15984/_node/[email protected]/_config/admins/admin -d '"PASSWORD"
curl -X PUT http://localhost:25984/_node/[email protected]/_config/admins/admin -d '"PASSWORD"''

Outstanding. Let’s continue.

How to create a Docker network

At the moment, the CouchDB nodes have no awareness of one another. To fix that we need to create a new Docker network. Do this with:

docker network create -d bridge --subnet 172.25.0.0/16 isolated_nw

With our network created, we now have to connect our containers to it, which is done using the following commands:

docker network connect --alias couchdb-0.local.com isolated_nw couchdb0
docker network connect --alias couchdb-1.local.com isolated_nw couchdb1
docker network connect --alias couchdb-2.local.com isolated_nw couchdb2

Perfect.

How to log into the admin console

Open a web browser and point it to http://server:5984, where SERVER is the IP address of the server hosting Docker. Log in with the username admin and the password you added for the admin user earlier.

Once you’ve logged in, click the wrench icon in the left navigation and then click Configure a Cluster (Figure A).

Figure A

In the resulting window (Figure B), you’ll need to fill in the admin credentials and then add a node to the cluster.

Figure B

To add the first node to the cluster, you’ll type couchdb-1.local.com as the Remote Host and leave the port at 5984. Once you’ve done that, click Add Node. Do the same thing for the second node using couchdb-2.local.com as the Remote Host.

After adding both nodes, click Configure Cluster and you should be rewarded with a page informing you the cluster has been configured (Figure C).

Figure C

Congratulations, you’ve just deployed your first CouchDB cluster, with the help of Docker.

Subscribe to TechRepublic’s How To Make Tech Work on YouTube for all the latest tech advice for business pros from Jack Wallen.