How to Install Apache CouchDB NoSQL Database Server on Debian 11

Apache CouchDB is an open-source NoSQL database developed by the Apache Software Foundation. Each database is a collection of documents in JSON format. Each document consists of a number of fields and attachments. It comes with a restful API that allows you to create, edit, and delete database documents. It supports two modes - standalone and clustered. If you are using it on a single server, you can use the standalone mode. Clustered mode helps if you are using more than one server.

This tutorial will teach you how to install Apache CouchDB Database Server on a Debian 11 server. You will also learn how to perform some basic database operations and access CouchDB via a public URL using the Caddy web server.

Prerequisites

  • A server running Debian 11.

  • Sudo package is installed.

    $ apt install sudo
    
  • A non-root user with sudo privileges.

  • Everything is updated.

    $ sudo apt update && sudo apt upgrade
    
  • A fully qualified domain name (FQDN), like, couchdb.example.com to access CouchDB over a public URL with HTTPS.

Step 1 - Install Utilities

Before proceeding ahead with the installation, we need to install some tools that will be required for the tutorial. Run the following command to install them.

$ sudo apt install -y curl apt-transport-https gnupg nano lsb-release 

Step 2 - Add CouchDB repository

The first step is to import the CouchDB's GPG key. Run the following command to import the key.

$ curl https://couchdb.apache.org/repo/keys.asc | gpg --dearmor | sudo tee /usr/share/keyrings/couchdb-archive-keyring.gpg >/dev/null 2>&1

Add the CouchDB's repository to the system repository list.

$ echo "deb [signed-by=/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ `lsb_release -cs` main" \
    | sudo tee /etc/apt/sources.list.d/couchdb.list >/dev/null

Update the system repository list.

$ sudo apt update

Step 3 - Install CouchDB

Run the following command to install CouchDB.

$ sudo apt install couchdb -y

CouchDB installer will automatically prompt you to configure basic settings. In the first step, it will ask you if you want to use it in a single server setup or multiple nodes. Since we are installing it on a single server, keep the option selected and press Enter to continue.

CouchDB Server Configuration Type

Next, you will be asked to set a cookie name. Choose any name you want.

CouchDB Erlang Cookie Setup

Next, you will be asked to set up a binding address for CouchDB's service. Since, we are installing it on a server and will need to access it via a UI control panel, set 0.0.0.0 as the binding address. If you are planning to limit access to the CouchDB server to an IP address, then use that.

CouchDB Binding Address Setup

Next, you will be asked to create an administrator password for its default admin account.

CouchDB Admin Password Setup

You will be asked to verify the password again.

CouchDB Password Verification prompt

Press Enter to complete the installation process.

Step 4 - Verify CouchDB Install

To verify if the installation was successful, run the following command.

$ curl http://127.0.0.1:5984/

It will return a JSON formatted output with information about CouchDB.

{"couchdb":"Welcome","version":"3.2.2","git_sha":"d5b746b7c","uuid":"7a20b1eadd803f1c0d77fb9617c7f3de","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

The shell output is unformatted. Here is how it looks on formatting.

{
   "couchdb":"Welcome",
   "version":"3.2.2",
   "git_sha":"d5b746b7c",
   "uuid":"7a20b1eadd803f1c0d77fb9617c7f3de",
   "features":[
      "access-ready",
      "partitioned",
      "pluggable-storage-engines",
      "reshard",
      "scheduler"
   ],
   "vendor":{
      "name":"The Apache Software Foundation"
   }
}

You can also access it via the web by visiting the URL http://<yourserverIP>:5984/. But before we do that, we need to open the port in our firewall. Assuming you are using Uncomplicated Firewall(ufw), run the following command to open the port.

$ sudo ufw allow 5984/tcp

Open the URL http://<yourserverIP>:5984 in your browser. You will see the following screen. The following output was captured on Firefox. In other browsers, you will simply see the raw output which you got in your terminal.

CouchDB WebPage in Firefox

Step 5 - Access CouchDB

CouchDB ships with a web-based GUI called Fauxton to manage and create databases. You can access it via the URL http://<yourserverIP>:5984/_utils/. Launch the URL in your favorite browser and you will see the following login screen.

CouchDB Login Screen

Enter admin as your username and the password created before. Press the Log in button to continue. Next, you will be taken to the CouchDB dashboard.

CouchDB Dashboard

Here, you will see two databases that were created during installation. The _users database as expected handles information for the users of the CouchDB platform and the _replicator database holds information about any replication databases or operations.

You will also see a sidebar with all sorts of options that you can use with CouchDB.

Step 6 - Basic Database Operations using CouchDB Interface

CouchDB's Fauxton interface allows us to perform basic CRUD operations (create, read, update, and delete). Let us start with creating a new database.

Create Database

To create a new database, click the Create Database link on the main screen. It will open up the following pop-up.

CouchDB Create Database popup

Enter the name of the database you want to create and click the Create button.

This will create a new database and open up the following screen.

CouchDB Database dashboard

Create Document

Now that we have a database, let us create a document in it. Click the Create Document button to get started. You will get the following new document screen pre-filled with a JSON object and an _id with a Globally Unique Identifier (GUID).

CouchDB New Document window

Let us add some data by adding some more fields in the following manner. If you want to change the value of the _id field, you can but only before creating the document. You cannot change its value after the document has been created. You can edit other fields at any time though.

{
  "_id": "0b4ad0d607479c09bb9121b146007363",
  "Name": "Navjot Singh",
  "role": "writer",
  "skills": "linux"
}

CouchDB New Document Data

Click the Create Document button when you are finished adding the fields to save the new document. You will be returned to the following All Documents page.

CouchDB All Documents

To view the content of the documents, you can click on the {} JSON link.

CouchDB View Document

To edit the document, you can click on the pencil icon shown on the right or switch back to the Metadata view and click the document link. Change the values of any of the items and click Save Document to finish it.

Delete Document

To delete the document, click the checkmark in front of the document, and select the delete button on top as shown below.

CouchDB Delete Document

Step 7 - Basic Database Operations using Commandline

While using the web interface is a simpler way of using CouchDB, greater efficiency can be achieved by performing the same operations via the command line.

Create Database

Before we get into creating our database, let us define a variable for the URL to connect. We will be using simple plain-text authentication for our examples. Since we will need to authenticate every command, it's better to use a predefined variable for it. You can use localhost or 127.0.0.1 to connect to the CouchDB installation.

$ HOST="http://admin:[email protected]:5984"

Note: Using a plain-text password is not the best method and shouldn't be used in production environments. You can check CouchDB's official documentation for more secure authentication methods.

Now that we have defined the host URL, let us try to create another database using the following command.

$ curl -X PUT $HOST/another_db

The name of the database is another_db. And we need to provide the administrator password for the command.

Create Document

To create a document, run the following command.

$ curl -X POST -d '{"todo":"task 1", "done":false}' $HOST/another_db -H "Content-Type:application/json"

The -X flag indicates that we are performing an HTTP POST operation. The -H flag specifies what type of content we are pushing which is JSON here. And the -d flag specifies the actual JSON content that we are adding.

The above command will automatically generate an ID for the document. It will generate the following output telling that the command was successful.

{"ok":true,"id":"0b4ad0d607479c09bb9121b14600c6ee","rev":"1-2fc1d70532433c39c9f61480607e3681"}

As you can see, an ID for the document was automatically generated. If you want to specify a custom ID, you can do so in the following manner.

$ curl -X POST -d '{"_id":"random_task", "todo":"task 2", "done":false}' $HOST/another_db -H "Content-Type:application/json"
{"ok":true,"id":"random_task","rev":"1-bceeae3c4a9154c87db1649473316e44"}

Create Documents in Bulk

You can also add documents in bulk.

$ curl -X POST -d '{"docs": [{"todo":"task 3", "done":false}, {"todo":"task 4", "done":false}]}' $HOST/another_db/_bulk_docs -H "Content-Type:application/json"

As you can see, when we are inserting multiple documents, the POST body contains an object with a docs field. This field carries an array of documents to be inserted into the database. While inserting a single document, the POST request was sent to the database ($HOST/another_db). But when we need to insert multiple documents, the request has to be sent to the $HOST/another_db/_bulk_docs URL.

You will receive a similar output.

[{"ok":true,"id":"0b4ad0d607479c09bb9121b14600cb04","rev":"1-778fd61f8f460d0c1df1bb174279489d"},{"ok":true,"id":"0b4ad0d607479c09bb9121b14600d9ef","rev":"1-dc9e84861bba58e5cfefeed8f5133636"}]

Here you can see, that the output contains the ID for the two new documents.

Read Document

To read a document from the database, you need to specify its ID. Run the following command to retrieve the random_task document. Since we used an HTTP POST request to add data, it makes sense that to retrieve it, you will need to use a GET request.

$ curl -X GET $HOST/another_db/random_task

You will receive the following output.

{"_id":"random_task","_rev":"1-bceeae3c4a9154c87db1649473316e44","todo":"task 2","done":false}

Here, note down the _rev field of the document. This field is useful when you need to edit or delete a document.

Edit Document

To edit a document, you need to use the _rev field. Any request that doesn't include the _rev field is automatically rejected by CouchDB while editing. Since CouchDB updates the entire document, the entire document must be sent in the request body during the edit operation.

Let us update the random_task document by using the following command.

$ curl -X PUT -d '{"_rev":"1-bceeae3c4a9154c87db1649473316e44", "todo":"task 2", "done":true}' $HOST/another_db/random_task

Make sure you replace the value of the _rev field with the value you got when you read the document. It should match the value in the actual document.

You will receive an output similar to the one below.

{"ok":true,"id":"random_task","rev":"2-4cc3dfb6e76befd665faf124b36b7f1c"}

If you notice, the rev field's data has changed. Any further change to the document will require you to use this new rev value.

Delete Document

To delete a document, you will need to specify the ID and the updated rev value. Let us delete the random-task document.

$ curl -X DELETE $HOST/another_db/random_task?rev=2-4cc3dfb6e76befd665faf124b36b7f1c

Make sure to match the value of the rev field in the command with the value in your actual document. You will get similar output like the following.

{"ok":true,"id":"random_task","rev":"3-07d6cde68be2a559497ec263045edc9d"}

View Data

Let us check the list of all databases on the server.

$  curl -X GET $HOST/_all_dbs

List all documents under a particular database.

$ curl -X GET $HOST/another_db/_all_docs

Step 8 - Install Caddy Server

So far, we have accessed CouchDB using the server IP address. There is an easy method if you want to replace it with your domain name and use SSL in front of it to make it more secure. For our tutorial, we will be using Caddy Server since it is lightweight and works with minimal configuration, and comes with in-built SSL creation.

Run the following command to install some packages required by Caddy. They may already be installed on your server.

$ sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

Install Caddy's GPG key and add the official repository to Debian's repository list.

$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

Install the Caddy server.

$ sudo apt update
$ sudo apt install caddy

Run the following command to verify the installation.

$ caddy version
v2.5.1 h1:bAWwslD1jNeCzDa+jDCNwb8M3UJ2tPa8UZFFzPVmGKs=

Step 9 - Configure Caddy

To configure Caddy to work as a reverse proxy server, you need to configure the Caddyfile. Open the Caddyfile for editing.

$ sudo nano /etc/caddy/Caddyfile

Replace the code in it with the following code.

couchdb.example.com {
        reverse_proxy localhost:5984

        tls [email protected]

        log {
                output file /var/log/caddy/couchdb.log
        }
}

Save the file by pressing Ctrl + X and entering Y when prompted.

Run the Caddy validator to check for any issues.

$ caddy validate --adapter caddyfile --config /etc/caddy/Caddyfile

If you get any errors regarding the formatting, run the following command to fix it.

$ sudo caddy fmt --overwrite /etc/caddy/Caddyfile

Run the validator again.

Restart the Caddy server to implement the changes.

$ sudo systemctl restart caddy

You can now access CouchDB via the URL https://couchdb.example.com/_utils/ in your browser.

Conclusion

You have learned how to install the Apache CouchDB Database server on a Debian 11 machine. You also learned how to perform basic database operations via the command line and the Fauxton UI. And last but not the least, you also learned how to expose the Fauxton UI on the internet by using Caddy as a reverse proxy server. If you have any questions, post them in the comments below.

Share this page:

0 Comment(s)