Skip to main content

Install and Connect Harper

One of Harper's primary goals since day one was to be easy to install and get started with. The core Harper application itself is just a Node.js application with some native module dependencies. The simplest and easiest way to get started using Harper is by installing it using npm (or any npm compatible Node.js package manager). In addition to installing Harper directly to your local development environment, the Harper team provides a Docker image (harperdb/harperdb), and most recently a platform service called Harper Fabric.

This guide will demonstrate all three ways to get started as well as introduce some basic Harper features such as the CLI and our built in health endpoint.

What You Will Learn​

  • How to install Harper locally using a Node.js package manager or a container
  • How to use the harper CLI
  • How to get setup using Harper Fabric
  • How to perform a health check using the built-in Harper Operations API health endpoint

Prerequisites​

Like the Welcome page stated, all guide pages require a set of system prerequisites such as command line access, HTTP client, and an up-to-date Node.js version. This guide is no different, and uniquely only requires those prerequisites. They are repeated here for your convenience, but future guides will not include them.

  • Command line access and general file-system and networking permissions
    • sudo is not required
    • For local development, Harper requires permission to read/write files and localhost networking permissions
  • HTTP client of choice
    • Most examples will present both curl and fetch-based HTTP requests
    • GUI-based HTTP clients will also work fine
  • Node.js Current, Active LTS, or Maintenance LTS version
    • For updated Node.js installation instructions refer to the official Download Node.js page
    • For more information on valid versions refer to Node.js Releases
    • Verify your Node.js version by running node -v in the command line
  • Code editor of choice
    • Everything from vim to Visual Studio Code to WebStorm IDE will work fine for the purposes of these guides

Local installation and setup​

note

If you want to use the cloud-hosted, platform service Harper Fabric instead of a local installation, skip ahead to the Getting started with Fabric section.

Harper is published to the npm registry as harperdb and requires Node.js current, active LTS, or maintenance LTS versions to run.

The fastest way to get started is by installing Harper globally using an npm compatible package manager:

npm install -g harperdb

Then, execute the Harper CLI:

harper

When installing locally on your machine, you can specify any destination for Harper, we recommend using something within your home directory such as $HOME/hdb. Keep note of what you specify for the username and password. Make sure you select the dev default config and set the hostname to localhost.

important

Do not actually enter $HOME in the destination prompt; it should automatically fill in the value of your home directory. Otherwise, specify the absolute path for the Harper installation.

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: $HOME/hdb
Please enter a username for the administrative user: HDB_ADMIN
Please enter a password for the administrative user: [hidden]
Default Config - dev (easy access/debugging) or prod (security/performance): (dev/prod) dev
Please enter the hostname for this server: localhost

HarperDB installation was successful.

[main/0] [notify]: HarperDB installation was successful.

After completing the installation step, Harper should now be running in the active process.

As long as the logging.stdStream configuration option is set to true (which is the default when using the dev default mode), Harper will also stream all logs to the stdout and stderr streams too.

If all is working correctly, you should see the following output in your command line:

Starting HarperDB...

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

                    HarperDB, Inc. Denver, CO.

[main/0] [info]: HarperDB PID <pid>
[main/0] [info]: Checking if HDB software has been updated
Debugger listening on ws://127.0.0.1:9229/<inspector-id>
For help, see: https://nodejs.org/en/docs/inspector
[main/0] [info]: All root applications loaded
[http/1] [info]: Domain socket listening on <rootpath>/hdb/operations-server
HarperDB 4.y.z successfully started
[main/0] [notify]: HarperDB successfully started.

Hostname:           localhost
Worker Threads:     1
Root Path:          <rootpath>/hdb
Debugging:          enabled: true
Logging:            level: info, location: <rootpath>/hdb/log/hdb.log, stdout/err
Default:            HTTP (and WS): 9926, CORS: enabled for *
Operations API:     HTTP: 9925, CORS: enabled for *, unix socket: <rootpath>/hdb/operations-server
MQTT:               TCP: 1883, TLS: 8883, WS: 9926
Replication:        WS: 9925, WSS: 9933

Note that log messages are being sent to the console (stdout and stderr) in addition to the log file <rootpath>/hdb/log/hdb.log. This can be disabled by setting logging.stdStreams to false, and the log file can be directly monitored/tailed.
This server does not have valid usage licenses, this should only be used for educational and development purposes.

This initial output contains a lot of helpful information. After the ASCII logo, there are a number of important log lines displaying the application process ID, the debugger endpoint, the domain socket path, and the Harper application version. Log lines are always prepended with the thread name, number, and log level. [main/0] is the main thread. [http/1] is the singular, additional worker thread. [info] is the default log level. After the log lines is specific application configuration information. It shows the application hostname, the number of worker threads, where Harper was installed, is the debugger enabled, logging level and location followed by ports, CORS, and socket path details for various networking protocols. We'll explain all of these in due time.

Interrupting the process (CTRL/CMD + C) will shut down Harper.

With Harper successfully running, skip ahead to Performing a health check to learn how to verify your local Harper instance is running and complete this getting started guide. Or continue reading for more information on getting started with Harper Fabric.

Getting started with Fabric​

Fabric is our service for managing and deploying Harper on a distributed network. Fabric makes it easy to create new Harper clusters, the Harper application platform running on distributed nodes, and deploy your application to this service. Fabric has a management interface, and provides a UI for managing your deployments and even your local instance that you just installed. You can sign up for Fabric for free and create a free Harper cluster to deploy your application:

  • Go to Fabric and sign-up for a new account.
    • You will need to agree to the terms of service and verify your email address.
  • Once you have created an account, you can create an organization. This will allow you to collaboratively manage your Harper services with others. This will also define the host domain that will be used.
  • You can now create a new Harper cluster or instance:
    • Create a free Harper cluster for trying out Harper.
    • Purchase a Harper cluster with higher performance, scalability, and limits.
    • Add your own local instance to manage everything in one place.

After successfully creating a Harper Fabric cluster, take note of the cluster URL and continue to the Performing a health check section to verify your instance.

If you have any issues getting started with Fabric, consult the dedicated Fabric documentation. If you still need help, join the official Harper community Discord and get help from the Harper engineering team.

Performing a health check​

To check if everything is configured correctly and ready to go for development, run a health check using the built-in /health endpoint from the Harper Operations API server.

The Operations API provides a full set of capabilities for configuring, deploying, administering, and controlling Harper. We'll learn more about it throughout all of the guide pages.

note

If you are using a Harper Fabric cluster, replace the http://localhost with the cluster URL.

curl 'http://localhost:9925/health'

If you see HarperDB is running., fantastic work! You've successfully installed and setup Harper. Continue on to the next part of the Getting Started section, creating your first Harper application.

Additional Resources​