Saravanan Gnanaguru

Posted on Apr 19, 2023 • Edited on Dec 5, 2023

Setup HarperDB on Equinix Bare Metal Server

#harperdb #database #programming #tutorial

Introduction to HarperDB
Ways to Host HarperDB
Introduction to Equinix Bare Metal
Equinix Account Setup and Completing Prerequisites
Create an On Demand Server in Equinix
Login into the Server using SSH
Install and Run HarperDB on Equinix Server
- Prerequisites
- HarperDB installation using npm
Run HarperDB in Equinix
- Alternate method to run HarperDB
Access the HarperDB using Equinix IP
Start using HarperDB hosted in Equinix
Conclusion
Document References

Introduction to HarperDB

HarperDB is a globally-distributed edge data platform that is designed to handle massive amounts of data with ultra low latency. Other edge database solutions are not write optimized and global replication is slow. Whereas HarperDB is read and write optimized, handling upwards of 20K writes per second per node, with 110 ms global replication.

HarperDB’s clustering methodology relies on eventual consistency to be much more efficient than more traditional options, and you can’t lock out the database globally. Read more about HarperDB and the use case it is trying to solve in this blog.

HarperDB has the solutions listed below and if you’re an organization looking for database solutions in this area can utilize the HarperDB for your need,

Distributed Database
Edge Computing / Edge Caching
Infrastructure Savings

Ways to Host HarperDB

There are multiple ways available to getting started with HarperDB, but the quickest way to get up and running with HarperDB is with HarperDB Cloud.

It is also possible to Install HarperDB on Cloud Instances across public cloud providers like AWS, Azure, GCP and On premise Cloud providers like Equinix and Linode.

In this blog, we will see how to set-up the HarperDB database in Equinix Cloud Bare Metal Server and create steps to create a DB schema, Table, and insert a record.

Introduction to Equinix Bare Metal

Equinix is one of the leaders in providing on-demand bare metal as a service product offering. You can sign-up here to get started with Equinix.

Equinix Account Setup and Completing Prerequisites

In this section we will see the steps to get started with Equinix.

Step 1: Sign-up for an account,
Step 2: During the sign-up we need to add payment method for billing (apply “deploynow” code to get the trial credit of $250)
Step 3: Create an organization and a project under the org

Step 5: Click on the name of the Project to go to the project page
Step 6: Click on Project Settings > SSH Keys

Step 7: Create an ssh key in your workstation from which we will be using to logging into “Equinix Instance” using the SSH method. Follow the guide here if you’re new to creating the SSH key for your workstation
Step 8: Copy the public key (generally file name will be id_rsa.pub) from the file ending with *.pub
Step 9: Paste Public key value in SSH key page by adding new “Add new key”.

Create an On Demand Server in Equinix

In this section we will see the steps to deploy our on-demand server to install HarperDB.
Step 1: Go to project > Bare metal servers > On demand

Step 2: Go to the “Classic” tab, choose the metro region in which you want to host the HarperDB server.

Step 3: Choose operating system - for this HarperDB demo I’ve selected the OS “Ubuntu 20.04”

Step 4: Expand “Optional settings” and go to “SSH keys” to select SSH key we have added earlier

Step 5: Verify the summary and click on “Deploy Now”
Step 6: We can observe the server instance is getting deployed

Step 7: After some time the instance deployment will be complete, and we can see the instance is up and running

Step 8: Click the instance “hostname” to open the instance details

Login into the Server using SSH

Using the public IPV4 address, we can get into the server using SSH method
Use the private key pair of the public key we have added in the SSH key while creating the instance. It will be located in the path ~/.ssh



$ ssh -i ~/.ssh/equinix_key root@145.40.77.227
The authenticity of host '145.40.77.227 (145.40.77.227)' can't be established.
ED25519 key fingerprint is SHA256:A8G3NWfuX9wEvSbiTtReGwSqouiUirqvXbfBjB/StmM.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '145.40.77.227' (ED25519) to the list of known hosts.
Welcome to Ubuntu 18.04.6 LTS (GNU/Linux 5.4.0-137-generic x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

  System information as of Thu Apr  6 05:42:41 UTC 2023

  System load:  0.25               Processes:            261
  Usage of /:   0.5% of 438.04GB   Users logged in:      0
  Memory usage: 1%                 IP address for bond0: 145.40.77.227
  Swap usage:   0%

0 updates can be applied immediately.

Your Hardware Enablement Stack (HWE) is supported until April 2023.


The programs included with the Ubuntu system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by
applicable law.

root@c3-small-x86-01:~#

Now we logged into the server and let us see the steps to install HarperDB in the Equinix Server.

Install and Run HarperDB on Equinix Server

Prerequisites

I’ve followed the installation steps available here and followed the Linux installation steps for installing nvm, since we deployed Ubuntu OS in Equinix.

Since it is just a demo installation, I’ve skipped the LVM configuration and Configure Data volume sections.
Now, HarperDB needs npm and NodeJS. So we need to install them using,

nvm - Node version manager, which is the recommended way for installing NodeJS and npm

I’ve used below commands to install nvm



curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

After running the above commands, either you can exit and re-login to the Equinix server so the changes will go into effect.



exit

Then install nvm version 17, which worked fine for me.



nvm install 17

HarperDB installation using npm

I’ve used the offline installation method for installing HarperDB in Equinix.

Step 1: Download installation package



wget https://products-harperdb-io.s3.us-east-2.amazonaws.com/harperdb-4.0.5.tgz

Step 2: install using npm



sudo npm install -g harperdb-4.0.5.tgz harperdb install

There are some optional steps available in the documentation which can help HarperDB to start when the OS boots.

Run HarperDB in Equinix

After the successful installation execute the command harperdb run to start the database

Follow the prompts to start the database



$ harperdb run

This version of HarperDB is tested against Node.js version 18.13.0, the currently installed Node.js version is: 17.9.1. Some issues may occur with untested versions of Node.js.

Starting HarperDB...

HarperDB not found, starting install process.

Starting HarperDB install...

Terms & Conditions can be found at https://harperdb.io/legal/end-user-license-agreement

and can be viewed by typing or copying and pasting the URL into your web browser.

I Agree to the HarperDB Terms and Conditions. (yes/no) yes

Please enter a destination for HarperDB: /root/hdb

Please enter a server listening port for HarperDB: 9925

Please enter a username for the HDB_ADMIN: HDB_ADMIN

Please enter a password for the HDB_ADMIN: [hidden]

HarperDB installation was successful.

           ▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒                                
       ▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒                     
   ▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒                    



    

    




▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▒


   ▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▒


    ▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▒▒


    ▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒


   ▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒


  ▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒

 ▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒ 

▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒


  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒


     ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒


         ▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒


            ▒▒▒▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒


               ▒▒▒▒▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒


                   ▒▒▒▓▓▒▒▒▒▒▒▒▒▒▒▒


                      ▒▒▒▒▒▒▒                                  

                HarperDB, Inc. Denver, CO.



    

    




|------------- HarperDB 4.0.5 successfully started ------------|

Alternate method to run HarperDB

There is also a single line command available to run HarperDB, which has all the database invocation arguments passed as CLI options



harperdb install --TC_AGREEMENT "yes" --ROOTPATH "/home/ubuntu/hdb" --OPERATIONSAPI_NETWORK_PORT "9925" --HDB_ADMIN_USERNAME "HDB_ADMIN" --HDB_ADMIN_PASSWORD "abc123!"

Access the HarperDB using Equinix IP

HarperDB runs in the server, so it can be accessed via localhost:port http://localhost:9925

Also we can access the server from outside using the “equinix-public-ip:port” as http://145.40.77.227:9925

Start using HarperDB hosted in Equinix

We will now see how to create a DB schema, create tables and insert records in it.

Refer the “Quick Start Examples” in API docs to explore the various programming methods for creating HarperDB elements like schema, tables, etc.

I’ll be using the curl method to play around with HarperDB

Create Schema



root@c3-small-x86-01:~ curl --location --request POST -u HDB_ADMIN:admin123 'http://localhost:9925' --header 'Content-Type: application/json' --data-raw '{

    "operation": "create_schema",

    "schema": "dev"

}'

{"message":"schema 'dev' successfully created"}

Create Table



root@c3-small-x86-01:~ curl --location --request POST -u HDB_ADMIN:admin123 'http://localhost:9925' --header 'Content-Type: application/json' --data-raw '{

    "operation": "create_table",

    "schema": "dev",

    "table": "dog",

    "hash_attribute": "id"

}'

{"message":"table 'dev.dog' successfully created."}

Insert a Record



root@c3-small-x86-01:~ curl --location --request POST -u HDB_ADMIN:admin123 'http://localhost:9925' --header 'Content-Type: application/json' --data-raw '{

    "operation": "insert",

    "schema": "dev",

    "table": "dog",

    "records": [

        {

            "id": 1,

            "dog_name": "Penny",

            "owner_name": "Kyle",

            "breed_id": 154,

            "age": 7,

            "weight_lbs": 38

        }

    ]

}'

{"message":"inserted 1 of 1 records","inserted_hashes":[1],"skipped_hashes":[]}

Conclusion

In this article, we discussed the introduction to HarperDB data platform, and how it was easy to get started with the HarperDB setup in the Equinix Bare metal on-demand server.
Also we have gone through how to access the database and tried out creating a DB schema, Table and Record.
Hope this article should be useful for database professionals, developers and data architects looking for a tutorial of HarperDB installation on Equinix bare metal servers.