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
Copy file name to clipboardExpand all lines: docs/deployments/install-harper/index.md
+34-1Lines changed: 34 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,7 +35,40 @@ If you are setting up a production server on Linux, [we have much more extensive
35
35
36
36
## With Docker
37
37
38
-
If you would like to run Harper in Docker, install [Docker Desktop](https://docs.docker.com/desktop/) on your Mac or Windows computer. Otherwise, install the [Docker Engine](https://docs.docker.com/engine/install/) on your Linux server.
38
+
If you would like to run Harper in Docker, install [Docker Desktop](https://docs.docker.com/desktop/) on your Mac or Windows computer. Otherwise, install the [Docker Engine](https://docs.docker.com/engine/install/) on your Linux server. You can then pull the image:
39
+
40
+
```bash
41
+
docker pull harperdb/harperdb
42
+
```
43
+
44
+
Start a container, mount a volume and pass environment variables:
45
+
46
+
```bash
47
+
docker run -d \
48
+
-v <host_directory>:/home/harperdb/hdb \
49
+
-e HDB_ADMIN_USERNAME=HDB_ADMIN \
50
+
-e HDB_ADMIN_PASSWORD=password \
51
+
-e THREADS=4 \
52
+
-e OPERATIONSAPI_NETWORK_PORT=null \
53
+
-e OPERATIONSAPI_NETWORK_SECUREPORT=9925 \
54
+
-e HTTP_SECUREPORT=9926 \
55
+
-p 9925:9925 \
56
+
-p 9926:9926 \
57
+
-p 9933:9933 \
58
+
harperdb/harperdb
59
+
```
60
+
61
+
Here, the `<host_directory>` should be replaced with an actual directory path on your system where you want to store the persistent data. This command also exposes both the Harper Operations API (port 9925) and an additional HTTP port (9926).
62
+
63
+
✅ Quick check:
64
+
65
+
```bash
66
+
curl http://localhost:9925/health
67
+
```
68
+
69
+
:::info
70
+
💡 Why choose Docker: Great for consistent team environments, CI/CD pipelines, or deploying Harper alongside other services.
71
+
:::
39
72
40
73
Once Docker Desktop or Docker Engine is installed, visit our [Docker Hub page](https://hub.docker.com/r/harperdb/harperdb) for information and examples on how to run a Harper container.
Copy file name to clipboardExpand all lines: docs/getting-started/installation.md
+19-72Lines changed: 19 additions & 72 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,97 +1,44 @@
1
1
---
2
-
title: Install Harper
2
+
title: Install and Connect Harper
3
3
---
4
4
5
-
# Install Harper
5
+
# Install and Connect Harper
6
6
7
-
You can get Harper running in minutes.
8
-
Choose the option that fits your workflow:
7
+
The recommended approach for efficiently developing applications with Harper is to install Harper locally for efficient development of an application and deploy it to [Harper Fabric](https://fabric.harper.fast), our distributed data application platform service. However, you can also develop directly in Fabric, if you want to quickly try it out. You can also run a self-hosted Harper server, and manage it with our Fabric studio management UI.
9
8
10
-
-**npm** → best for local development & quick starts.
11
-
-**Docker** → best for containerized environments and team setups.
12
-
-**Raw binary** → best if you need a manual or offline install.
9
+
## Install with npm
13
10
14
-
---
15
-
16
-
## Install with npm (fastest way)
17
-
18
-
Make sure you have [Node.js](https://nodejs.org/) (LTS or newer). Then run:
11
+
The fastest way to get Harper running locally is to install with npm. Make sure you have [Node.js](https://nodejs.org/) (LTS or newer). Then run:
19
12
20
13
```bash
21
14
npm install -g harperdb
22
15
harperdb
23
16
```
24
17
25
-
That’s it! Harper is now running locally.
26
-
The first time, you’ll set up your destination, username, password, and [configuration](../deployments/configuration).
18
+
The first time, you’ll set up your destination, username, password, and [configuration](../deployments/configuration). That’s it! Harper is now running locally.
27
19
28
-
✅ Quick check: open http://localhost:9925or run:
20
+
✅ Quick check: open http://localhost:9925, which will launch the studio UI for managing your local server, or run this for a quick health check:
29
21
30
22
```bash
31
23
curl http://localhost:9925/health
32
24
```
33
25
34
-
:::info
35
-
💡 Why choose npm: It’s the simplest way to try Harper and build apps right from your laptop.
36
-
:::
37
-
38
-
## Install with Docker
39
-
40
-
Want Harper in a container? Pull the image:
41
-
42
-
```bash
43
-
docker pull harperdb/harperdb
44
-
```
45
-
46
-
Start a container, mount a volume and pass environment variables:
47
-
48
-
```bash
49
-
docker run -d \
50
-
-v <host_directory>:/home/harperdb/hdb \
51
-
-e HDB_ADMIN_USERNAME=HDB_ADMIN \
52
-
-e HDB_ADMIN_PASSWORD=password \
53
-
-e THREADS=4 \
54
-
-e OPERATIONSAPI_NETWORK_PORT=null \
55
-
-e OPERATIONSAPI_NETWORK_SECUREPORT=9925 \
56
-
-e HTTP_SECUREPORT=9926 \
57
-
-e CLUSTERING_ENABLED=true \
58
-
-e CLUSTERING_USER=cluster_user \
59
-
-e CLUSTERING_PASSWORD=password \
60
-
-e CLUSTERING_NODENAME=hdb1 \
61
-
-p 9925:9925 \
62
-
-p 9926:9926 \
63
-
-p 9932:9932 \
64
-
harperdb/harperdb
65
-
```
66
-
67
-
Here, the `<host_directory>` should be replaced with an actual directory path on your system where you want to store the persistent data. This command also exposes both the Harper Operations API (port 9925) and an additional HTTP port (9926).
26
+
Harper can also be [installed with our Docker image or you can download Harper for manual or offline installation](../deployments/install-harper).
68
27
69
-
✅ Quick check:
28
+
## Manage and Deploy with Fabric
70
29
71
-
```bash
72
-
curl http://localhost:9925/health
73
-
```
74
-
75
-
:::info
76
-
💡 Why choose Docker: Great for consistent team environments, CI/CD pipelines, or deploying Harper alongside other services.
77
-
:::
78
-
79
-
## Install from Raw Binary
80
-
81
-
Need offline or manual setup? Download the package from [our release index](https://products-harperdb-io.s3.us-east-2.amazonaws.com/index.html), then install:
82
-
83
-
```bash
84
-
npm install -g harperdb-X.X.X.tgz
85
-
harperdb install
86
-
```
87
-
88
-
:::info
89
-
💡 Why choose Raw Binary: Works without Docker, ideal for controlled environments.
90
-
:::
30
+
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:
91
31
92
-
## Next Steps
32
+
- Go to [Fabric](https://fabric.harper.fast) and sign-up for a new account.
33
+
- You will need to agree to the terms of service and verify your email address.
34
+
- 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.
35
+
- You can now create a new Harper cluster or instance:
36
+
- Create a free Harper cluster for trying out Harper.
37
+
- Purchase a Harper cluster with higher performance, scalability, and limits.
38
+
- Add your own local instance to manage everything in one place.
39
+
- 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.
93
40
94
-
Once Harper is running, you can:
41
+
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:
95
42
96
43
-[Build your first application](../getting-started/quickstart)
97
44
- Explore the [Core Concepts](../foundations/core-concepts)
If you are working the Fabric studio UI, you can navigate to your cluster and then to the "Applications" tab. Then choose to "Create New Application" (using the standard application template). This will create a new application based on the `application-template`.
19
+
18
20
## Creating our first Table
19
21
20
22
The core of a Harper application is the database, so let's create a database table.
21
23
22
-
A quick and expressive way to define a table is through a [GraphQL Schema](https://graphql.org/learn/schema). Using your editor of choice, edit the file named `schema.graphql` in the root of the application directory, `my-app`, that we created above. To create a table, we will need to add a `type` of `@table` named `Dog` (and you can remove the example table in the template):
24
+
A quick and expressive way to define a table is through a [GraphQL Schema](https://graphql.org/learn/schema). Using your editor of choice, edit the file named `schema.graphql` in the root of the application directory, `my-app`, that we created above. In the Fabric UI, simply click on `schema.graphql` to start editing it. To create a table, we will need to add a `type` of `@table` named `Dog` (and you can remove the example table in the template):
23
25
24
26
```graphql
25
27
typeDog@table {
@@ -43,6 +45,8 @@ Now we tell Harper to run this as an application:
43
45
harperdbdev . # tell Harper cli to run current directory as an application in dev mode
44
46
```
45
47
48
+
If you are using the Fabric UI, you can click "Restart Cluster" to apply these schema changes.
49
+
46
50
Harper will now create the `Dog` table and its `id` attribute we just defined. Not only is this an easy way to create a table, but this schema is included in our application, which will ensure that this table exists wherever we deploy this application (to any Harper instance).
47
51
48
52
## Adding Attributes to our Table
@@ -62,6 +66,8 @@ This will ensure that new records must have these properties with these types.
62
66
63
67
Becauseweran `harperdbdev .` earlier (dev mode), Harperisnowmonitoringthecontentsofourapplicationdirectoryforchangesandreloadingwhentheyoccur. Thismeansthatoncewesaveourschema file with these new attributes, Harper will automatically reload our application, read `my-app/schema.graphql` and update the `Dog` table and attributes we just defined. The dev mode will also ensure that any logging or errors are immediately displayed in the console (rather only in the log file).
64
68
69
+
If you are running in Fabric, again, you can click "Restart Cluster" to apply any changes. You can navigate to the "Databases" page to see your new table and add records to it.
70
+
65
71
As a document database, Harper supports heterogeneous records, so you can freely specify additional properties on any record. If you do want to restrict the records to only defined properties, you can always do that by adding the sealed directive:
66
72
67
73
```graphql
@@ -88,7 +94,9 @@ type Dog @table @export {
88
94
}
89
95
```
90
96
91
-
BydefaulttheapplicationHTTPserverportis `9926` (this can be [configured here](../deployments/configuration#http)), so the local URL would be `http://localhost:9926/Dog/` with a full REST API. We can PUT or POST data into this table using this new path, and then GET or DELETE from it as well (you can even view data directly from the browser). If you have not added any records yet, we could use a PUT or POST to add a record. PUT is appropriate if you know the id, and POST can be used to assign an id:
97
+
Foralocalinstance, bydefaulttheapplicationHTTPserverportis `9926` (this can be [configured here](../deployments/configuration#http)), so the local URL would be `http://localhost:9926/Dog/` with a full REST API. In Fabric, a public hostname/URL will be created, and you can go to the "Config" page to see your "Application URL", which should look like `your-cluster.your-org.harperfabric.com`. You can directly query this with an HTTPS URL, by including authentication information.
98
+
99
+
We can PUT or POST data into this table using this new path, and then GET or DELETE from it as well (youcanevenviewdatadirectlyfromthebrowser). Ifyouhavenotaddedanyrecordsyet, wecoulduseaPUTorPOSTtoaddarecord. PUTisappropriateifyouknowtheid, andPOSTcanbeusedtoassignanid:
92
100
93
101
```bash
94
102
curl -XPOSThttp://localhost:9926/Dog/ \
@@ -101,13 +109,27 @@ curl -X POST http://localhost:9926/Dog/ \
101
109
}'
102
110
```
103
111
112
+
Or in Fabric:
113
+
114
+
```bash
115
+
curl -X POST https://your-cluster.your-org.harperfabric.com/Dog/ \
With this a record will be created and the auto-assigned id will be available through the `Location` header. If you added a record, you can visit the path `/Dog/<id>` to view that record. Alternately, the curl command `curl http://localhost:9926/Dog/<id>` will achieve the same thing.
105
127
106
128
## Authenticating Endpoints
107
129
108
130
Now that you've created your first API endpoints, it's important to ensure they're protected. Without authentication, anyone could potentially access, misuse, or overload your APIs, whether by accident or malicious intent. Authentication verifies who is making the request and enables you to control access based on identity, roles, or permissions. It’s a foundational step in building secure, reliable applications.
109
131
110
-
Endpoints created with Harper automatically support `Basic`, `Cookie`, and `JWT` authentication methods. See the documentation on [security](../developers/security/) formoreinformationondifferentlevelsofaccess.
132
+
Endpoints created with Harper automatically support `Basic` authentication, JWT authentication, and maintaining authentication with cookie-based session. See the documentation on [security](../developers/security/) for more information on different levels of access.
111
133
112
134
By default, Harper also automatically authorizes all requests from loopback IP addresses (from the same computer) as the superuser, to make it simple to interact for local development. If you want to test authentication/authorization, or enforce stricter security, you may want to disable the [`authentication.authorizeLocal` setting](../deployments/configuration#authentication).
Congratulations, you now have created a secure database application backend with a table, a well-defined structure, access controls, and a functional REST endpoint with query capabilities! See the [REST documentation for more information on HTTP access](../developers/rest) and see the [Schema reference](../developers/applications/defining-schemas) for more options for defining schemas.
186
+
In Fabric, you can directly open such URLs directly in the browser, where the browser will prompt you for your username and password:
Congratulations, you now have created a secure database application backend with a table, a well-defined structure, access controls, and a functional REST endpoint with query capabilities! See the [REST documentation for more information on HTTP access](../developers/rest) and see the [Schema reference](../developers/applications/defining-schemas) for more options for defining schemas. If you were developing locally, you are ready to deploy to Fabric.
165
194
166
195
> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../reference/graphql).
167
196
197
+
## Deploy to Fabric
198
+
199
+
In the recommended flow, you have been developing your application locally, but now you are ready to deploy your application to Fabric. The recommended way of doing this is to commit your code to a git repository, where Harper can directly pull your application from the repository and run it. To get started, it is easiest to put this in a public repository for ease of access and deployment. Once you have committed your code to a git repository, you can go to the "Applications" page, and select "Import Application". You can then enter the URL of your repository and Fabric will deploy in on your cluster. We also recommend using git tags and deploying by tag name for control over application versioning. You can import and deploy a tag in a repository using import of a URL like "git+https://[email protected]/my-org/my-app.git#semver:v1.0.27".
200
+
201
+
You can also deploy to fabric using the CLI. With this approach, you can "push" your application code into your Fabric cluster. From the command line, go into your application directory and run:
202
+
203
+
```bash
204
+
harperdb deploy_component \
205
+
project=<my-app-name> \
206
+
package=<path-to-project> \ # optional, uses cwd if not specified
207
+
restart=true \
208
+
replicated=true # deploy to your whole cluster
209
+
```
210
+
211
+
Once you have deployed and restarted, your application is live and ready to be used by the world!
212
+
168
213
## Key Takeaway
169
214
170
215
Harper's schema-driven approach means you can build production-ready APIs in minutes, not hours. Start with pure schema definitions to get 90% of your functionality, then add custom code only where needed. This gives you the best of both worlds: rapid development with the flexibility to customize when required.
Copy file name to clipboardExpand all lines: docs/index.mdx
+5-2Lines changed: 5 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,18 +10,21 @@ import CustomDocCardList from '@site/src/components/CustomDocCardList';
10
10
[Connect with our team!](https://www.harpersystems.dev/contact)
11
11
:::
12
12
13
-
Welcome to the Harper Documentation! Here, you'll find all things Harper, and everything you need to get started, troubleshoot issues, and make the most of our platform.
13
+
Harper is an all-in-one backend technology that fuses database technologies, caching, application hosting, and messaging functions into a single system. Unlike traditional architectures where each piece runs independently and incurs extra costs and latency from serialization and network operations between processes, Harper systems can handle workloads seamlessly and efficiently.
14
+
15
+
Here, you'll find all things Harper, and everything you need to get started, troubleshoot issues, and make the most of our platform.
14
16
15
17
## Getting Started
16
18
19
+
The recommended approach for efficiently developing applications with Harper is to develop locally and deploy them to Harper Fabric, our distributed data application platform service. Our getting started guide will walk you through how to install Harper locally, sign up for Fabric service, build a simple application and deploy it.
17
20
<CustomDocCardList
18
21
columns={3}
19
22
items={[
20
23
{
21
24
type: 'link',
22
25
href: '/docs/getting-started/installation',
23
26
label: 'Install Harper',
24
-
description: 'Pick the installation method that best suits your environment',
27
+
description: 'Learn how to install Harper locally, sign up for Fabric and deploy to it.',
0 commit comments