Skip to content

Update harperdb->harper #477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kriszyp merged 4 commits into from
Apr 23, 2026
+27 −19
Merged

Update harperdb->harper #477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
088a900
Update harperdb->harper
kriszyp Apr 22, 2026
2872411
Mention harper-pro as well
kriszyp Apr 22, 2026
6fbf47f
Fix typo
kriszyp Apr 22, 2026
c5aff9d
Apply suggestion from @cb1kenobi
kriszyp Apr 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions learn/developers/harper-applications-in-depth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Within every Harper installation are these core files and directories:
┠─ keys/
┠─ log/
┠─ harper-application-lock.json
┠─ harperdb-config.yaml
┠─ harper-config.yaml
┠─ hdb.pid
┠─ operations-server
┗━ README.md
Expand All @@ -90,7 +90,7 @@ The directories themselves are fairly self-explanatory:

The `harper-application-lock.json` file is similar to any sort of lockfile. Its purpose is to ensure Harper is installing the correct versions of applications and plugins. This is an internal file and you shouldn't ever have to modify it yourself.

Finally, and most importantly is the `harperdb-config.yaml`. This is the main configuration file for your Harper installation. Lets open this file and inspect its contents. Local users should open it in their editor of choice, Fabric users should navigate to the "Config" tab from their main organization view.
Finally, and most importantly is the `harper-config.yaml`. This is the main configuration file for your Harper installation. Lets open this file and inspect its contents. Local users should open it in their editor of choice, Fabric users should navigate to the "Config" tab from their main organization view.

You should see a number of top-level properties such as `http`, `threads`, `authentication`, and more. Each of these corresponds to one of Harper's built-in core features. This file is the source of truth for Harper configuration values. You can make changes directly to the file and then restart Harper for them to take affect.

Expand Down Expand Up @@ -477,7 +477,7 @@ Harper provides the ability to launch a proper debugger as part of the Harper pr
Harper v4 ships as a built and minified package, so debugging the Harper source may be confusing; you generally will only want to debug your custom code. However, in the near future, as Harper v5 is released using our new open source core, you will be able to debug Harper's core too!
:::

Before getting started, either open the `harperdb-config.yaml` file or use the Operations API to inspect how Harper is currently configured (using the `get_configuration` operation). We are looking for the `"threads"` part of the configuration object in particular.
Before getting started, either open the `harper-config.yaml` file or use the Operations API to inspect how Harper is currently configured (using the `get_configuration` operation). We are looking for the `"threads"` part of the configuration object in particular.

<Tabs>
<TabItem value="CLI">
Expand Down
40 changes: 24 additions & 16 deletions learn/getting-started/install-and-connect-harper.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem';

import GeneralPrerequisites from '../../src/components/learn/general-prerequisites.mdx';

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`](https://hub.docker.com/r/harperdb/harperdb)), and most recently a platform service called [Harper Fabric](https://fabric.harper.fast).
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 ([`harperfast/harper`](https://hub.docker.com/r/harper/harper)), and most recently a platform service called [Harper Fabric](https://fabric.harper.fast).

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.

Expand All @@ -33,12 +33,12 @@ If you want to use the cloud-hosted, platform service Harper Fabric instead of a
<Tabs groupId="local-install">
<TabItem value="npm" label="npm">

Harper is published to the npm registry as [`harperdb`](https://www.npmjs.com/package/harperdb) and requires Node.js current, active LTS, or maintenance LTS versions to run.
Harper is published to the npm registry as [`harper`](https://www.npmjs.com/package/harper) 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:

```bash
npm install -g harperdb
npm install -g harper
```

Then, execute the Harper CLI:
Expand All @@ -47,7 +47,15 @@ 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`.
Harper also has a "pro" version, which includes full enterprise scale capabilities, such as replication, certificate management, and more advanced analytics. This is also the version running on Fabric. However, this is licensed with Elastic 2.0, and you need a usage license through Harper if you want to use this for a managed service. The oper and pro versions offer the same APIs for development, so the pro version is not necessary to start building applications. If you do want to install, it is available with at `@harperfast/harper-pro`:

```bash
npm install -g @harperfast/harper-pro
```

(Harper pro can be started with the `harper` command as well).

When installing locally on your machine, you can specify any destination for Harper. We recommend using something within your home directory such as `$HOME/harper`. 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.
Expand All @@ -59,7 +67,7 @@ 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 destination for HarperDB: $HOME/harper
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
Expand All @@ -73,7 +81,7 @@ HarperDB installation was successful.
</TabItem>
<TabItem value="docker" label="Docker">

Harper is readily available as a Docker image [`harperdb/harperdb`](https://hub.docker.com/r/harperdb/harperdb).
Harper is readily available as a Docker image [`harperfast/harper`](https://hub.docker.com/r/harper/harper).

The image is based off of a Node.js image and the default tag is always published using the latest Harper version and latest Node.js Active LTS version.

Expand All @@ -82,19 +90,19 @@ The image uses sensible default environment variables, agreeing to the terms and
Using a Docker compatible container manager of choice, the simplest way to get started is using:

```bash
docker pull harperdb/harperdb
docker pull harperfast/harper
docker run -it \
--name harper \
-v $HOME/hdb:/home/harperdb/hdb \
-v $HOME/dev:/home/harperdb/dev \
-v $HOME/harper:/home/harper/harper \
-v $HOME/dev:/home/harper/dev \
-e DEFAULTS_MODE=dev \
-e REPLICATION_HOSTNAME=localhost \
-p 9925:9925 \
-p 9926:9926 \
harperdb/harperdb
harperfast/harper
```

The `-v` options will mount the Harper installation (`hdb/`) as well as a development directory (`dev/`) to the container host which is useful for development purposes. The `hdb/` path will contain the Harper installation parts, and the `dev/` directory can be used to create projects (which future guides will require).
The `-v` options will mount the Harper installation (`harper/`) as well as a development directory (`dev/`) to the container host which is useful for development purposes. The `harper/` path will contain the Harper installation parts, and the `dev/` directory can be used to create projects (which future guides will require).

The additional environment variables specified by `-e` options ensures the installation is setup for local development.

Expand Down Expand Up @@ -140,21 +148,21 @@ Starting HarperDB...
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
[http/1] [info]: Domain socket listening on <rootpath>/harper/operations-server
HarperDB 4.y.z successfully started
[main/0] [notify]: HarperDB successfully started.

Hostname: localhost
Worker Threads: 1
Root Path: <rootpath>/hdb
Root Path: <rootpath>/harper
Debugging: enabled: true
Logging: level: info, location: <rootpath>/hdb/log/hdb.log, stdout/err
Logging: level: info, location: <rootpath>/harper/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
Operations API: HTTP: 9925, CORS: enabled for *, unix socket: <rootpath>/harper/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.
Note that log messages are being sent to the console (stdout and stderr) in addition to the log file <rootpath>/harper/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.
```

Expand Down