Maximum performance at minimal cost. Start your server in seconds now!
    Vijona

    Apache CouchDB Installation Guide for Ubuntu 20.04

    Overview

    Apache CouchDB is an open-source NoSQL database system that stores information in JSON document format. It utilizes JavaScript MapReduce syntax along with an HTTP API as its principal query methods for managing data.

    Built with Erlang, CouchDB provides real-time scalability and replication capabilities, ideal for distributed database systems requiring synchronization over low-bandwidth networks. These characteristics make CouchDB a strong candidate for building robust applications in sectors like banking, telecommunications, online commerce, and instant messaging.

    This tutorial explains how to set up and run the CouchDB database server on Ubuntu 20.04.

    Requirements

    Before starting, ensure you have the following:

    • An Ubuntu 20.04 server.
    • A non-root user account with sudo privileges.

    Step 1: Installing Required Packages and Fetching the CouchDB Package

    Since the Apache CouchDB package is not present in the default Ubuntu repositories, you need to add an external repository by completing the steps outlined below.

    Connect to Your Server

    Log in to your server using SSH with a non-root user account that has sudo access.

    Update System Package Lists

    Refresh your package database to ensure all repositories are up to date:

    Copy Code 
    

      $ sudo apt update

    Install Necessary Dependencies

    Install curl, apt-transport-https, and gnupg by running the following command:

    Copy Code 
    

      $ sudo apt install -y curl apt-transport-https gnupg

    Retrieve the CouchDB GPG Key

    Download the CouchDB GPG key. This step allows the apt package manager to verify the authenticity of the external repository:

    Copy Code 
    

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

    Enable the CouchDB Repository

    Add the CouchDB software repository to your list of available package sources:

    Copy Code 
    

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

     

    Step 2: Update Repository and Install CouchDB

    Refresh the Package Index

    Update your package list to recognize the newly added CouchDB repository:

    Copy Code 
    

      $ sudo apt update

    Install the CouchDB Package

    Install CouchDB by executing the command below:

    Copy Code 
    

      $ sudo apt install -y couchdb

    Press the Tab key and then hit Enter to move forward with the installation process.

    Select CouchDB Setup Mode

    On the next screen, choose the standalone setup option. Then, press Tab followed by Enter to proceed.

    General type of CouchDB configuration:

    • standalone
    • clustered
    • none

    Configure the Interface Bind Address

    Maintain the default bind-address value as 127.0.0.1. Press Tab and then Enter to move forward.

    CouchDB interface bind address:

    • 127.0.0.1

    Set Up Administrator Password

    Input a password of your choice for the CouchDB admin account and press Tab followed by Enter to continue.

    Password for the CouchDB “admin” user:

    • EXAMPLE_PASSWORD

    Confirm the Administrator Password

    Re-enter your chosen administrator password and press Tab then Enter to proceed.

    Repeat password for the CouchDB “admin” user:

    • EXAMPLE_PASSWORD

    At this point, the CouchDB installation is finalized. You can now manage the CouchDB service using the commands outlined below.

    Step 3: Manage the CouchDB Service

    Start CouchDB

    Use the following command to start the CouchDB service:

    Copy Code 
    

      $ sudo systemctl start couchdb

    Stop CouchDB

    To stop the CouchDB service, run this command:

    Copy Code 
    

      $ sudo systemctl stop couchdb

    Enable CouchDB on Boot

    Enable the CouchDB service so that it starts automatically when the system boots:

    Copy Code 
    

      $ sudo systemctl enable couchdb

    Restart CouchDB

    To restart the CouchDB service, use the following command:

    Copy Code 
    

      $ sudo systemctl restart couchdb

     

    Step 4: Create and Manage a CouchDB Database

    You can perform database queries on the CouchDB server in two primary ways:

    • The CouchDB HTTP API: CouchDB includes a JSON REST API, allowing you to interact with the database by sending HTTP requests.
    • The CouchDB Fauxton Interface: This is a web-based management tool that provides an easy-to-use graphical interface to administer your CouchDB databases through a browser.

    4.1. Using the CouchDB HTTP API

    You can access the CouchDB API using various HTTP clients. This example uses the Linux curl command-line tool to carry out fundamental database operations.

    Check Server Information

    Run the following command to retrieve basic details about your CouchDB server installation. Replace EXAMPLE_PASSWORD with your actual admin password:

    Copy Code 
    

      $ curl -X GET http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984

    Expected output:

    Copy Code 
    

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

    Create a New Database

    To create a new database named demo, run the following command:

    Copy Code 
    

      $ curl -X PUT http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo

    Expected output:

    Copy Code 
    

      {"ok":true}

    List All Databases

    To see all existing databases on your CouchDB server, execute:

    Copy Code 
    

      $ curl -X GET http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/_all_dbs

    Expected output:

    Copy Code 
    

      ["_replicator","_users","demo"]

     

    4.2. Insert Documents into the Demo Database

    Next, you will add three documents into the demo database. Each document will be defined in JSON format, and a unique identifier will be specified in the request URL using the structure ../demo/"1", ../demo/"2", and ../demo/"3".

    Create the First Document

    Execute the following command to create a document with ID “1”:

    Copy Code 
    

      $ curl -H 'Content-Type: application/json' -X PUT http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/"1" -d '{"product_name":"LED BULB" , "retail_price" : 23.55}'

    Create the Second Document

    Run this command to create a document with ID “2”:

    Copy Code 
    

      $ curl -H 'Content-Type: application/json' -X PUT http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/"2" -d '{"product_name":"WIRELESS MOUSE" , "retail_price" : 45.20}'

    Create the Third Document

    Use the following command to create a document with ID “3”:

    Copy Code 
    

      $ curl -H 'Content-Type: application/json' -X PUT http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/"3" -d '{"product_name":"4G ROUTER" , "retail_price" : 89.50}'

    Each successful insertion will produce output similar to the following:

    Copy Code 
    

      {"ok":true,"id":"1","rev":"1-b626670af2e7ee1ae13ffba7ffe83819"}
  {"ok":true,"id":"2","rev":"1-d995adf7c62c3f1931f817f7a3f2685c"}
  {"ok":true,"id":"3","rev":"1-1ebf435bdc37cf3c5dd32aebdd377d46"}

    View All Documents

    To display all documents stored in the demo database, execute this command:

    Copy Code 
    

      $ curl -X GET http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/_all_docs?include_docs=true

    Example output:

    Copy Code 
    

      {
    "total_rows":3,
    "offset":0,
    "rows":[
       {
          "id":"1",
          "key":"1",
          "value":{
             "rev":"1-b626670af2e7ee1ae13ffba7ffe83819"
          },
          "doc":{
             "_id":"1",
             "_rev":"1-b626670af2e7ee1ae13ffba7ffe83819",
             "product_name":"LED BULB",
             "retail_price":23.55
          }
       },
       {
          "id":"2",
          "key":"2",
          "value":{
             "rev":"1-d995adf7c62c3f1931f817f7a3f2685c"
          },
          "doc":{
             "_id":"2",
             "_rev":"1-d995adf7c62c3f1931f817f7a3f2685c",
             "product_name":"WIRELESS MOUSE",
             "retail_price":45.2
          }
       },
       {
          "id":"3",
          "key":"3",
          "value":{
             "rev":"1-1ebf435bdc37cf3c5dd32aebdd377d46"
          },
          "doc":{
             "_id":"3",
             "_rev":"1-1ebf435bdc37cf3c5dd32aebdd377d46",
             "product_name":"4G ROUTER",
             "retail_price":89.5
          }
       }
    ]
  }

    Retrieve a Specific Document

    To fetch the contents of a specific document by its ID, such as ID “1”, run this command:

    Copy Code 
    

      $ curl -X GET http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/1

    Example output:

    Copy Code 
    

      {"_id":"1","_rev":"1-b626670af2e7ee1ae13ffba7ffe83819","product_name":"LED BULB","retail_price":23.55}

     

    4.3. Update and Delete Documents in CouchDB

    Update a Document

    To update an existing document, specify the document’s unique ID in the URL (/demo/1/) and include the most recent _rev ID in the JSON payload. Use the following command to update document “1”:

    Copy Code 
    

      $ curl -H 'Content-Type: application/json' -X PUT http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/1/ -d '{"product_name":"15 WATTS LED BULB" , "retail_price" : 40.89, "_rev":"1-b626670af2e7ee1ae13ffba7ffe83819"}'

    Once updated, CouchDB generates a new document revision ID as shown below:

    Copy Code 
    

      {"ok":true,"id":"1","rev":"2-387ee2644327cda7a202ed3ad1a9cad0"}

    Verify Updated Document

    Fetch the document once again to confirm the changes have been applied:

    Copy Code 
    

      $ curl -X GET http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/1

    Updated product details:

    Copy Code 
    

      {"_id":"1","_rev":"2-387ee2644327cda7a202ed3ad1a9cad0","product_name":"15 WATTS LED BULB","retail_price":40.89}

    Note: CouchDB does not allow partial updates to documents. When a document is updated, a new version is created using the supplied information. Therefore, you cannot simply add new fields to an existing document without sending the entire modified content.

    Delete a Document

    To delete a document, you must specify both the document’s unique ID and its revision ID in the query URL.

    Retrieve the Revision ID

    Get the revision ID for the document with ID “3” by running this command:

    Copy Code 
    

      $ curl -X GET http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/3

    Example output:

    Copy Code 
    

      {"_id":"3","_rev":"1-1ebf435bdc37cf3c5dd32aebdd377d46","product_name":"4G ROUTER","retail_price":89.5}
    Delete the Document

    Use the following command to delete the document with ID “3” and the retrieved revision ID:

    Copy Code 
    

      $ curl -X DELETE http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/3?rev=1-1ebf435bdc37cf3c5dd32aebdd377d46

    Successful deletion confirmation:

    Copy Code 
    

      {"ok":true,"id":"3","rev":"2-37f9841ca9055574b880fdbf0278b170"}
    Verify the Deletion

    Attempt to retrieve the deleted document to confirm it has been removed:

    Copy Code 
    

      $ curl -X GET http://admin:EXAMPLE_PASSWORD@127.0.0.1:5984/demo/3

    Expected error output:

    Copy Code 
    

      {"error":"not_found","reason":"deleted"}

     

    4.4. Administer CouchDB Using the Fauxton Interface

    To manage your CouchDB server through the Fauxton web interface, some configuration adjustments are necessary. Follow the steps below to modify the default CouchDB settings.

    Edit the CouchDB Configuration File

    Open the /opt/couchdb/etc/local.ini file with a text editor:

    Copy Code 
    

      $ sudo nano /opt/couchdb/etc/local.ini

    Find the following line in the file:

    Copy Code 
    

      ... [chttpd]
  ;port = 5984
  ;bind_address = 127.0.0.1
  ...

    Remove the leading semicolon (;) to uncomment the bind_address setting and update its value from 127.0.0.1 to 0.0.0.0. This change allows CouchDB to listen on all network interfaces:

    Copy Code 
    

      ... [chttpd]
  ;port = 5984
  bind_address = 0.0.0.0
  ...

    Restart the CouchDB Service

    Restart CouchDB to apply the updated configuration settings:

    Copy Code 
    

      $ sudo systemctl restart couchdb

    Access the Fauxton Web Interface

    Open a web browser and navigate to the following URL. Replace 192.0.2.1 with your server’s actual public IP address:

    Copy Code 
    

      http://192.0.2.1:5984/_utils/

    The Fauxton login page should appear.

    Log in to Fauxton

    Authenticate by entering your username (admin) and password (e.g., EXAMPLE_PASSWORD). Click Log In to proceed. You will then be redirected to the Fauxton dashboard screen.

    Manage CouchDB with Fauxton

    The Fauxton interface enables you to perform essential database management tasks, including creating, retrieving, modifying, and deleting databases and documents.

    Conclusion

    This guide provided step-by-step instructions for installing and setting up Apache CouchDB on an Ubuntu 20.04 server. For further details about CouchDB’s features and capabilities, visit the official Apache CouchDB website.

    Source: vultr.com

    Create a Free Account

    Register now and get access to our Cloud Services.

    Try now

    Posts you might be interested in: