How to Install Apache CouchDB NoSQL Database Server on Debian 11
source link: https://www.howtoforge.com/how-to-install-apache-couchdb-database-server-on-debian-11/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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.
Next, you will be asked to set a cookie name. Choose any name you want.
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.
Next, you will be asked to create an administrator password for its default admin account.
You will be asked to verify the password again.
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.Advertisement
{"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.
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.
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.
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.
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.
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).
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" }
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.
To view the content of the documents, you can click on the {} JSON link.
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.
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.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK