Setup HarperDB on Equinix Bare Metal Server
Tags: harperdb, database, programming, tutorial
Published: 2023-04-19 15:03:43

## Table of Contents
- [Introduction to HarperDB](#introduction-to-harperdb)
- [Ways to Host HarperDB](#ways-to-host-harperdb)
- [Introduction to Equinix Bare Metal](#introduction-to-equinix-bare-metal)
- [Equinix Account Setup and Completing Prerequisites](#equinix-account-setup-and-completing-prerequisites)
- [Create an On Demand Server in Equinix](#create-an-on-demand-server-in-equinix)
- [Login into the Server using SSH](#login-into-the-server-using-ssh)
- [Install and Run HarperDB on Equinix Server](#install-and-run-harperdb-on-equinix-server)
    - [Prerequisites](#prerequisites)
    - [HarperDB installation using npm](#harperdb-installation-using-npm)
- [Run HarperDB in Equinix](#run-harperdb-in-equinix)
    - [Alternate method to run HarperDB](#alternate-method-to-run-harperdb)
- [Access the HarperDB using Equinix IP](#access-the-harperdb-using-equinix-ip)
- [Start using HarperDB hosted in Equinix](#start-using-harperdb-hosted-in-equinix)
    - [Create Schema](#create-schema)
    - [Create Table](#create-table)
    - [Insert a Record](#insert-a-record)
- [Conclusion](#conclusion)
- [Document References](#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](https://www.harperdb.io/post/industries-that-need-distributed-database).

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](https://www.harperdb.io/post/edge-caching-explained-why-you-should-be-using-it)
- 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](https://deploy.equinix.com/get-started/) 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

![Equinix Org Project](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jhdzpyij6roebgjwitu0.png)

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](https://www.ssh.com/academy/ssh/keygen#creating-an-ssh-key-pair-for-user-authentication) 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”. 

![new ssh key](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5xug9qtp8q9nbelg86y1.png)

## 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 1 select ondemand](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/z9gy5119u01gf8qqa1ph.png)

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

![Step 2 equinix create](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6fk6e92meoc2quiiam1r.png)

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

![Step 3 equinix create](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ugnzipscr4jjaq94yie0.png)

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

![Step 4 equinix create](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ypz50rsnbbsp0pfrvdyr.png)

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

![Step 6 equinix create](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f3h1q6wv6ejfx4ld4ekc.png)

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

![Step 7 equinix create](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wtm24e9xgx0vjo4gp0tm.png)

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

![Step 8 equinix create](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xb8r9poqszqmrt2t1s0o.png)

## 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](https://docs.harperdb.io/docs/install-harperdb) 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](https://products-harperdb-io.s3.us-east-2.amazonaws.com/harperdb-4.0.5.tgz)
```
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](https://api.harperdb.io/#c50e9963-888a-4ccd-99f6-4ae266dfdf60) 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.

## Document References
HarperDB [Getting Started](https://docs.harperdb.io/docs/getting-started)
HarperDB [API documentation](https://api.harperdb.io/#2dc540c1-d62b-4521-a078-4e8d60e3b391)
Equinix [Getting Started](https://deploy.equinix.com/get-started/) 

Follow my work and get in touch,
This is Saravanan, I'm a DevOps Evangelist | Tech Blogger | Mentor | AWS Community Builder | Hashicorp Ambassador | Content Creator
- [GitHub](https://github.com/chefgs)
- [LinkedIn](https://www.linkedin.com/in/saravanan-gnanaguru-1941a919/)
- [Twitter](https://twitter.com/saransid)
- [YouTube](https://www.youtube.com/@gsaravanantech)
- [gsaravanan.dev](https://gsaravanan.dev)