Skip to content

Backport quickstart guide to 4.6, and add a card for building an application #350

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
Ethan-Arrowood merged 1 commit into from
Oct 13, 2025
Merged

Backport quickstart guide to 4.6, and add a card for building an application #350

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 6 additions & 6 deletions docs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,15 @@ The recommended approach for efficiently developing applications with Harper is
},
{
type: 'link',
href: '/docs/foundations/harper-architecture',
label: 'Harper Architecture',
description: 'Learn about what Harper is composed of, and how they work together',
href: '/docs/getting-started/quickstart',
label: 'Install Harper',
description: 'Learn how to build your first Harper application.',
},
{
type: 'link',
href: '/docs/foundations/core-concepts',
label: 'Harper Concepts',
description: "Learn about Harper's fundamental concepts and how they interact",
href: '/docs/foundations/harper-architecture',
label: 'Harper Architecture',
description: 'Learn about what Harper is composed of, and how they work together',
},
]}
/>
Expand Down
91 changes: 19 additions & 72 deletions versioned_docs/version-4.6/getting-started/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,97 +1,44 @@
---
title: Install Harper
title: Install and Connect Harper
---

# Install Harper
# Install and Connect Harper

You can get Harper running in minutes.
Choose the option that fits your workflow:
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.

- **npm** → best for local development & quick starts.
- **Docker** → best for containerized environments and team setups.
- **Raw binary** → best if you need a manual or offline install.
## Install with npm

---

## Install with npm (fastest way)

Make sure you have [Node.js](https://nodejs.org/) (LTS or newer). Then run:
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:

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

That’s it! Harper is now running locally.
The first time, you’ll set up your destination, username, password, and [configuration](../deployments/configuration).
The first time, you’ll set up your destination, username, password, and [configuration](../deployments/configuration). That’s it! Harper is now running locally.

✅ Quick check: open http://localhost:9925 or run:
✅ 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:

```bash
curl http://localhost:9925/health
```

:::info
💡 Why choose npm: It’s the simplest way to try Harper and build apps right from your laptop.
:::

## Install with Docker

Want Harper in a container? Pull the image:

```bash
docker pull harperdb/harperdb
```

Start a container, mount a volume and pass environment variables:

```bash
docker run -d \
-v <host_directory>:/home/harperdb/hdb \
-e HDB_ADMIN_USERNAME=HDB_ADMIN \
-e HDB_ADMIN_PASSWORD=password \
-e THREADS=4 \
-e OPERATIONSAPI_NETWORK_PORT=null \
-e OPERATIONSAPI_NETWORK_SECUREPORT=9925 \
-e HTTP_SECUREPORT=9926 \
-e CLUSTERING_ENABLED=true \
-e CLUSTERING_USER=cluster_user \
-e CLUSTERING_PASSWORD=password \
-e CLUSTERING_NODENAME=hdb1 \
-p 9925:9925 \
-p 9926:9926 \
-p 9932:9932 \
harperdb/harperdb
```

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).
Harper can also be [installed with our Docker image or you can download Harper for manual or offline installation](../deployments/install-harper).

✅ Quick check:
## Manage and Deploy with Fabric

```bash
curl http://localhost:9925/health
```

:::info
💡 Why choose Docker: Great for consistent team environments, CI/CD pipelines, or deploying Harper alongside other services.
:::

## Install from Raw Binary

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:

```bash
npm install -g harperdb-X.X.X.tgz
harperdb install
```

:::info
💡 Why choose Raw Binary: Works without Docker, ideal for controlled environments.
:::
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:

## Next Steps
- Go to [Fabric](https://fabric.harper.fast) 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 managing 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.
- 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.

Once Harper is running, you can:
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:

- [Build your first application](../getting-started/quickstart)
- Explore the [Core Concepts](../foundations/core-concepts)
Expand Down
58 changes: 53 additions & 5 deletions versioned_docs/version-4.6/getting-started/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,20 @@ Now that you've set up Harper, let's build a simple API. Harper lets you build p

## Setup Your Project

Start by cloning the Harper application template:
If you have installed Harper locally, start by cloning the Harper application template:

```bash
git clone https://github.com/HarperDB/application-template my-app
cd my-app
```

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`.

## Creating our first Table

The core of a Harper application is the database, so let's create a database table.

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):
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):

```graphql
type Dog @table {
Expand All @@ -43,6 +45,8 @@ Now we tell Harper to run this as an application:
harperdb dev . # tell Harper cli to run current directory as an application in dev mode
```

If you are using the Fabric UI, you can click "Restart Cluster" to apply these schema changes.

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).

## Adding Attributes to our Table
Expand All @@ -62,6 +66,8 @@ This will ensure that new records must have these properties with these types.

Because we ran `harperdb dev .` earlier (dev mode), Harper is now monitoring the contents of our application directory for changes and reloading when they occur. This means that once we save our schema 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).

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.

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:

```graphql
Expand All @@ -88,7 +94,9 @@ type Dog @table @export {
}
```

By default the application HTTP server port is `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:
For a local instance, by default the application HTTP server port is `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.

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:

```bash
curl -X POST http://localhost:9926/Dog/ \
Expand All @@ -101,13 +109,27 @@ curl -X POST http://localhost:9926/Dog/ \
}'
```

Or in Fabric:

```bash
curl -X POST https://your-cluster.your-org.harperfabric.com/Dog/ \
-H "Content-Type: application/json" \
-H "Authentication: Basic <base64 encoded user:pass>"
-d '{
"name": "Harper",
"breed": "Labrador",
"age": 3,
"tricks": ["sits"]
}'
```

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.

## Authenticating Endpoints

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.

Endpoints created with Harper automatically support `Basic`, `Cookie`, and `JWT` authentication methods. See the documentation on [security](../developers/security/) for more information on different levels of access.
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.

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).

Expand Down Expand Up @@ -161,10 +183,36 @@ http://localhost:9926/Dog/?breed=Labrador
http://localhost:9926/Dog/?breed=Husky&name=Balto&select(id,name,breed)
```

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.
In Fabric, you can directly open such URLs directly in the browser, where the browser will prompt you for your username and password:

```
https://your-cluster.your-org.harperfabric.com/Dog/?name=Harper
...
```

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.

> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../reference/graphql).

## Deploy to Fabric

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".

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:

```bash
harperdb deploy_component \
project=<my-app-name> \
package=<path-to-project> \ # optional, uses cwd if not specified
target=<your-cluster.your-org.harperfabric.com> \
username=<username> \
password=<password> \
restart=true \
replicated=true # deploy to your whole cluster
```

Once you have deployed and restarted, your application is live and ready to be used by the world!

## Key Takeaway

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.
26 changes: 14 additions & 12 deletions versioned_docs/version-4.6/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,26 +16,28 @@ Here, you'll find all things Harper, and everything you need to get started, tro

## Getting Started

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.

<CustomDocCardList
columns={3}
items={[
{
type: 'link',
href: '/docs/getting-started/installation',
label: 'Install Harper',
description: 'Pick the installation method that best suits your environment',
description: 'Learn how to install Harper locally, sign up for Fabric and deploy to it.',
},
{
type: 'link',
href: '/docs/foundations/harper-architecture',
label: 'Harper Architecture',
description: 'Learn about what Harper is composed of, and how they work together',
href: '/docs/getting-started/quickstart',
label: 'Install Harper',
description: 'Learn how to build your first Harper application.',
},
{
type: 'link',
href: '/docs/foundations/core-concepts',
label: 'Harper Concepts',
description: "Learn about Harper's fundamental concepts and how they interact",
href: '/docs/foundations/harper-architecture',
label: 'Harper Architecture',
description: 'Learn about what Harper is composed of, and how they work together',
},
]}
/>
Expand All @@ -47,32 +49,32 @@ Here, you'll find all things Harper, and everything you need to get started, tro
items={[
{
type: 'link',
href: 'docs/developers/applications/',
href: '/docs/developers/applications/',
label: 'Harper Applications',
description: 'Build your a fully featured Harper Component with custom functionality',
},
{
type: 'link',
href: 'docs/developers/rest',
href: '/docs/developers/rest',
label: 'REST Queries',
description: 'The recommended HTTP interface for data access, querying, and manipulation',
},
{
type: 'link',
href: 'docs/developers/operations-api/',
href: '/docs/developers/operations-api/',
label: 'Operations API',
description: 'Configure, deploy, administer, and control your Harper instance',
},
{
type: 'link',
href: 'docs/developers/replication/',
href: '/docs/developers/replication/',
label: 'Clustering & Replication',
description:
'The process of connecting multiple Harper databases together to create a database mesh network that enables users to define data replication patterns.',
},
{
type: 'link',
href: 'docs/administration/harper-studio/',
href: '/docs/administration/harper-studio/',
label: 'Explore the Harper Studio',
description:
'The web-based GUI for Harper. Studio enables you to administer, navigate, and monitor all of your Harper instances in a simple, user friendly interface.',
Expand Down