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:
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:firstname.lastname@example.org/_config/admins/admin -d '"PASSWORD"
curl -X PUT http://localhost:email@example.com/_config/admins/admin -d '"PASSWORD"
curl -X PUT http://localhost:firstname.lastname@example.org/_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
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).
In the resulting window (Figure B), you’ll need to fill in the admin credentials and then add a node to the cluster.
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).
Congratulations, you’ve just deployed your first CouchDB cluster, with the help of Docker.
Master Docker with the following resources from TechRepublic Academy:
Subscribe to TechRepublic’s How To Make Tech Work on YouTube for all the latest tech advice for business pros from Jack Wallen.
Subscribe to the Developer Insider Newsletter
From the hottest programming languages to commentary on the Linux OS, get the developer and open source news and tips you need to know. Delivered Tuesdays and Thursdays