Install Apache CouchDB on CentOS 7 – Step-by-Step Guide

Apache CouchDB is a NoSQL database server that's open-source and free to use. It keeps data in databases formatted as JSON documents and includes a RESTful HTTP interface to easily perform operations like creating, updating, viewing, and deleting documents.

Step-by-Step Setup of Apache CouchDB on CentOS 7

This tutorial will guide you through the process of installing and setting up Apache CouchDB on a server running CentOS 7.

Requirements

• Deploy a CentOS 7 server.
• Log in to the deployed server instance.
• Ensure your system is updated.

Configure the CouchDB Software Repository

1. Install the EPEL Package Repository

Begin by installing the EPEL repository required by CouchDB:

$ sudo yum install epel-release

2. Create a CouchDB Repository File

Open a new repository file for CouchDB using:

$ sudo nano /etc/yum.repos.d/apache-couchdb.repo

Insert the following repository configuration into the file:

[Apache-Couchdb]
name=couchdb
baseurl=https://apache.jfrog.io/artifactory/couchdb-rpm/el$releasever/$basearch/
gpgkey=https://couchdb.apache.org/repo/keys.asc https://couchdb.apache.org/repo/rpm-package-key.asc
gpgcheck=1
repo_gpgcheck=1
enabled=1

Install CouchDB

Once the repository is ready, proceed with installing CouchDB on the server:

$ sudo yum install couchdb

Enable and Start CouchDB Service

1. Enable CouchDB on System Boot

To make sure CouchDB launches automatically at system startup, run:

$ sudo systemctl enable couchdb

2. Start the CouchDB Service

Finally, activate CouchDB with this command:

$ sudo systemctl start couchdb

Configure CouchDB Settings on CentOS 7

All CouchDB configuration and data reside in the /opt/couchdb directory. The main configuration file is local.ini, located in the /opt/couchdb/etc/ path. To begin the setup, bind CouchDB to a network interface and establish an administrative account.

1. Modify CouchDB Bind Address

Open the local.ini configuration file using the following command:

$ sudo nano /opt/couchdb/local.ini

Find the line that specifies bind_address =. By default, it's set to 127.0.0.1. You can update this to 0.0.0.0 to allow access from any network interface or to your public IP address if you prefer global exposure.

[chttpd]
;port = 5984
bind_address = 127.0.0.1

2. Create an Admin User

Scroll to the bottom or search for the [admins] section. Add your admin credentials in the format username = password. It’s advised to replace "admin" with a stronger username to enhance security.

[admins]
admin = YOUR-PASSWORD

3. Enable Single Node Mode

Also, insert the following under the [couchdb] section to enable single-node operation, allowing CouchDB to generate the system databases at startup.

[couchdb]
single_node=true

After making changes, save and close the file.

4. Optionally Create System Databases Manually

If you prefer manual creation, run the following commands to set up the required system databases: _users, _replicator, and _global_changes.

$ curl -u Username:Password -X PUT http://127.0.0.1:5984/_users
$ curl -u Username:Password -X PUT http://127.0.0.1:5984/_replicator
$ curl -u Username:Password -X PUT http://127.0.0.1:5984/_global_changes

5. Apply Configuration Changes

Restart the CouchDB service to apply the newly made configurations:

$ sudo systemctl restart couchdb

Configure the Firewall to Allow CouchDB Access

1. Permit HTTP Traffic

To allow web traffic to access CouchDB, run:

$ sudo firewall-cmd --permanent --zone=public --add-service=http

2. Permit HTTPS Traffic (Optional)

If SSL is configured on your server, allow secure HTTPS connections:

$ sudo firewall-cmd --permanent --zone=public --add-service=https

3. Open CouchDB Port

Enable port 5984, which is used by CouchDB:

$ sudo firewall-cmd --permanent --zone=public --add-port=5984/tcp

4. Reload the Firewall

To apply the updated firewall rules, reload the service:

$ sudo systemctl reload firewalld

Verify Your CouchDB Setup

To confirm that CouchDB is installed correctly, execute the following curl command from your terminal:

$ curl 127.0.0.1:5984

The response should resemble this JSON output:

{"couchdb":"Welcome","version":"3.2.1","git_sha":"244d428af","uuid":"99b896bf19b5b076970e12574b9b9ff8","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

Conclusion

You have now completed the installation and configuration of Apache CouchDB on a CentOS 7 system. For additional guidance and in-depth features, refer to the official CouchDB documentation.