You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Developers have two recommended approaches for developing Harper applications; either locally or with [Harper Fabric](https://fabric.harper.fast), our distributed data application platform service. If you start developing locally, you can always switch to Fabric by deploying your application. If you're interested in setting up a Fabric instance, navigate to the [Fabric](../../fabric/index.md) part of the documentation, and then come back after you have created your first Fabric cluster.
12
+
One of Harper's primary goals since day 1 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).
13
+
14
+
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.
15
+
16
+
## What You Will Learn
17
+
18
+
- How to install Harper locally
19
+
- How to use the `harperdb` CLI
20
+
- How to get setup using Harper Fabric
21
+
- How to install and setup Harper as a container
22
+
- How to perform a health check using the built-in Harper Operations API health endpoint
23
+
24
+
## Prerequisites
25
+
26
+
Like the [Welcome](../) page stated, all guide pages require a set of system prerequisites such as command line access, HTTP client, and an uptodate 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.
11
27
12
-
## Install Harper Locally
28
+
<GeneralPrerequisites />
13
29
14
-
Harper is published to the npm registry and requires Node.js current, active LTS, or maintenance LTS versions to run.
30
+
## Local Installation and Setup
31
+
32
+
:::note
33
+
If you want to use the cloud-hosted, platform service Harper Fabric instead of a local installation, skip ahead to the [Get Started with Fabric](#get-started-with-fabric) section.
34
+
:::
35
+
36
+
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.
15
37
16
38
The fastest way to get started is by installing Harper globally using an npm compatible package manager:
17
39
@@ -25,49 +47,236 @@ Then, execute the Harper CLI to start the interactive installation process:
25
47
harper install
26
48
```
27
49
28
-
After completing the installation, run within the current command process using:
50
+
The interactive installation process will prompt with a number of questions. It should look something like this:
51
+
52
+
```
53
+
> harperdb install
54
+
55
+
Starting HarperDB install...
56
+
57
+
Terms & Conditions can be found at https://harperdb.io/legal/end-user-license-agreement
58
+
and can be viewed by typing or copying and pasting the URL into your web browser.
59
+
I agree to the HarperDB Terms and Conditions: (yes/no) yes
60
+
Please enter a destination for HarperDB: /Users/user/hdb
61
+
Please enter a username for the administrative user: HDB_ADMIN
62
+
Please enter a password for the administrative user: [hidden]
63
+
Default Config - dev (easy access/debugging) or prod (security/performance): (dev/prod) dev
64
+
Please enter the hostname for this server: localhost
65
+
66
+
HarperDB installation was successful.
67
+
68
+
[main/0] [notify]: HarperDB installation was successful.
69
+
```
70
+
71
+
For the purpose of this getting started guide it is important to keep track of the installation path, the admin username and password, and to select the `dev` default configuration values.
72
+
73
+
All options can also be specified using environment variables or CLI arguments. For a complete list see the [Harper CLI](../../docs/deployments/harper-cli) reference docs.
74
+
75
+
For a quick installation helper use the following (make sure to replace the `<password>` and `<user>` tags before executing):
76
+
77
+
```bash
78
+
harperdb install \
79
+
--TC_AGREEMENT=yes \
80
+
--DEFAULTS_MODE=dev \
81
+
--HDB_ADMIN_USERNAME=HDB_ADMIN \
82
+
--HDB_ADMIN_PASSWORD=<password> \
83
+
--ROOTPATH='/Users/<user>/hdb' \
84
+
--REPLICATION_HOSTNAME=localhost
85
+
```
86
+
87
+
### Running Harper
88
+
89
+
After completing the installation, run Harper using:
29
90
30
91
```bash
31
-
harper
92
+
harperdb
93
+
```
94
+
95
+
This command runs Harper in the current command 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.
96
+
97
+
If all is working correctly, you should see the following output in your terminal:
Note that log messages are being sent to the console (stdout and stderr) in addition to the log file /Users/ethan/hdb/log/hdb.log. This can be disabled by setting logging.stdStreams to false, and the log file can be directly monitored/tailed.
144
+
This server does not have valid usage licenses, this should only be used for educational and development purposes.
145
+
```
146
+
147
+
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, and domain socket path, and the Harper application version. Log lines are always prepended with the thread name, number, and then log level. `[main/0]` is the main thread, and `[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, and then ports, CORS, and socket path details for various networking protocols. We'll dive into all of these in due time.
148
+
149
+
Interrupting the process (CTRL/CMD + C) will shut down Harper.
150
+
151
+
With Harper successfully running, skip ahead to [Performing a health check](#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 regarding running Harper as a background process, installing Harper using containerization, or getting started with Harper Fabric.
152
+
153
+
### Running Harper as a background process
154
+
155
+
If you want to run Harper in the background, use `harperdb start` instead.
156
+
32
157
```
158
+
> harperdb start
159
+
Starting HarperDB...
33
160
34
-
To check if everything is configured correctly and ready to go for development, run a quick health check using the `/health` endpoint available within the Operations API server.
[main/0] [info]: Checking if HDB software has been updated
184
+
HarperDB 4.7.12 successfully started
185
+
[main/0] [notify]: HarperDB successfully started.
186
+
```
187
+
188
+
This output will still include the ASCII logo, and then a couple log lines displaying the process ID and Harper version, but then the process will exit and the standard streams are terminated. In order to see more log lines you must read the actual log file available by default at `<rootpath>/log/hdb.log`. For example, you can tail stream the log file using something like:
189
+
190
+
```bash
191
+
tail -f <rootpath>/log/hdb.log
192
+
```
193
+
194
+
Now, you must use `harperdb stop` to shut down Harper.
195
+
196
+
```
197
+
> harperdb stop
198
+
Stopping HarperDB.
199
+
[main/0] [notify]: Stopping HarperDB.
200
+
```
201
+
202
+
Start Harper if you stopped it, and skip ahead to [Performing a health check](#performing-a-health-check) to learn how to verify your local Harper instance is running and complete this getting started guide.
203
+
204
+
## Containerization
205
+
206
+
Harper is also readily available as a Docker image [`harperdb/harperdb`](https://hub.docker.com/r/harperdb/harperdb).
207
+
208
+
The Docker image is not too much different from the local installation and setup. We recommend at least reading through the previous [Local Installation and Setup](#local-installation-and-setup) section first.
209
+
210
+
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.
211
+
212
+
The image uses sensible default environment variables, agreeing to the terms and conditions, setting a rootpath ensured by the image itself, creating a default admin user with username `HDB_ADMIN` and password `password`, and enabled standard streams logging.
213
+
214
+
Just like in the local installation setup, Harper enables the user to specify configuration values using environment variables; these all work the same with the image. For a complete list of CLI configuration values see the [Harper CLI](../../docs/deployments/harper-cli) reference documentation.
215
+
216
+
Using a Docker compatible container manager of choice, the simplest way to get started is using:
217
+
218
+
```bash
219
+
docker pull harperdb/harperdb
220
+
docker run -d \
221
+
-v /Users/harper/hdb:/home/harperdb/hdb \
222
+
-p 9925:9925 \
223
+
-p 9926:9926 \
224
+
harperdb/harperdb
225
+
```
226
+
227
+
The `-v` option will mount the Harper installation to the container host which is useful for development purposes.
228
+
229
+
Now, there should be a running Harper container available just like a local installation. Skip ahead to [Performing a health check](#performing-a-health-check) to learn how to verify your containerize Harper instance is running and complete this getting started guide.
230
+
231
+
## Get Started with Fabric
232
+
233
+
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:
234
+
235
+
- Go to [Fabric](https://fabric.harper.fast) and sign-up for a new account.
236
+
- You will need to agree to the terms of service and verify your email address.
237
+
- 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.
238
+
- You can now create a new Harper cluster or instance:
239
+
- Create a free Harper cluster for trying out Harper.
240
+
- Purchase a Harper cluster with higher performance, scalability, and limits.
241
+
- Add your own local instance to manage everything in one place.
242
+
243
+
After successfully creating a Harper Fabric cluster, take note of the cluster URL and continue to the [Performing a health check](#performing-a-health-check) section to verify your instance.
244
+
245
+
If you have any issues getting started with Fabric, consult the dedicated [Fabric documentation](../../fabric/). If you still need help, join the official Harper community [Discord](https://harper.fast/discord) and get help from the Harper engineering team.
246
+
247
+
## Performing a health check
248
+
249
+
To check if everything is configured correctly and ready to go for development, run a health check using the built-in `/health` endpoint for the Operations API server.
35
250
36
251
:::note
37
252
If you configured a different Operations API port, use that instead of `9925` here.
253
+
254
+
Similarly, if you are using a Harper Fabric cluster, replace the `http://localhost` with the cluster URL.
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:
275
+
</Tabs>
58
276
59
-
- Go to [Fabric](https://fabric.harper.fast) and sign-up for a new account.
60
-
- You will need to agree to the terms of service and verify your email address.
61
-
- Once you have created an account, you can create an organization. This will allow you to collaboratively managing your Harper services with others. This will also define the host domain that will be used.
62
-
- You can now create a new Harper cluster or instance:
63
-
- Create a free Harper cluster for trying out Harper.
64
-
- Purchase a Harper cluster with higher performance, scalability, and limits.
65
-
- Add your own local instance to manage everything in one place.
66
-
- Once you have a Harper cluster, you will be ready to create a new application directly on Fabric, or be ready to deploy an application to Fabric.
277
+
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](./quickstart).
67
278
68
-
Once Harper is running or you are connected to Fabric, we recommend that you walk through the steps of [building your first application](../getting-started/quickstart) and learn more about Harper's concepts and architecture:
279
+
## Additional Resources
69
280
70
-
-[Build your first application](../getting-started/quickstart)
71
-
- Explore the [Core Concepts](../foundations/core-concepts)
72
-
- Learn about [Harper's architecture](../foundations/harper-architecture)
0 commit comments