Posted onApr 19, 2023 • Edited onDec 5, 2023

Setup HarperDB on Equinix Bare Metal Server

#harperdb #database #programming #tutorial

Introduction to HarperDB

HarperDB is aglobally-distributed edge data platform that is designed to handle massive amounts of data withultra 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 thisblog.

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 cansign-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 theguide 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.227The 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 namesAre you sure you want to continue connecting (yes/no/[fingerprint])? yesWarning: 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 theindividual files in /usr/share/doc/*/copyright.Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted byapplicable 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 availablehere and followed the Linux installation steps for installingnvm, 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 installnvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bashexport 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 installnvm 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 commandharperdb 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 athttps://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:porthttp://localhost:9925

Also we can access the server from outside using the “equinix-public-ip:port” ashttp://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” inAPI docs to explore the various programming methods for creating HarperDB elements like schema, tables, etc.

I’ll be using thecurl 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.