How to Install Apache CouchDB on CentOS/RHEL 8

CouchDB is an open-source, document-oriented NoSQL database. In this article, you will learn how to install Apache CouchDB on CentOS / RHEL 8.

 

Table of Contents:

• What is Apache CouchDB?
• Environment Specification
• Updating Linux Software Packages
• Installing EPEL Yum Repository
• Installing CouchDB Yum Repository
• Installing Apache CouchDB on CentOS / RHEL 8
• Accessing CouchDB Web UI
• Conclusion

 

What is Apache CouchDB? :

CouchDB is an open-source database management system, developed by Apache Software Foundation. It is a NoSQL document-store database developed in ErLang.

CouchDB database uses multiple formats and protocols to store, transfer, and process its data, it uses JSON (JavaScript Object Notation) to store data, JavaScript as its query language using MapReduce, and HTTP for an API.

Unlike a relational database, a NoSQL database does not store data and relationships in tables. Instead, each database is a collection of independent documents. Each document maintains its own data and self-contained schema.

CouchDB software includes a native web interface i.e. Fauxton for administration of NoSQL database server.

Environment Specification:

We are using a minimal installed CentOS 8 virtual machine with following specification.

• CPU - 3.4 Ghz (2 cores)
• Memory - 2 GB
• Storage - 20 GB
• Operating System - CentOS Linux 8.2
• Hostname – couchdb-01.centlinux.com
• IP Address - 192.168.116.206 /24

 

Updating Linux Software Packages:

Connect with couchdb-01.centlinux.com as root user by using a ssh client.

It is a best practice to update installed software packages before installing anything new on Linux operating system.

Execute dnf command to update installed software packages in your Linux operating system.

# dnf -y update

After updating software packages, verify the new Kernel version.

# uname -r
4.18.0-193.6.3.el8_2.x86_64

 

Installing EPEL Yum Repository:

CouchDB database server requires some packages that are not available in standard yum repositories, therefore, you have to install EPEL (Extra Packages for Enterprise Linux) yum repository on your Linux server.

# dnf install -y epel-release

 

Installing CouchDB Yum Repository:

CouchDB database can be install on Linux from source or RPM packages. The RPM based installation is simple and straight forward, therefore we suggest that you should install this NoSQL database software from RPM packages.

Free RPM packages are distributed through their own official yum repository. Therefore, you need to install CouchDB yum repository in your Linux operating system.

Create a repo file by using vim text editor.

# vi /etc/yum.repos.d/bintray-apache-couchdb-rpm.repo

And add following directives in this file.

[bintray--apache-couchdb-rpm]
name=bintray--apache-couchdb-rpm
baseurl=http://apache.bintray.com/couchdb-rpm/el$releasever/$basearch/
gpgcheck=0
repo_gpgcheck=0
enabled=1

Build cache for newly installed yum repositories.

# dnf makecache
CentOS-8 - AppStream                            2.7 kB/s | 4.3 kB     00:01
CentOS-8 - Base                                 1.4 kB/s | 3.9 kB     00:02
CentOS-8 - Extras                               1.4 kB/s | 1.5 kB     00:01
bintray--apache-couchdb-rpm                     489  B/s | 1.3 kB     00:02
Extra Packages for Enterprise Linux Modular 8 -  12 kB/s | 117 kB     00:10
Extra Packages for Enterprise Linux 8 - x86_64  215 kB/s | 7.9 MB     00:37
Metadata cache created.

 

Installing Apache CouchDB on CentOS / RHEL 8:

You have set up the required yum repositories. Now you can install CouchDB software by using dnf command.

# dnf install -y couchdb

NoSQL database software is installed in /opt/couchdb directory.

Edit CouchDB configuration file by using vim text editor.

# vi /opt/couchdb/etc/local.ini

Create an admin user and set a strong password for it. You have to locate the [admins] section and then add a admin user under this section. You can add as many admin users as you like here.

[admins]
admin = Str0ngP@ssw0rd

Don't worry about the password in plain text, because the CouchDB will automatically convert it to a hash at the time of service startup.

By default, CouchDB runs its Web UI (i.e. Fauxton) at the localhost interface only. But to access it from the network, you need to run it on other network interfaces as well.

Locate [chttpd] section and set following directives therein.

[chttpd]
port = 5984
bind_address = 0.0.0.0

Enable and start CouchDB service.

# systemctl enable --now couchdb.service
Created symlink /etc/systemd/system/multi-user.target.wants/couchdb.service â /usr/lib/systemd/system/couchdb.service.

CouchDB service uses default port 5984/tcp. Therefore, you need to allow incoming traffic to this port from the network.

Execute firewall-cmd command to allow port 5984/tcp in Linux firewall.

# firewall-cmd --permanent --add-port=5984/tcp
success
# firewall-cmd --reload
success

 

Accessing Fauxton Web UI:

After successful startup of CouchDB service, you can now access the Fauxton web interface by opening the URL http://couchdb-01.centlinux.com:5984/_utils#setup in a web browser.

You will be redirected to the login page. You can use an admin user (that we have added in local.ini file) to login to Fauxton.

After login, the setup will ask you to configure CouchDB server as a single-node instance or set up a cluster. Click on "Configure as Single Node".

Provide the admin user credentials, bind IP address and the service port. Click on "Configure Node".

At the end of setup, it will ask you to configure replication. Ignore it and click on the Databases button at left sidebar.

You are now at the databases page. You can create your required databases from this page.

In the above screenshot, you can see the two system databases that are created during setup process and two user databases that are created by us for testing purpose.

Besides Fauxton web interface, you can also send HTTP commands to CouchDB instance by using curl command.

To create a CouchDB database, you can execute following command at Linux bash prompt.

# curl -u admin:Str0ngP@ssw0rd -X PUT http://127.0.0.1:5984/prod
{"ok":true}

To list all the databases on your CouchDB server, you can send following command.

# curl -u admin:Str0ngP@ssw0rd -X GET http://127.0.0.1:5984/_all_dbs
["_replicator","_users","prod","test"]

 

Conclusion:

We have successfully installed Apache CouchDB on CentOS / RHEL 8. To understand basics and architecture of CouchDB database, we recommend that you should buy and read CouchDB: The Definitive Guide: Time to Relax by O'Reilly Media.