How to Setup CouchDB Replication on Ubuntu 16.04

In today's article, we will set up CouchDB replication on Ubuntu 16.04. CouchDB is NoSQL database much similar to cassandra. Rather than Cassandra's Java, CouchDB is written Erlang and it is Apache Software Foundation project since 2008. This database is document-oriented, not unlike MongoDB. For this tutorial, you need two nodes running Ubuntu 16.04 Server. I will use KVM instances in my laptop, you can use either VM or physical machines. So lets start.

Installing and CouchDB on Ubuntu node

Lets first update sources list

sudo apt update

Next we install package software-properties-common which enables us to add PPA repositories. It is maybe included by default, but if it is not, you need to run this command

sudo apt install software-properties-common

Next we add repository for couchdb from where we will install the database software

sudo add-apt-repository ppa:couchdb/stable

Then we can install couchdb with simple command:

sudo apt-get install couchdb

After this command is executed, couchdb is installed and we will run on port 5984 do we can use curl to get info about the database

curl localhost:5984

As we see, it runs already.

How to create and delete database

Couchdb is manipulated through http requests. When you want something done, you make a request on localhost on default port the CouchDB runs on.  That is port 5984. For security reasons, you can only do this on localhost, on the machine where couchdb is running.

Lets add the database:

miki@ubuntu-1:~$ curl -X PUT localhost:5984/new_database

Lets now list all the databases on the system:

miki@ubuntu-1:~$ curl -X GET

The first two are there by default, the new_database is what we created. Lets then delete it. Deletion of databases is done with following command

miki@ubuntu-1:~$ curl -X DELETE

Now running the second command again

miki@ubuntu-1:~$ curl -X GET

We see that the new_database is missing, as we deleted it.

Futon - the CouchDB GUI

If you visit http://localhost:5984/_utils with your browser, you will find the Futon. Futon is CouchDB GUI front end. But as mentioned, CouchDB for security reasons only enables administering from localhost, which means from the server you installed CouchDB. You can not type IP address of the server instead of localhost. So if you want to administer your server from your laptop, we would need to use a little trick. We would need to make ssh tunnel to the server, making mini VPN and making your server think that request is coming from localhost. To do that, on your local computer, type following command:

miki@ThinkPad-X220T:~$ ssh -L5984: miki@

This will create the tunnel that we need, and next you can fire up your browser and navigate to http://localhost:5984/_utils/index.html

It will give you the user interface similar to this


As we are going to replicate a database in next chapter, we need to set our destination database to accept replica from locations other than localhost. This can be set in bind_address parameter in configuration page of Futon. It needs to be set to to listen on all ip rather than only localhost. Something like this:


You can do this on both of your nodes (you would need to create new ssh tunnel for another nodes) but generally only target where replica is made needs to listen on all IP addresses. The source can continue listening only to localhost.

Replicating a database locally

Replicating a database is, like everything else in CoucdDB, also done by HTTP request.You need to specify the source and the destination database. Destination can be local or remote database. Since we already set ubuntu-1 listen to all ip, lets create a db which we will replicate on ubuntu-2 host.

miki@ubuntu-2:~$ curl -X PUT localhost:5984/db-replica

Now lets see how we can replicate this database locally. On the same server

curl -H 'Content-Type: application/json' -X POST http://localhost:5984/_replicate -d ' {"source": "http://localhost:5984/db-replica", "target": "http://localhost:5984/foo", "create_target": true, "continuous": true} '

This command should  create a database foo on local host, and as source should take database db-replica that we already created earlier. We enabled also the option continuous, which means that database will be periodically synced when you make any changes source database, which in this case is db-replica. After running this command lets check for all available databases

miki@ubuntu-2:~$ curl -X GET localhost:5984/_all_dbs


The foo database have been created.

Remote replication

Let's try now to do it remotely, our source is again db-replica on ubuntu-2 server, and our target will be remote on our ubuntu-1 server. It will create new database if not present (create_target parameter) and it will sync the replica continuously for all changes as they happen.

miki@ubuntu-2:~$ curl -H 'Content-Type: application/json' -X POST http://localhost:5984/_replicate -d ' {"source": "http://localhost:5984/db-replica", "target": "", "create_target": true, "continuous": true} '

Lets check the dbs in ubuntu-1 server

miki@ubuntu-1:~$ curl -X GET localhost:5984/_all_dbs

We can see that how remote replication works. In case you want just one-off replication, you would need to change continuous parameter to false or just simply omit it. If you want to see couchDB logs, you can find it in /var/log/couchdb/couch.log directory. You would need sudo or root privileges to access it, and if you want to watch logs interactively, this command will do it

sudo tail -f /var/log/couchdb/couch.log


We have gone through basic commands and usage of CouchDB. Creation of new database, deletion, replication locally or over network are all done by HTTP requests and can be coded to your app. Checking logs is done by normal tail -f command, and when GUI is needed, we have Futon, which is intuitive enough to help you do all the tasks that you don't feel comfortable enough for doing in command line. That is all for this article, thank you for reading and good day.

Leave a Comment