Getting Started With Apache CouchDB NoSQL on Debian 11

‍Apache CouchDB is a powerful open-source NoSQL database server developed by the Apache Software Foundation. It offers a flexible and scalable solution for handling large amounts of structured and semi-structured data. In this article, we will guide you through the process of installing Apache CouchDB on a Debian 11 server. We will walk you through the step-by-step installation process, basic database operations, and accessing CouchDB via a public URL using the Caddy web server.

Prerequisites

Before we begin, make sure you have the following prerequisites in place:

A server running Debian 11
Sudo package installed
A non-root user with sudo privileges
Updated system packages

Step 1 – Install Utilities

To get started, we need to install some utilities that will be required during the installation process. Open your terminal and run the following command to install the necessary tools:

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

These tools will help us with the installation and configuration of CouchDB.

Step 2 – Add CouchDB Repository

Next, we need to add the CouchDB repository to the system repository list. Run the following commands to import the CouchDB’s GPG key and add the repository:

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

Once the repository is added, update the system repository list:

$ sudo apt update

Step 3 – Install CouchDB

With the repository added, we can now proceed with the installation of CouchDB. Run the following command to install CouchDB:

$ sudo apt install couchdb -y

During the installation process, you will be prompted to configure basic settings for CouchDB. Choose the appropriate options according to your requirements. Once the installation is complete, CouchDB will be up and running on your server.

Step 4 – Verify CouchDB Install

To verify if the installation was successful, you can use the curl command to check the CouchDB server’s response. Run the following command:

$ curl http://127.0.0.1:5984/

This command will return a JSON formatted output with information about CouchDB, including the version and features. If you see the expected output, it means that CouchDB is successfully installed and running.

Step 5 – Access CouchDB

By default, CouchDB can be accessed via a web-based GUI called Fauxton. Open your favorite web browser and enter the following URL to access the CouchDB interface:

http://<yourserverIP>:5984/_utils/

Replace <yourserverIP> with the actual IP address of your server. You should see the Fauxton login screen. Enter the administrator username (default is admin) and the password you set during the installation process. Once authenticated, you will have access to the CouchDB dashboard.

Step 6 – Basic Database Operations using CouchDB Interface

In the CouchDB Fauxton interface, you can perform various CRUD (Create, Read, Update, Delete) operations on your databases. Let’s start with creating a new database.

Create Database

To create a new database, click on the “Create Database” link on the main screen. Enter the desired name for your database and click the “Create” button. The new database will be created, and you will be redirected to its overview page.

Create Document

Once you have a database, you can create documents within it. Click on the “Create Document” button to get started. You will be presented with a pre-filled screen containing a JSON object and a unique identifier (_id). You can add or modify fields in the JSON object as needed. Click the “Create Document” button to save the new document.

Delete Document

To delete a document, select the document by clicking the checkbox next to it, and then click the “Delete” button at the top. Confirm the deletion when prompted. The selected document will be permanently deleted from the database.

Step 7 – Basic Database Operations using Command Line

While the Fauxton interface provides an intuitive way to interact with CouchDB, you can also perform the same operations using the command line. This can be useful when automating tasks or working with scripts. Let’s explore some basic database operations using the command line.

Create Database

To create a database using the command line, you can use the curl command. Here’s an example:

$ curl -X PUT http://localhost:5984/another_db

This command creates a new database named “another_db” on the local CouchDB server.

Create Document

To create a document using the command line, you can use the curl command with the -d flag to specify the document data. Here’s an example:

$ curl -X POST -d '{"todo":"task 1", "done":false}'http://localhost:5984/another_db

This command creates a new document with the specified data in the “another_db” database.

Read Document

To read a document from the database, you can use the curl command with the document’s ID. Here’s an example:

$ curl -X GET http://localhost:5984/another_db/document_id

Replace “document_id” with the actual ID of the document you want to retrieve.

Edit Document

To edit a document, you need to provide the updated document data along with the document’s ID and revision number. Here’s an example:

$ curl -X PUT -d '{"_id":"document_id", "_rev":"revision_number", "todo":"updated task", "done":true}' http://localhost:5984/another_db/document_id

Replace “documentid” with the actual ID of the document and “revisionnumber” with the revision number you want to update.

Delete Document

To delete a document, you need to provide the document’s ID and revision number. Here’s an example:

$ curl -X DELETE http://localhost:5984/another_db/document_id?rev=revision_number

Replace “documentid” with the actual ID of the document and “revisionnumber” with the revision number of the document.

Step 8 – Install Caddy Server

To access CouchDB via a public URL with HTTPS, we can use the Caddy server as a reverse proxy. Caddy is a lightweight and easy-to-configure web server that automatically handles SSL/TLS certificates. Let’s install and configure Caddy on our server.

Install Caddy

Run the following commands to install the necessary packages and add the Caddy repository:

$ sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
$ 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
$ sudo apt update
$ sudo apt install caddy

Configure Caddy

Open the Caddyfile for editing:

$ sudo nano /etc/caddy/Caddyfile

Replace the existing content with the following:

couchdb.example.com {
reverse_proxy localhost:5984
tls test@example.com
log {
output file /var/log/caddy/couchdb.log
}
}

Save the file and exit the editor. This configuration tells Caddy to proxy requests for couchdb.example.com to the local CouchDB server running on port 5984. It also enables TLS encryption using the specified email address for certificate management and logs the requests to a file.

Validate the Caddy configuration:

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

If there are no errors, restart the Caddy service to apply the changes:

$ sudo systemctl restart caddy

Conclusion

Congratulations! You have successfully installed Apache CouchDB on your Debian 11 server and learned how to perform basic database operations both through the web-based Fauxton interface and the command line. Additionally, you have set up a Caddy server as a reverse proxy to access CouchDB via a public URL with HTTPS.

CouchDB provides a robust and scalable solution for managing your NoSQL databases, and with the help of Caddy, you can ensure secure access to your CouchDB instance. If you have any questions or need further assistance, feel free to reach out to our support team at Shape.host. Shape.host offers reliable and scalable Linux SSD VPS hosting solutions to meet your business’s growing needs.