diff --git a/docs/foundations/core-concepts.md b/docs/foundations/core-concepts.md deleted file mode 100644 index 8ef3113d..00000000 --- a/docs/foundations/core-concepts.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Core Concepts ---- - -# Core Concepts - -Before you build your first app with Harper, it helps to understand a few key ideas. These concepts show you how Harper is structured and why it’s flexible enough to power everything from a quick proof-of-concept to a production-ready platform. - -## Components - -**Components** are the building blocks of Harper. -They’re JavaScript-based modules that extend Harper’s core, and they can talk directly to Harper’s [Global APIs](../reference/globals) (databases, tables, resources). - -Because components can build on top of each other, they give you composability. For example, both [Applications](../developers/applications/) and [Plugins](../reference/components/plugins) are just kinds of components: - -- **Plugins** add individual capabilities, like defining tables or serving static assets. -- **Applications** pull multiple plugins and resources together into a complete product. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring up a backend from scratch, you can piece together pre-built functionality and get to working endpoints fast. -::: - -## Applications (a type of Component) - -An **application** is a special kind of component that pulls everything together. -Applications rely on plugins to do the work: - -- Use `graphqlSchema` to define your data tables. -- Add `rest` to query that data instantly. -- Plug in `static` to serve files or front-end assets. - -You can even run full frameworks like [Next.js](https://github.com/HarperDB/nextjs) or [Apollo](https://github.com/HarperDB/apollo) as Harper applications. - -:::info -πŸ’‘ **Why it matters:** Applications are how you ship real products on Harper. They let you stitch together resources, APIs, and UI in one place. -::: - -## Plugins - -**Plugins** are a special kind of component that are not meant to run standalone, but instead add features to applications or other components. These were originally called **extensions** (and the [extension API](../reference/components/extensions) is still supported), but the new [plugin API](../reference/components/plugins) is simultaneously a simplification and extensibility upgrade. - -Examples you’ll see in the ecosystem include: - -- **Built in plugins**: These are embedded in Harper and work out of the box. Examples include [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) for database and table definitions, [rest](../reference/components/built-in-extensions#rest) for RESTful access to your data, and [static](../reference/components/built-in-extensions#static) for serving files or frontend assets. - -- **Custom plugins**: These live outside of Harper and are installed from GitHub or npm. Harper supports a few official ones, and the ecosystem may include community plugins as well. Examples include [@harperdb/nextjs](https://github.com/HarperDB/nextjs) for Next.js integration and [@harperdb/apollo](https://github.com/HarperDB/apollo) for Apollo GraphQL. - -:::info -πŸ’‘ **Why it matters:** Plugins give Harper its flexibility. You can compose them into applications to get powerful functionality without writing boilerplate yourself. -::: - -## Resources - -**Resources** are Harper’s data layer and are implemented using the [`Resource`](../reference/resources/) class. -They represent databases, tables, and other data entities, and they provide a unified API for accessing, querying, modifying, and monitoring records. - -At the simplest level, resources let you: - -- Define schemas and tables for your application data. -- Query and update that data through Harper’s APIs. -- Extend the base `Resource` class with JavaScript to define custom data sources or behaviors. - -Each `Resource` instance can represent a single record or a collection of records at a given point in time. -Static methods on the `Resource` class handle common operations like parsing paths, running transactions, and enforcing access controls, while instance methods give you a transactional view of individual records. - -:::info -πŸ’‘ **Why it matters:** Whether you’re working with standard tables or custom-defined resources, everything in Harper’s data layer builds on the same model. This gives you consistency when modeling data and flexibility to extend it with your own logic. For full details, see the [Resource reference documentation](../reference/resources/). -::: - -## Server - -At the edge of Harper is the **server layer**, which connects your data to the outside world. Harper supports REST/HTTP, WebSockets, MQTT, and more. A single resource can be available through multiple protocols at onceβ€”so the same table can power a real-time dashboard, a mobile app, and a backend API. - -:::info -πŸ’‘ **Why it matters:** You don’t have to choose between protocols. One data model, many ways to access it. -::: - ---- - -βœ… With these concepts in mind, you’re ready to [build your first application](../getting-started/quickstart). That’s where you’ll see how Components, Resources, and Plugins come together in practice. diff --git a/docs/foundations/harper-architecture.md b/docs/foundations/harper-architecture.md deleted file mode 100644 index 0c6dfb28..00000000 --- a/docs/foundations/harper-architecture.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Harper Architecture ---- - -# Harper Architecture - -Before diving deep into APIs and configuration, it helps to understand the big picture of how Harper works. -Harper uses a **three-layer architecture** designed for distributed, edge-first computing. Each layer builds on the next, letting you start simple and scale as your app grows. - -![](/img/v4.6/harper-architecture.png) - -At a high level: - -- **Core services** handle data, networking, and files. -- **Plugins** layer in reusable features (REST, GraphQL, Next.js, etc.). -- **Applications** bring everything together to deliver user-facing functionality. - -:::info -πŸ’‘ **Why it matters:** You focus on building your app, while Harper takes care of scaling, networking, and consistency behind the scenes. -::: - ---- - -## Core Services - -Harper ships with three essential services: - -- **Database** β†’ Fast storage, queries, and transactions. -- **Networking** β†’ REST/HTTP, WebSockets, MQTT, and cluster communication. -- **Component Management** β†’ The system that loads, configures, and connects components (applications, plugins, resources) so they work together consistently. - -Think of these as Harper’s foundationβ€”every extension and app builds on them. - ---- - -## Applications & Extensions - -Most of your work will happen here. - -### Applications - -Applications sit at the top layer. They’re where you implement user-facing features. Examples: - -- A **Next.js app** served directly from Harper. -- A **basic app** from the [Getting Started guide](../getting-started/quickstart) that defines a schema, adds a table, and automatically exposes REST endpoints with the `rest` extension. - -Applications don’t re-invent core logicβ€”they declare the plugins they need. - -### Component Configuration - -Every Harper project starts with a **root configuration**. -This configuration declares which components (applications, plugins/extensions, resources) should be loaded and how they should be initialized. - -Some components are self-contained, while others include configuration that ties into additional components. For example: - -- An application in the root config might load the `rest` plugin. -- The `rest` plugin exposes data from the database, so its configuration links to `graphqlSchema`. -- `graphqlSchema` defines the tables that the database service makes available. - -This layering of configuration is what makes Harper composable: by declaring one component in your root config, you can enable entire sets of functionality. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring everything manually, you declare the root config, and Harper initializes the components in the right relationships. -::: - ---- - -## Resource API - -At the heart of Harper is the **Resource API**. It gives you a unified, consistent way to interact with data. - -- `get()` β†’ fetch data -- `post()` β†’ create data or trigger actions -- `put()` β†’ replace existing data -- `patch()` β†’ update part of a record - -Every call is wrapped in a transaction, so multi-table operations stay consistent without extra boilerplate. - -For the complete API, see the [Resource reference](../reference/resources). - -:::info -πŸ’‘ **Why it matters:** You can build reliable featuresβ€”like signups, payments, or analyticsβ€”without hand-rolling transaction logic. -::: - ---- - -## Transaction Model - -All requests run inside automatic transactions: - -- Read/write across multiple tables in a single request. -- Automatic change tracking. -- Guaranteed consistency at commit. - -:::info -πŸ’‘ **Why it matters:** You don’t have to think about database race conditions or half-finished writesβ€”Harper guarantees integrity by default. -::: - ---- - -βœ… With this architecture in mind, you can see how Harper scales from β€œhello world” to complex, distributed applications. Next, try putting it into practice by [building your first app](../developers/applications/). diff --git a/docs/foundations/use-cases.md b/docs/foundations/use-cases.md deleted file mode 100644 index 642a74f7..00000000 --- a/docs/foundations/use-cases.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Harper Use Cases ---- - -# Harper Use Cases - -Harper is designed to cut out infrastructure complexity so you can move faster. -Here are some common ways developers use Harper in production today β€” each one showing how Harper’s architecture translates into real-world outcomes. - ---- - -## RESTful APIs for Distributed & Cached Data - -**Great for:** web apps, mobile apps, data-heavy platforms. - -Harper’s most common use case is exposing distributed, cached data over a RESTful interface. -This lets you serve complex or large-scale datasets efficiently, with built-in caching and global distribution. - -- Define your schema with the `graphqlSchema` plugin. -- Expose it instantly over REST using the `rest` plugin. -- Take advantage of Harper’s caching layer to serve hot data without extra infrastructure. -- Power both web and mobile applications from the same API. - -:::info -πŸ’‘ **Why it matters:** Instead of bolting a cache or API layer onto a database, Harper gives you a unified system that scales for real-world apps. -::: - ---- - -## Online Catalogs & Content Delivery - -**Great for:** e-commerce sites, real estate listings, media & content platforms. - -Harper’s distributed architecture makes your pages load fast worldwide, improving **SEO** and **conversion rates**. - -- Host your frontend directly with the [Next.js Extension](https://github.com/HarperDB/nextjs). -- Support any framework using Harper’s extension system. -- Use Harper’s built-in caching + JavaScript layer to [server-side render pages](https://www.harpersystems.dev/development/tutorials/server-side-rendering-with-multi-tier-cache). -- Keep pages instantly fresh with built-in [WebSocket connections](../developers/real-time#websockets). - -:::info -πŸ’‘ **Why it matters:** Instead of stitching together CDN + DB + API layers, you deliver catalog and content experiences from a single platform. -::: - ---- - -## Data Delivery Networks - -**Great for:** live sports updates, flight tracking, software updates. - -Harper combines **messaging**, **data storage**, and **application logic** in one system. That means: - -- Push real-time updates directly to clients. -- Process and store data without leaving Harper. -- Eliminate extra message brokers or caching systems. - -Explore the [real-time docs](../developers/real-time) to see how it works. - -:::info -πŸ’‘ **Why it matters:** You can build real-time data services in hours, not weeks, with fewer moving parts to manage. -::: - ---- - -## Edge Inference Systems - -**Great for:** IoT pipelines, sensor networks, edge AI. - -Normally, capturing and analyzing streams at the edge requires a patchwork of tools. Harper simplifies this with: - -- **Self-healing connections** that keep data flowing even in flaky environments. -- The same Harper runtime running at both layers. - -:::info -πŸ’‘ **Why it matters:** One consistent stack across edge and cloud makes AI/ML inference faster, cheaper, and easier to scale. -::: - ---- - -βœ… Want to explore more? [Contact us](https://www.harpersystems.dev/contact) and we’ll walk you through building your own use case. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md deleted file mode 100644 index f7cb1cf3..00000000 --- a/docs/getting-started/installation.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Install and Connect Harper ---- - -# Install and Connect Harper - -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. - -## Install with npm - -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 -``` - -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, 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 -``` - -Harper can also be [installed with our Docker image or you can download Harper for manual or offline installation](../deployments/install-harper). - -## Manage and Deploy 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](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 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) -- Learn about [Harper's architecture](../foundations/harper-architecture) -- Review [Configuration options](../deployments/configuration) - -:::info -Need help? Please don’t hesitate to [reach out](https://www.harpersystems.dev/contact). -::: diff --git a/docs/index.mdx b/docs/index.mdx index e6e11ca2..97b2b16c 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -19,31 +19,7 @@ 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. - - +The best way to get started using Harper is to head over to the [Learn](../learn/) section and work through the Getting Started and Developer guides. ## Building with Harper @@ -75,12 +51,5 @@ The recommended approach for efficiently developing applications with Harper is 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/', - 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.', - }, ]} /> diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 4b29211d..4a48378d 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -59,6 +59,17 @@ const config: Config = { onBrokenMarkdownLinks: 'warn', plugins: [ + // Learn documentation + [ + '@docusaurus/plugin-content-docs', + { + id: 'learn', + path: 'learn', + routeBasePath: 'learn', + sidebarPath: './sidebarsLearn.ts', + editUrl: 'https://github.com/HarperDB/documentation/blob/main/', + }, + ], // Main documentation [ '@docusaurus/plugin-content-docs', @@ -305,6 +316,13 @@ const config: Config = { href: 'https://www.harper.fast/', }, items: [ + { + type: 'docSidebar', + sidebarId: 'learnSidebar', + docsPluginId: 'learn', + position: 'left', + label: 'Learn', + }, { type: 'docSidebar', sidebarId: 'docsSidebar', diff --git a/learn/administration/coming-soon.md b/learn/administration/coming-soon.md new file mode 100644 index 00000000..d30962bd --- /dev/null +++ b/learn/administration/coming-soon.md @@ -0,0 +1 @@ +# Coming Soon diff --git a/learn/developers/coming-soon.md b/learn/developers/coming-soon.md new file mode 100644 index 00000000..d30962bd --- /dev/null +++ b/learn/developers/coming-soon.md @@ -0,0 +1 @@ +# Coming Soon diff --git a/docs/getting-started/quickstart.md b/learn/getting-started/_old-create-your-first-application.mdx similarity index 96% rename from docs/getting-started/quickstart.md rename to learn/getting-started/_old-create-your-first-application.mdx index e8956d0e..992cec95 100644 --- a/docs/getting-started/quickstart.md +++ b/learn/getting-started/_old-create-your-first-application.mdx @@ -1,12 +1,4 @@ ---- -title: Create Your First Application ---- - -# Create Your First Application - -Now that you've set up Harper, let's build a simple API. Harper lets you build powerful APIs with minimal effort. In just a few minutes, you'll have a functional REST API with automatic validation, indexing, and queryingβ€”all without writing a single line of code. - -## Setup Your Project +## Initializing the Harper Application If you have installed Harper locally, start by cloning the Harper application template: diff --git a/learn/getting-started/create-your-first-application.mdx b/learn/getting-started/create-your-first-application.mdx new file mode 100644 index 00000000..849de355 --- /dev/null +++ b/learn/getting-started/create-your-first-application.mdx @@ -0,0 +1,221 @@ +--- +title: Create Your First Application +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +With Harper successfully installed and setup, let's dive into building your first Harper Application, a simple REST API. Harper lets you build powerful APIs with minimal effort. In just a few minutes, you'll have a functional REST API with automatic validation, indexing, and queryingβ€”all without writing a single line of code. + +## What You Will Learn + +- Overview of Harper architecture +- What are Harper core services, plugins, and applications +- How to run a Harper application +- How to define a table using schemas +- How to automatically create a REST API from a table schema +- How to interact with the table using the generated REST API + - Create, Read, Update, and Delete data + +## Prerequisites + +- Working Harper Installation + - Complete previous guide [Install and Connect Harper](./install-and-connect-harper) + +## Harper Architecture + +Before diving into building your first Harper application, it is important to understand a bit about Harper's architecture. The simplest way to think about Harper is as a stack. + +``` +┏━━━━━━━━━━━━━━━━━━┓ +┃ Applications ┃ +┠──────────────────┨ +┃ Plugins ┃ +┃ - rest ┃ +┃ - graphqlSchema ┃ +┃ - ... ┃ +┠──────────────────┨ +┃ Core Services: ┃ +┃ - database ┃ +┃ - networking ┃ +┃ - component ┃ +┃ management ┃ +┗━━━━━━━━━━━━━━━━━━┛ +``` + +At the bottom are the **core services** that make up the foundation of the Harper platform. This includes the high-performance **database**, extensible **networking** middleware, and **component** management system. Components are extensions of the core Harper system, and are further classified as **plugins** and **applications**. + +**Plugins** come next in the stack. Plugins have access to APIs exposing many of Harper's core services, and are capable of implementing more advanced features than what the core services provide. Many of Harper's features are implemented as **built-in plugins**. Additional features can be implemented as **custom plugins**. In this guide, we'll be demonstrating some of Harper's built-in plugins `graphqlSchema` and `rest`. Later guides will demonstrate many more. + +And finally, the top of the stack are **applications**. This is where any user-facing functionality is implemented. Applications use plugins to implement their business logic. Everything from database table schemas, to web applications. + +The key difference between plugins and applications is that plugins enable the functionality, and applications implement it. Its similar to that of a front-end framework. React on its own doesn't actually do anything, you actually need to build a "React App" for it to do anything meaningful. + +## Initialize the Harper Application + +Without further a do, lets get started building your first Harper application! + +:::tip +Throughout this guide you'll see tabs like the ones just below that provide different instructions based on your installation choice from the previous guide. The "Local Installation" is for both globally installed and containerized Harper applications; the point being you have access to the file system. The "Fabric" option is for the Harper Fabric platform service deployment and will involve managing applications and modifying files through the Fabric UI within your browser. + +These tabs are all synchronized together, so select your installation method and enjoy learning how to build your first Harper application! +::: + + + + +Get started by cloning the [`HarperFast/create-your-first-application`](https://github.com/HarperFast/create-your-first-application) repo and opening it your editor of choice. If you have installed Harper using a container, make sure to run this within the `dev/` directory that the container was mounted to. + +```bash +git clone https://github.com/HarperFast/create-your-first-application.git first-harper-app +``` + + + + +From the Cluster page, navigate to the Applications tab and click on "New Application" on the left-hand sidebar. + +Give the application a name such as "first-harper-app", and then click on the "Import" tab. + +Specify `https://github.com/HarperFast/create-your-first-application` in the "Git Repository URL" field. + +Keep the "Install Command" empty and the "Authorization" as "Public Access". + +Finally, click the "Import Application" button and wait for the application to be instantiated. + + + + +## Create a Table + +The core of most Harper applications is the data. Harper's data system is made up of databases and tables. There are many ways to create them, and the primary method is to use a GraphQL-like syntax to define table schemas. These schemas are not true GraphQL, and you don't have to use GraphQL for querying neither. + + + + +Open `schema.graphql` in your text editor. + + + + +Navigate to the Files tab for your new application and open the `schema.graphql` file. + + + + +Within `schema.graphql`, add: + +```graphql +type Dog @table { + id: ID @primaryKey +} +``` + +Harper has defined custom directives, such as `@table` and `@primaryKey`, to specify special behavior for the table schema. + +The `@table` directive is what instructs Harper that this is in fact a table schema versus an arbitrary type. + +The `@primaryKey` directive specifies which attribute is meant to be the primary key for indexing. + +Next, lets add some more properties to the schema. + +```graphql +type Dog @table { + id: ID @primaryKey + name: String + breed: String + age: Int +} +``` + +Harper's schema system piggybacks off of the standard GraphQL field types such as `String`, `Int`, and many more. + +:::info +For a full list of field types, see the [Schema Field Types](../../docs/developers/applications/defining-schemas#field-types) reference documentation. +::: + +Now you have a schema for a `Dog` table with four attributes `id`, `name`, `breed`, and `age`. + +The next step is to tell Harper about your schema file. + +Open the `config.yaml` file and add the following: + +```yaml +graphqlSchema: + files: 'schema.graphql' +``` + +The `config.yaml` file is how Harper applications configure plugins. The `graphqlSchema` plugin is built-in to Harper so there is no additional steps needed to configure it, but custom plugins do require installing dependencies (more on that in another guide). + +The `files` property allows you to specify a file glob pattern for the plugin. In this case, we are only specifying a single file, but you can specify any glob pattern here too. + +With the `schema.graphql` and `config.yaml` in place, now its time to run your application for the first time. + +## Running your Application + + + + +If Harper is still running, shut it down using CTRL/CMD + C for a foreground process or `harperdb stop` for a background process. + +Within your application directory, open a command line and run `harperdb dev .` + +TODO: Insert description of `dev` command + + + + +Click the restart button + +TODO: Fill in actual steps for fabric here + + + + +## Interacting with the `Dog` table + + + + +Locally, using the Operations API via the CLI and curl + +Inspect the database and table using `describe_database` and `describe_table` + +Add a record using `insert` + +Hint at additional operations apis for other CRUD ops but encourage the user to read on for REST API guide + + + + +Using the Database UI + +Learn about the database and table + +Add a record manually + +Hint at additional methods for CRUD ops but encourage the user to read on for REST API guide + + + + +## Enabling automatic REST API generation + +Add @export to schema +Edit config.yaml with rest: true + +## Interacting with the `/Dog` API + +### Creating entries with POST and PUT + +### Reading entries with GET + +#### Querying by attribute + +### Updating entries with PUT and PATCH + +### Deleting entries with DELETE + +## Key Take Aways + +## Additional Resources \ No newline at end of file diff --git a/learn/getting-started/install-and-connect-harper.mdx b/learn/getting-started/install-and-connect-harper.mdx new file mode 100644 index 00000000..b9531a7e --- /dev/null +++ b/learn/getting-started/install-and-connect-harper.mdx @@ -0,0 +1,312 @@ +--- +title: Install and Connect Harper +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import GeneralPrerequisites from '../../src/components/learn/general-prerequisites.mdx'; + +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). + +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 +- How to use the `harperdb` CLI +- How to get setup using Harper Fabric +- How to install and setup Harper as a container +- 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. + + + +## 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](#get-started-with-fabric) section. +::: + + + + +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. + +The fastest way to get started is by installing Harper globally using an npm compatible package manager: + +```bash +npm install -g harperdb +``` + + + + +Harper is readily available as a Docker image [`harperdb/harperdb`](https://hub.docker.com/r/harperdb/harperdb). + +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. + +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. + +Using a Docker compatible container manager of choice, the simplest way to get started is using: + +```bash +docker pull harperdb/harperdb +docker run -it \ + --name harper \ + -v /Users//hdb:/home/harperdb/hdb \ + -v /Users//dev:/home/harperdb/dev \ + -e DEFAULTS_MODE=dev \ + -e REPLICATION_HOSTNAME=localhost \ + -p 9925:9925 \ + -p 9926:9926 \ + harperdb/harperdb \ + /bin/bash +``` + +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. Now the `hdb/` path will contain the Harper installation parts (once you install), 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. + +Without the `-it` and `/bin/bash` parts, the image will start (and install) the Harper application by default. For the purposes of these guides, access to the `harperdb` CLI is necessary, so we recommend to always exec into the container. + + + + +Then, execute the Harper CLI to start the installation process: + +```bash +harperdb install +``` + +The Harper installation process is an interactive prompt, however it also supports overrides using environment variables or CLI arguments. It supports partial or complete overrides for the installation prompts and even allows additional configuration options to be specified too. + +This guide focusses on a happy path in order to keep things simple. If you're interested in learning more about all of Harper's configuration options see the the [Harper CLI](../../docs/deployments/harper-cli) reference docs. + + + + +When installing locally on your machine, you can specify any destination for Harper, we recommend using something within your user directory such as `/User//hdb`. Keep note of what you specify for the username and password, and make sure you select the `dev` default config and set the hostname to `localhost`. + +``` +> harperdb install + +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: /User//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. +``` + + + + +The base image presets a number of configuration environment variables. The additional `DEFAULTS_MODE` and `REPLICATION_HOSTNAME` variables included in the `docker run` command complete the installation prompts making the whole command non-interactive. + +``` +> harperdb install + +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/harperdb/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. +``` + +Keep in mind that Harper is installed at the `/home/harperdb/hdb` path within the container (which is mounted to some path on the host system if you used `-v` in the `docker run` command), and that the username and password are defaulted to `HDB_ADMIN` and `password` respectively. + + + + +### Running Harper as a foreground process + +After completing the installation, run Harper using: + +```bash +harperdb +``` + +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. + +If all is working correctly, you should see the following output in your command line: + +``` +> harperdb +Starting HarperDB... + + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’ + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’ + β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–’ + β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–’ + β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–’β–’ + β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ +β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’ + + HarperDB, Inc. Denver, CO. + +[main/0] [info]: HarperDB PID +[main/0] [info]: Checking if HDB software has been updated +Debugger listening on ws://127.0.0.1:9229/ +For help, see: https://nodejs.org/en/docs/inspector +[main/0] [info]: All root applications loaded +[http/1] [info]: Domain socket listening on /hdb/operations-server +HarperDB 4.y.z successfully started +[main/0] [notify]: HarperDB successfully started. + +Hostname: localhost +Worker Threads: 1 +Root Path: /hdb +Debugging: enabled: true +Logging: level: info, location: /hdb/log/hdb.log, stdout/err +Default: HTTP (and WS): 9926, CORS: enabled for * +Operations API: HTTP: 9925, CORS: enabled for *, unix socket: /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 /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, 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 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](#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, or getting started with Harper Fabric. + +### Running Harper as a background process + +If you want to run Harper in the background, use `harperdb start` instead. + +``` +> harperdb start +Starting HarperDB... + + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’ + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’ + β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–’ + β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–’ + β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–’β–’ + β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ +β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–“β–“β–“β–“β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–“β–“β–“β–“β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–“β–“β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’β–’ + β–’β–’β–’β–’β–’β–’β–’ + + HarperDB, Inc. Denver, CO. + +[main/0] [info]: HarperDB PID 49036 +[main/0] [info]: Checking if HDB software has been updated +HarperDB 4.7.12 successfully started +[main/0] [notify]: HarperDB successfully started. +``` + +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 `/log/hdb.log`. For example, you can tail stream the log file using something like: + +```bash +tail -f /log/hdb.log +``` + +Now, you must use `harperdb stop` to shut down Harper. + +``` +> harperdb stop +Stopping HarperDB. +[main/0] [notify]: Stopping HarperDB. +``` + +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. + +## 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](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 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](#performing-a-health-check) section to verify your instance. + +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. + +## 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 configured a different Operations API port, use that instead of `9925` here. + +Similarly, if you are using a Harper Fabric cluster, replace the `http://localhost` with the cluster URL. +::: + + + + +```bash +curl http://localhost:9925/health +``` + + + + +```typescript +const response = await fetch('http://localhost:9925/health'); +const text = await response.text(); +console.log(text); +``` + + + + + +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). + +## Additional Resources + +- [Harper CLI](../../docs/deployments/harper-cli) reference documentation +- [Harper Fabric](../../fabric/) documentation diff --git a/learn/index.mdx b/learn/index.mdx new file mode 100644 index 00000000..768cd4de --- /dev/null +++ b/learn/index.mdx @@ -0,0 +1,29 @@ +--- +title: Welcome to Harper Learn +--- + +import GeneralPrerequisites from '../src/components/learn/general-prerequisites.mdx'; + +This documentation section contains thorough guides for learning how to develop and manage applications with Harper. The guides are present in a logical order to build up knowledge across Harper's vast feature set. The guides are example based and provide a hands-on approach to teaching and demonstrating key features. Guides can be referenced independently, but assume the reader is familiar with concepts presented in previous guides. + +{/** +Uncomment this when we actually have these guides created +For example, the [Loading Data]() guide assumes the reader already knows how to build a basic Harper application (covered in ), create databases and tables using schemas, and some basic query techniques. Those concepts are specifically covered throughout the [Getting Started](), [Key Harper Application Features](), and [Defining Databases and Tables]() guides. +**/} + +Most guides present both local-based and [Harper Fabric](https://fabric.harper.fast) cloud-based examples and instructions. Regardless, in order to properly complete all examples, we recommend the following prerequisite tools installed and configured on your local machine: + + + +If you ever have questions, join our official community [Discord](https://harper.fast/discord). Furthermore, Harper documentation is open source, if you notice anything out-of-place with the guide content, please [open an issue](https://github.com/HarperFast/documentation/issues) or submit changes directly using the "Edit this page" link at the bottom of every page. + +:::info + +Eagle-eye developers may notice some things still reference Harper's previous name, HarperDB. + +The "database" part is not gone, Harper has simply evolved to become so much more than _just_ a database. +Harper is one-and-the-same with HarperDB, so please bare with us as we chip away at some renames. + +::: + +When you're ready to get started, click the "Next" tab below to begin your Harper adventure! diff --git a/redirects.ts b/redirects.ts index fb7f3972..76c0e74f 100644 --- a/redirects.ts +++ b/redirects.ts @@ -177,8 +177,48 @@ function generateDocsRedirects(basePath: string): RedirectRule[] { // Old Technical Details -> Reference paths { from: withBase('/technical-details/reference'), to: withBase('/reference/') }, - // Getting Started -> Root - { from: withBase('/getting-started'), to: withBase('/') } + // Getting Started and Foundations pages to new Learn section + { from: withBase('/getting-started'), to: withBase('/learn/') }, + { from: withBase('/4.6/getting-started'), to: withBase('/learn/') }, + { from: withBase('/4.5/getting-started'), to: withBase('/learn/') }, + { from: withBase('/4.4/getting-started'), to: withBase('/learn/') }, + + { + from: withBase('/getting-started/installation'), + to: withBase('/learn/getting-started/install-and-connect-harper'), + }, + { + from: withBase('/4.6/getting-started/installation'), + to: withBase('/learn/getting-started/install-and-connect-harper'), + }, + { + from: withBase('/4.5/getting-started/installation'), + to: withBase('/learn/getting-started/install-and-connect-harper'), + }, + { + from: withBase('/4.4/getting-started/installation'), + to: withBase('/learn/getting-started/install-and-connect-harper'), + }, + + { from: withBase('/getting-started/quickstart'), to: withBase('/learn/getting-started/quickstart') }, + { from: withBase('/4.6/getting-started/quickstart'), to: withBase('/learn/getting-started/quickstart') }, + { from: withBase('/4.5/getting-started/quickstart'), to: withBase('/learn/getting-started/quickstart') }, + { from: withBase('/4.4/getting-started/quickstart'), to: withBase('/learn/getting-started/quickstart') }, + + { from: withBase('/foundations/harper-architecture'), to: withBase('/learn/') }, + { from: withBase('/4.6/foundations/harper-architecture'), to: withBase('/learn/') }, + { from: withBase('/4.5/foundations/harper-architecture'), to: withBase('/learn/') }, + { from: withBase('/4.4/foundations/harper-architecture'), to: withBase('/learn/') }, + + { from: withBase('/foundations/core-concepts'), to: withBase('/learn/') }, + { from: withBase('/4.6/foundations/core-concepts'), to: withBase('/learn/') }, + { from: withBase('/4.5/foundations/core-concepts'), to: withBase('/learn/') }, + { from: withBase('/4.4/foundations/core-concepts'), to: withBase('/learn/') }, + + { from: withBase('/foundations/use-cases'), to: withBase('/learn/') }, + { from: withBase('/4.6/foundations/use-cases'), to: withBase('/learn/') }, + { from: withBase('/4.5/foundations/use-cases'), to: withBase('/learn/') }, + { from: withBase('/4.4/foundations/use-cases'), to: withBase('/learn/') } ); return redirects; diff --git a/sidebarsLearn.ts b/sidebarsLearn.ts new file mode 100644 index 00000000..608c4a61 --- /dev/null +++ b/sidebarsLearn.ts @@ -0,0 +1,45 @@ +import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; + +const sidebarsLearn: SidebarsConfig = { + learnSidebar: [ + { + type: 'doc', + id: 'index', + label: 'Welcome', + }, + { + type: 'category', + label: 'Getting Started', + collapsible: false, + className: 'learn-category-header', + items: [ + { + type: 'doc', + id: 'getting-started/install-and-connect-harper', + label: 'Install and Connect Harper' + }, + { + type: 'doc', + id: 'getting-started/create-your-first-application', + label: 'Create your First Application' + } + ], + }, + { + type: 'category', + label: 'Developers', + collapsible: false, + className: 'learn-category-header', + items: [{ type: 'autogenerated', dirName: 'developers' }], + }, + { + type: 'category', + label: 'Administration', + collapsible: false, + className: 'learn-category-header', + items: [{ type: 'autogenerated', dirName: 'administration' }], + }, + ], +}; + +export default sidebarsLearn; diff --git a/src/components/learn/general-prerequisites.mdx b/src/components/learn/general-prerequisites.mdx new file mode 100644 index 00000000..887e222c --- /dev/null +++ b/src/components/learn/general-prerequisites.mdx @@ -0,0 +1,12 @@ +- 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](https://nodejs.org/en/download) page + - For more information on valid versions refer to [Node.js Releases](https://nodejs.org/en/about/previous-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 diff --git a/src/css/custom.css b/src/css/custom.css index 01c07762..970b2a67 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -36,3 +36,25 @@ code, tab-size: 2; -moz-tab-size: 2; } + +/* Custom styles for Learn sidebar category headers */ +.learn-category-header .menu__list-item-collapsible:hover { + background: none; +} + +.learn-category-header .menu__list-item-collapsible .menu__link { + color: #6c757d !important; /* Grey text color */ + border-radius: 0; + border-bottom: 1px solid #dee2e6; /* Underline */ + padding-bottom: 0.25rem; + margin-bottom: 0.5rem; + cursor: default; /* Change cursor since it's not clickable */ + font-weight: 600; /* Make it stand out as a header */ + pointer-events: none; /* Disable clicking */ +} + +/* Dark mode styling for category headers */ +[data-theme='dark'] .learn-category-header .menu__list-item-collapsible .menu__link { + color: #adb5bd !important; /* Lighter grey for dark mode */ + border-bottom-color: #495057; /* Darker underline for dark mode */ +} diff --git a/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx b/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx index 1d650a37..75c87100 100644 --- a/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx +++ b/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx @@ -4,7 +4,7 @@ import { useLocation } from '@docusaurus/router'; import type { Props } from '@theme/NavbarItem/DocsVersionDropdownNavbarItem'; function isNonVersionedPathname(pathname: string) { - return pathname.startsWith('/fabric') || pathname.startsWith('/release-notes'); + return pathname.startsWith('/fabric') || pathname.startsWith('/release-notes') || pathname.startsWith('/learn'); } export default function DocsVersionDropdownNavbarItemWrapper(props: Props) { diff --git a/versioned_docs/version-4.4/foundations/core-concepts.md b/versioned_docs/version-4.4/foundations/core-concepts.md deleted file mode 100644 index 202f85ff..00000000 --- a/versioned_docs/version-4.4/foundations/core-concepts.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Core Concepts ---- - -# Core Concepts - -Before you build your first app with Harper, it helps to understand a few key ideas. These concepts show you how Harper is structured and why it’s flexible enough to power everything from a quick proof-of-concept to a production-ready platform. - -## Components - -**Components** are the building blocks of Harper. -They’re JavaScript-based modules that extend Harper’s core, and they can talk directly to Harper’s [Global APIs](../reference/globals) (databases, tables, resources). - -Because components can build on top of each other, they give you composability. For example, both [Applications](../developers/applications/) and [Plugins](../developers/components/reference#extensions) are just kinds of components: - -- **Plugins** add individual capabilities, like defining tables or serving static assets. -- **Applications** pull multiple plugins and resources together into a complete product. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring up a backend from scratch, you can piece together pre-built functionality and get to working endpoints fast. -::: - -## Applications (a type of Component) - -An **application** is a special kind of component that pulls everything together. -Applications rely on plugins to do the work: - -- Use `graphqlSchema` to define your data tables. -- Add `rest` to query that data instantly. -- Plug in `static` to serve files or front-end assets. - -You can even run full frameworks like [Next.js](https://github.com/HarperDB/nextjs) or [Apollo](https://github.com/HarperDB/apollo) as Harper applications. - -:::info -πŸ’‘ **Why it matters:** Applications are how you ship real products on Harper. They let you stitch together resources, APIs, and UI in one place. -::: - -## Plugins - -**Plugins** are a special kind of component that are not meant to run standalone, but instead add features to applications or other components. These were originally called **extensions** (and the [extension API](../developers/components/reference#extensions) is still supported), but the new plugin API is simultaneously a simplification and extensibility upgrade. - -Examples you’ll see in the ecosystem include: - -- **Built in plugins**: These are embedded in Harper and work out of the box. Examples include [graphqlSchema](../developers/components/built-in#graphqlschema) for database and table definitions, [rest](../developers/rest) for RESTful access to your data, and [static](../developers/components/built-in#static) for serving files or frontend assets. - -- **Custom plugins**: These live outside of Harper and are installed from GitHub or npm. Harper supports a few official ones, and the ecosystem may include community plugins as well. Examples include [@harperdb/nextjs](https://github.com/HarperDB/nextjs) for Next.js integration and [@harperdb/apollo](https://github.com/HarperDB/apollo) for Apollo GraphQL. - -:::info -πŸ’‘ **Why it matters:** Plugins give Harper its flexibility. You can compose them into applications to get powerful functionality without writing boilerplate yourself. -::: - -## Resources - -**Resources** are Harper’s data layer and are implemented using the [`Resource`](../reference/resource/) class. -They represent databases, tables, and other data entities, and they provide a unified API for accessing, querying, modifying, and monitoring records. - -At the simplest level, resources let you: - -- Define schemas and tables for your application data. -- Query and update that data through Harper’s APIs. -- Extend the base `Resource` class with JavaScript to define custom data sources or behaviors. - -Each `Resource` instance can represent a single record or a collection of records at a given point in time. -Static methods on the `Resource` class handle common operations like parsing paths, running transactions, and enforcing access controls, while instance methods give you a transactional view of individual records. - -:::info -πŸ’‘ **Why it matters:** Whether you’re working with standard tables or custom-defined resources, everything in Harper’s data layer builds on the same model. This gives you consistency when modeling data and flexibility to extend it with your own logic. For full details, see the [Resource reference documentation](../reference/resource/). -::: - -## Server - -At the edge of Harper is the **server layer**, which connects your data to the outside world. Harper supports REST/HTTP, WebSockets, MQTT, and more. A single resource can be available through multiple protocols at onceβ€”so the same table can power a real-time dashboard, a mobile app, and a backend API. - -:::info -πŸ’‘ **Why it matters:** You don’t have to choose between protocols. One data model, many ways to access it. -::: - ---- - -βœ… With these concepts in mind, you’re ready to [build your first application](../getting-started/quickstart). That’s where you’ll see how Components, Resources, and Extensions come together in practice. diff --git a/versioned_docs/version-4.4/foundations/harper-architecture.md b/versioned_docs/version-4.4/foundations/harper-architecture.md deleted file mode 100644 index d8f767fb..00000000 --- a/versioned_docs/version-4.4/foundations/harper-architecture.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Harper Architecture ---- - -# Harper Architecture - -Before diving deep into APIs and configuration, it helps to understand the big picture of how Harper works. -Harper uses a **three-layer architecture** designed for distributed, edge-first computing. Each layer builds on the next, letting you start simple and scale as your app grows. - -![](/img/v4.6/harper-architecture.png) - -At a high level: - -- **Core services** handle data, networking, and files. -- **Plugins** layer in reusable features (REST, GraphQL, Next.js, etc.). -- **Applications** bring everything together to deliver user-facing functionality. - -:::info -πŸ’‘ **Why it matters:** You focus on building your app, while Harper takes care of scaling, networking, and consistency behind the scenes. -::: - ---- - -## Core Services - -Harper ships with three essential services: - -- **Database** β†’ Fast storage, queries, and transactions. -- **Networking** β†’ REST/HTTP, WebSockets, MQTT, and cluster communication. -- **Component Management** β†’ The system that loads, configures, and connects components (applications, plugins, resources) so they work together consistently. - -Think of these as Harper’s foundationβ€”every extension and app builds on them. - ---- - -## Applications & Extensions - -Most of your work will happen here. - -### Applications - -Applications sit at the top layer. They’re where you implement user-facing features. Examples: - -- A **Next.js app** served directly from Harper. -- A **basic app** from the [Getting Started guide](../getting-started/quickstart) that defines a schema, adds a table, and automatically exposes REST endpoints with the `rest` extension. - -Applications don’t re-invent core logicβ€”they declare the plugins they need. - -### Component Configuration - -Every Harper project starts with a **root configuration**. -This configuration declares which components (applications, plugins/extensions, resources) should be loaded and how they should be initialized. - -Some components are self-contained, while others include configuration that ties into additional components. For example: - -- An application in the root config might load the `rest` plugin. -- The `rest` plugin exposes data from the database, so its configuration links to `graphqlSchema`. -- `graphqlSchema` defines the tables that the database service makes available. - -This layering of configuration is what makes Harper composable: by declaring one component in your root config, you can enable entire sets of functionality. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring everything manually, you declare the root config, and Harper initializes the components in the right relationships. -::: - ---- - -## Resource API - -At the heart of Harper is the **Resource API**. It gives you a unified, consistent way to interact with data. - -- `get()` β†’ fetch data -- `post()` β†’ create data or trigger actions -- `put()` β†’ replace existing data -- `patch()` β†’ update part of a record - -Every call is wrapped in a transaction, so multi-table operations stay consistent without extra boilerplate. - -For the complete API, see the [Resource reference](../reference/resource). - -:::info -πŸ’‘ **Why it matters:** You can build reliable featuresβ€”like signups, payments, or analyticsβ€”without hand-rolling transaction logic. -::: - ---- - -## Transaction Model - -All requests run inside automatic transactions: - -- Read/write across multiple tables in a single request. -- Automatic change tracking. -- Guaranteed consistency at commit. - -:::info -πŸ’‘ **Why it matters:** You don’t have to think about database race conditions or half-finished writesβ€”Harper guarantees integrity by default. -::: - ---- - -βœ… With this architecture in mind, you can see how Harper scales from β€œhello world” to complex, distributed applications. Next, try putting it into practice by [building your first app](../developers/applications/). diff --git a/versioned_docs/version-4.4/foundations/use-cases.md b/versioned_docs/version-4.4/foundations/use-cases.md deleted file mode 100644 index 642a74f7..00000000 --- a/versioned_docs/version-4.4/foundations/use-cases.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Harper Use Cases ---- - -# Harper Use Cases - -Harper is designed to cut out infrastructure complexity so you can move faster. -Here are some common ways developers use Harper in production today β€” each one showing how Harper’s architecture translates into real-world outcomes. - ---- - -## RESTful APIs for Distributed & Cached Data - -**Great for:** web apps, mobile apps, data-heavy platforms. - -Harper’s most common use case is exposing distributed, cached data over a RESTful interface. -This lets you serve complex or large-scale datasets efficiently, with built-in caching and global distribution. - -- Define your schema with the `graphqlSchema` plugin. -- Expose it instantly over REST using the `rest` plugin. -- Take advantage of Harper’s caching layer to serve hot data without extra infrastructure. -- Power both web and mobile applications from the same API. - -:::info -πŸ’‘ **Why it matters:** Instead of bolting a cache or API layer onto a database, Harper gives you a unified system that scales for real-world apps. -::: - ---- - -## Online Catalogs & Content Delivery - -**Great for:** e-commerce sites, real estate listings, media & content platforms. - -Harper’s distributed architecture makes your pages load fast worldwide, improving **SEO** and **conversion rates**. - -- Host your frontend directly with the [Next.js Extension](https://github.com/HarperDB/nextjs). -- Support any framework using Harper’s extension system. -- Use Harper’s built-in caching + JavaScript layer to [server-side render pages](https://www.harpersystems.dev/development/tutorials/server-side-rendering-with-multi-tier-cache). -- Keep pages instantly fresh with built-in [WebSocket connections](../developers/real-time#websockets). - -:::info -πŸ’‘ **Why it matters:** Instead of stitching together CDN + DB + API layers, you deliver catalog and content experiences from a single platform. -::: - ---- - -## Data Delivery Networks - -**Great for:** live sports updates, flight tracking, software updates. - -Harper combines **messaging**, **data storage**, and **application logic** in one system. That means: - -- Push real-time updates directly to clients. -- Process and store data without leaving Harper. -- Eliminate extra message brokers or caching systems. - -Explore the [real-time docs](../developers/real-time) to see how it works. - -:::info -πŸ’‘ **Why it matters:** You can build real-time data services in hours, not weeks, with fewer moving parts to manage. -::: - ---- - -## Edge Inference Systems - -**Great for:** IoT pipelines, sensor networks, edge AI. - -Normally, capturing and analyzing streams at the edge requires a patchwork of tools. Harper simplifies this with: - -- **Self-healing connections** that keep data flowing even in flaky environments. -- The same Harper runtime running at both layers. - -:::info -πŸ’‘ **Why it matters:** One consistent stack across edge and cloud makes AI/ML inference faster, cheaper, and easier to scale. -::: - ---- - -βœ… Want to explore more? [Contact us](https://www.harpersystems.dev/contact) and we’ll walk you through building your own use case. diff --git a/versioned_docs/version-4.4/getting-started/installation.md b/versioned_docs/version-4.4/getting-started/installation.md deleted file mode 100644 index e37dad66..00000000 --- a/versioned_docs/version-4.4/getting-started/installation.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Install Harper ---- - -# Install Harper - -You can get Harper running in minutes. -Choose the option that fits your workflow: - -- **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 (fastest way) - -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). - -βœ… Quick check: open http://localhost:9925 or run: - -```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 :/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 `` 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). - -βœ… Quick check: - -```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. -::: - -## Next Steps - -Once Harper is running, you can: - -- [Build your first application](../getting-started/quickstart) -- Explore the [Core Concepts](../foundations/core-concepts) -- Learn about [Harper's architecture](../foundations/harper-architecture) -- Review [Configuration options](../deployments/configuration) - -:::info -Need help? Please don’t hesitate to [reach out](https://www.harpersystems.dev/contact). -::: diff --git a/versioned_docs/version-4.4/getting-started/quickstart.md b/versioned_docs/version-4.4/getting-started/quickstart.md deleted file mode 100644 index 03540631..00000000 --- a/versioned_docs/version-4.4/getting-started/quickstart.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Create Your First Application ---- - -# Create Your First Application - -Now that you've set up Harper, let's build a simple API. Harper lets you build powerful APIs with minimal effort. In just a few minutes, you'll have a functional REST API with automatic validation, indexing, and queryingβ€”all without writing a single line of code. - -## Setup Your Project - -Start by cloning the [Harper Application Template](https://github.com/HarperDB/application-template) : - -```bash -git clone https://github.com/HarperDB/application-template my-app -cd my-app -``` - -## 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): - -```graphql -type Dog @table { - # properties will go here soon -} -``` - -And then we'll add a primary key named `id` of type `ID`: - -_(Note: A GraphQL schema is a fast method to define tables in Harper, but you are by no means required to use GraphQL to query your application, nor should you necessarily do so)_ - -```graphql -type Dog @table { - id: ID @primaryKey -} -``` - -Now we tell Harper to run this as an application: - -```bash -harperdb dev . # tell Harper cli to run current directory as an application in dev mode -``` - -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 - -Next, let's expand our `Dog` table by adding additional typed attributes for dog `name`, `breed` and `age`. - -```graphql -type Dog @table { - id: ID @primaryKey - name: String - breed: String - age: Int -} -``` - -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). - -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 -type Dog @table @sealed { - id: ID @primaryKey - name: String - breed: String - age: Int - tricks: [String] -} -``` - -## Adding an Endpoint - -Now that we have a running application with a database (with data if you imported any data), let's make this data accessible from a RESTful URL by adding an endpoint. To do this, we simply add the `@export` directive to our `Dog` table: - -```graphql -type Dog @table @export { - id: ID @primaryKey - name: String - breed: String - age: Int - tricks: [String] -} -``` - -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: - -```bash -curl -X POST http://localhost:9926/Dog/ \ - -H "Content-Type: application/json" \ - -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/` to view that record. Alternately, the curl command `curl http://localhost:9926/Dog/` 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. - -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). - -### Content Negotiation - -These endpoints support various content types, including `JSON`, `CBOR`, `MessagePack` and `CSV`. Simply include an `Accept` header in your requests with the preferred content type. We recommend `CBOR` as a compact, efficient encoding with rich data types, but `JSON` is familiar and great for web application development, and `CSV` can be useful for exporting data to spreadsheets or other processing. - -Harper works with other important standard HTTP headers as well, and these endpoints are even capable of caching interaction: - -``` -Authorization: Basic -Accept: application/cbor -If-None-Match: "etag-id" # browsers can automatically provide this -``` - -## Querying - -Querying your application database is straightforward and easy, as tables exported with the `@export` directive are automatically exposed via [REST endpoints](../developers/rest). Simple queries can be crafted through [URL query parameters](https://en.wikipedia.org/wiki/Query_string). - -In order to maintain reasonable query speed on a database as it grows in size, it is critical to select and establish the proper indexes. So, before we add the `@export` declaration to our `Dog` table and begin querying it, let's take a moment to target some table properties for indexing. We'll use `name` and `breed` as indexed table properties on our `Dog` table. All we need to do to accomplish this is tag these properties with the `@indexed` directive: - -```graphql -type Dog @table { - id: ID @primaryKey - name: String @indexed - breed: String @indexed - owner: String - age: Int - tricks: [String] -} -``` - -And finally, we'll add the `@export` directive to expose the table as a RESTful endpoint - -```graphql -type Dog @table @export { - id: ID @primaryKey - name: String @indexed - breed: String @indexed - owner: String - age: Int - tricks: [String] -} -``` - -Now we can start querying. Again, we just simply access the endpoint with query parameters (basic GET requests), like: - -``` -http://localhost:9926/Dog/?name=Harper -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. - -> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../reference/graphql). - -## 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. diff --git a/versioned_docs/version-4.5/foundations/core-concepts.md b/versioned_docs/version-4.5/foundations/core-concepts.md deleted file mode 100644 index 202f85ff..00000000 --- a/versioned_docs/version-4.5/foundations/core-concepts.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Core Concepts ---- - -# Core Concepts - -Before you build your first app with Harper, it helps to understand a few key ideas. These concepts show you how Harper is structured and why it’s flexible enough to power everything from a quick proof-of-concept to a production-ready platform. - -## Components - -**Components** are the building blocks of Harper. -They’re JavaScript-based modules that extend Harper’s core, and they can talk directly to Harper’s [Global APIs](../reference/globals) (databases, tables, resources). - -Because components can build on top of each other, they give you composability. For example, both [Applications](../developers/applications/) and [Plugins](../developers/components/reference#extensions) are just kinds of components: - -- **Plugins** add individual capabilities, like defining tables or serving static assets. -- **Applications** pull multiple plugins and resources together into a complete product. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring up a backend from scratch, you can piece together pre-built functionality and get to working endpoints fast. -::: - -## Applications (a type of Component) - -An **application** is a special kind of component that pulls everything together. -Applications rely on plugins to do the work: - -- Use `graphqlSchema` to define your data tables. -- Add `rest` to query that data instantly. -- Plug in `static` to serve files or front-end assets. - -You can even run full frameworks like [Next.js](https://github.com/HarperDB/nextjs) or [Apollo](https://github.com/HarperDB/apollo) as Harper applications. - -:::info -πŸ’‘ **Why it matters:** Applications are how you ship real products on Harper. They let you stitch together resources, APIs, and UI in one place. -::: - -## Plugins - -**Plugins** are a special kind of component that are not meant to run standalone, but instead add features to applications or other components. These were originally called **extensions** (and the [extension API](../developers/components/reference#extensions) is still supported), but the new plugin API is simultaneously a simplification and extensibility upgrade. - -Examples you’ll see in the ecosystem include: - -- **Built in plugins**: These are embedded in Harper and work out of the box. Examples include [graphqlSchema](../developers/components/built-in#graphqlschema) for database and table definitions, [rest](../developers/rest) for RESTful access to your data, and [static](../developers/components/built-in#static) for serving files or frontend assets. - -- **Custom plugins**: These live outside of Harper and are installed from GitHub or npm. Harper supports a few official ones, and the ecosystem may include community plugins as well. Examples include [@harperdb/nextjs](https://github.com/HarperDB/nextjs) for Next.js integration and [@harperdb/apollo](https://github.com/HarperDB/apollo) for Apollo GraphQL. - -:::info -πŸ’‘ **Why it matters:** Plugins give Harper its flexibility. You can compose them into applications to get powerful functionality without writing boilerplate yourself. -::: - -## Resources - -**Resources** are Harper’s data layer and are implemented using the [`Resource`](../reference/resource/) class. -They represent databases, tables, and other data entities, and they provide a unified API for accessing, querying, modifying, and monitoring records. - -At the simplest level, resources let you: - -- Define schemas and tables for your application data. -- Query and update that data through Harper’s APIs. -- Extend the base `Resource` class with JavaScript to define custom data sources or behaviors. - -Each `Resource` instance can represent a single record or a collection of records at a given point in time. -Static methods on the `Resource` class handle common operations like parsing paths, running transactions, and enforcing access controls, while instance methods give you a transactional view of individual records. - -:::info -πŸ’‘ **Why it matters:** Whether you’re working with standard tables or custom-defined resources, everything in Harper’s data layer builds on the same model. This gives you consistency when modeling data and flexibility to extend it with your own logic. For full details, see the [Resource reference documentation](../reference/resource/). -::: - -## Server - -At the edge of Harper is the **server layer**, which connects your data to the outside world. Harper supports REST/HTTP, WebSockets, MQTT, and more. A single resource can be available through multiple protocols at onceβ€”so the same table can power a real-time dashboard, a mobile app, and a backend API. - -:::info -πŸ’‘ **Why it matters:** You don’t have to choose between protocols. One data model, many ways to access it. -::: - ---- - -βœ… With these concepts in mind, you’re ready to [build your first application](../getting-started/quickstart). That’s where you’ll see how Components, Resources, and Extensions come together in practice. diff --git a/versioned_docs/version-4.5/foundations/harper-architecture.md b/versioned_docs/version-4.5/foundations/harper-architecture.md deleted file mode 100644 index d8f767fb..00000000 --- a/versioned_docs/version-4.5/foundations/harper-architecture.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Harper Architecture ---- - -# Harper Architecture - -Before diving deep into APIs and configuration, it helps to understand the big picture of how Harper works. -Harper uses a **three-layer architecture** designed for distributed, edge-first computing. Each layer builds on the next, letting you start simple and scale as your app grows. - -![](/img/v4.6/harper-architecture.png) - -At a high level: - -- **Core services** handle data, networking, and files. -- **Plugins** layer in reusable features (REST, GraphQL, Next.js, etc.). -- **Applications** bring everything together to deliver user-facing functionality. - -:::info -πŸ’‘ **Why it matters:** You focus on building your app, while Harper takes care of scaling, networking, and consistency behind the scenes. -::: - ---- - -## Core Services - -Harper ships with three essential services: - -- **Database** β†’ Fast storage, queries, and transactions. -- **Networking** β†’ REST/HTTP, WebSockets, MQTT, and cluster communication. -- **Component Management** β†’ The system that loads, configures, and connects components (applications, plugins, resources) so they work together consistently. - -Think of these as Harper’s foundationβ€”every extension and app builds on them. - ---- - -## Applications & Extensions - -Most of your work will happen here. - -### Applications - -Applications sit at the top layer. They’re where you implement user-facing features. Examples: - -- A **Next.js app** served directly from Harper. -- A **basic app** from the [Getting Started guide](../getting-started/quickstart) that defines a schema, adds a table, and automatically exposes REST endpoints with the `rest` extension. - -Applications don’t re-invent core logicβ€”they declare the plugins they need. - -### Component Configuration - -Every Harper project starts with a **root configuration**. -This configuration declares which components (applications, plugins/extensions, resources) should be loaded and how they should be initialized. - -Some components are self-contained, while others include configuration that ties into additional components. For example: - -- An application in the root config might load the `rest` plugin. -- The `rest` plugin exposes data from the database, so its configuration links to `graphqlSchema`. -- `graphqlSchema` defines the tables that the database service makes available. - -This layering of configuration is what makes Harper composable: by declaring one component in your root config, you can enable entire sets of functionality. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring everything manually, you declare the root config, and Harper initializes the components in the right relationships. -::: - ---- - -## Resource API - -At the heart of Harper is the **Resource API**. It gives you a unified, consistent way to interact with data. - -- `get()` β†’ fetch data -- `post()` β†’ create data or trigger actions -- `put()` β†’ replace existing data -- `patch()` β†’ update part of a record - -Every call is wrapped in a transaction, so multi-table operations stay consistent without extra boilerplate. - -For the complete API, see the [Resource reference](../reference/resource). - -:::info -πŸ’‘ **Why it matters:** You can build reliable featuresβ€”like signups, payments, or analyticsβ€”without hand-rolling transaction logic. -::: - ---- - -## Transaction Model - -All requests run inside automatic transactions: - -- Read/write across multiple tables in a single request. -- Automatic change tracking. -- Guaranteed consistency at commit. - -:::info -πŸ’‘ **Why it matters:** You don’t have to think about database race conditions or half-finished writesβ€”Harper guarantees integrity by default. -::: - ---- - -βœ… With this architecture in mind, you can see how Harper scales from β€œhello world” to complex, distributed applications. Next, try putting it into practice by [building your first app](../developers/applications/). diff --git a/versioned_docs/version-4.5/foundations/use-cases.md b/versioned_docs/version-4.5/foundations/use-cases.md deleted file mode 100644 index 642a74f7..00000000 --- a/versioned_docs/version-4.5/foundations/use-cases.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Harper Use Cases ---- - -# Harper Use Cases - -Harper is designed to cut out infrastructure complexity so you can move faster. -Here are some common ways developers use Harper in production today β€” each one showing how Harper’s architecture translates into real-world outcomes. - ---- - -## RESTful APIs for Distributed & Cached Data - -**Great for:** web apps, mobile apps, data-heavy platforms. - -Harper’s most common use case is exposing distributed, cached data over a RESTful interface. -This lets you serve complex or large-scale datasets efficiently, with built-in caching and global distribution. - -- Define your schema with the `graphqlSchema` plugin. -- Expose it instantly over REST using the `rest` plugin. -- Take advantage of Harper’s caching layer to serve hot data without extra infrastructure. -- Power both web and mobile applications from the same API. - -:::info -πŸ’‘ **Why it matters:** Instead of bolting a cache or API layer onto a database, Harper gives you a unified system that scales for real-world apps. -::: - ---- - -## Online Catalogs & Content Delivery - -**Great for:** e-commerce sites, real estate listings, media & content platforms. - -Harper’s distributed architecture makes your pages load fast worldwide, improving **SEO** and **conversion rates**. - -- Host your frontend directly with the [Next.js Extension](https://github.com/HarperDB/nextjs). -- Support any framework using Harper’s extension system. -- Use Harper’s built-in caching + JavaScript layer to [server-side render pages](https://www.harpersystems.dev/development/tutorials/server-side-rendering-with-multi-tier-cache). -- Keep pages instantly fresh with built-in [WebSocket connections](../developers/real-time#websockets). - -:::info -πŸ’‘ **Why it matters:** Instead of stitching together CDN + DB + API layers, you deliver catalog and content experiences from a single platform. -::: - ---- - -## Data Delivery Networks - -**Great for:** live sports updates, flight tracking, software updates. - -Harper combines **messaging**, **data storage**, and **application logic** in one system. That means: - -- Push real-time updates directly to clients. -- Process and store data without leaving Harper. -- Eliminate extra message brokers or caching systems. - -Explore the [real-time docs](../developers/real-time) to see how it works. - -:::info -πŸ’‘ **Why it matters:** You can build real-time data services in hours, not weeks, with fewer moving parts to manage. -::: - ---- - -## Edge Inference Systems - -**Great for:** IoT pipelines, sensor networks, edge AI. - -Normally, capturing and analyzing streams at the edge requires a patchwork of tools. Harper simplifies this with: - -- **Self-healing connections** that keep data flowing even in flaky environments. -- The same Harper runtime running at both layers. - -:::info -πŸ’‘ **Why it matters:** One consistent stack across edge and cloud makes AI/ML inference faster, cheaper, and easier to scale. -::: - ---- - -βœ… Want to explore more? [Contact us](https://www.harpersystems.dev/contact) and we’ll walk you through building your own use case. diff --git a/versioned_docs/version-4.5/getting-started/installation.md b/versioned_docs/version-4.5/getting-started/installation.md deleted file mode 100644 index e37dad66..00000000 --- a/versioned_docs/version-4.5/getting-started/installation.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Install Harper ---- - -# Install Harper - -You can get Harper running in minutes. -Choose the option that fits your workflow: - -- **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 (fastest way) - -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). - -βœ… Quick check: open http://localhost:9925 or run: - -```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 :/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 `` 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). - -βœ… Quick check: - -```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. -::: - -## Next Steps - -Once Harper is running, you can: - -- [Build your first application](../getting-started/quickstart) -- Explore the [Core Concepts](../foundations/core-concepts) -- Learn about [Harper's architecture](../foundations/harper-architecture) -- Review [Configuration options](../deployments/configuration) - -:::info -Need help? Please don’t hesitate to [reach out](https://www.harpersystems.dev/contact). -::: diff --git a/versioned_docs/version-4.5/getting-started/quickstart.md b/versioned_docs/version-4.5/getting-started/quickstart.md deleted file mode 100644 index 03540631..00000000 --- a/versioned_docs/version-4.5/getting-started/quickstart.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Create Your First Application ---- - -# Create Your First Application - -Now that you've set up Harper, let's build a simple API. Harper lets you build powerful APIs with minimal effort. In just a few minutes, you'll have a functional REST API with automatic validation, indexing, and queryingβ€”all without writing a single line of code. - -## Setup Your Project - -Start by cloning the [Harper Application Template](https://github.com/HarperDB/application-template) : - -```bash -git clone https://github.com/HarperDB/application-template my-app -cd my-app -``` - -## 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): - -```graphql -type Dog @table { - # properties will go here soon -} -``` - -And then we'll add a primary key named `id` of type `ID`: - -_(Note: A GraphQL schema is a fast method to define tables in Harper, but you are by no means required to use GraphQL to query your application, nor should you necessarily do so)_ - -```graphql -type Dog @table { - id: ID @primaryKey -} -``` - -Now we tell Harper to run this as an application: - -```bash -harperdb dev . # tell Harper cli to run current directory as an application in dev mode -``` - -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 - -Next, let's expand our `Dog` table by adding additional typed attributes for dog `name`, `breed` and `age`. - -```graphql -type Dog @table { - id: ID @primaryKey - name: String - breed: String - age: Int -} -``` - -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). - -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 -type Dog @table @sealed { - id: ID @primaryKey - name: String - breed: String - age: Int - tricks: [String] -} -``` - -## Adding an Endpoint - -Now that we have a running application with a database (with data if you imported any data), let's make this data accessible from a RESTful URL by adding an endpoint. To do this, we simply add the `@export` directive to our `Dog` table: - -```graphql -type Dog @table @export { - id: ID @primaryKey - name: String - breed: String - age: Int - tricks: [String] -} -``` - -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: - -```bash -curl -X POST http://localhost:9926/Dog/ \ - -H "Content-Type: application/json" \ - -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/` to view that record. Alternately, the curl command `curl http://localhost:9926/Dog/` 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. - -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). - -### Content Negotiation - -These endpoints support various content types, including `JSON`, `CBOR`, `MessagePack` and `CSV`. Simply include an `Accept` header in your requests with the preferred content type. We recommend `CBOR` as a compact, efficient encoding with rich data types, but `JSON` is familiar and great for web application development, and `CSV` can be useful for exporting data to spreadsheets or other processing. - -Harper works with other important standard HTTP headers as well, and these endpoints are even capable of caching interaction: - -``` -Authorization: Basic -Accept: application/cbor -If-None-Match: "etag-id" # browsers can automatically provide this -``` - -## Querying - -Querying your application database is straightforward and easy, as tables exported with the `@export` directive are automatically exposed via [REST endpoints](../developers/rest). Simple queries can be crafted through [URL query parameters](https://en.wikipedia.org/wiki/Query_string). - -In order to maintain reasonable query speed on a database as it grows in size, it is critical to select and establish the proper indexes. So, before we add the `@export` declaration to our `Dog` table and begin querying it, let's take a moment to target some table properties for indexing. We'll use `name` and `breed` as indexed table properties on our `Dog` table. All we need to do to accomplish this is tag these properties with the `@indexed` directive: - -```graphql -type Dog @table { - id: ID @primaryKey - name: String @indexed - breed: String @indexed - owner: String - age: Int - tricks: [String] -} -``` - -And finally, we'll add the `@export` directive to expose the table as a RESTful endpoint - -```graphql -type Dog @table @export { - id: ID @primaryKey - name: String @indexed - breed: String @indexed - owner: String - age: Int - tricks: [String] -} -``` - -Now we can start querying. Again, we just simply access the endpoint with query parameters (basic GET requests), like: - -``` -http://localhost:9926/Dog/?name=Harper -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. - -> Additionally, you may now use GraphQL (over HTTP) to create queries. See the documentation for that new feature [here](../reference/graphql). - -## 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. diff --git a/versioned_docs/version-4.5/index.mdx b/versioned_docs/version-4.5/index.mdx index 1e4b7a9a..8feac69a 100644 --- a/versioned_docs/version-4.5/index.mdx +++ b/versioned_docs/version-4.5/index.mdx @@ -17,34 +17,12 @@ Welcome to the Harper Documentation! Here, you'll find all things Harper, and ev ## Getting Started - +The best way to get started using Harper is to head over to the [Learn](../../learn/) section and work through the Getting Started and Developer guides. ## Building with Harper diff --git a/versioned_docs/version-4.6/foundations/core-concepts.md b/versioned_docs/version-4.6/foundations/core-concepts.md deleted file mode 100644 index c2514c79..00000000 --- a/versioned_docs/version-4.6/foundations/core-concepts.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Core Concepts ---- - -# Core Concepts - -Before you build your first app with Harper, it helps to understand a few key ideas. These concepts show you how Harper is structured and why it’s flexible enough to power everything from a quick proof-of-concept to a production-ready platform. - -## Components - -**Components** are the building blocks of Harper. -They’re JavaScript-based modules that extend Harper’s core, and they can talk directly to Harper’s [Global APIs](../reference/globals) (databases, tables, resources). - -Because components can build on top of each other, they give you composability. For example, both [Applications](../developers/applications/) and [Plugins](../reference/components/built-in-extensions) are just kinds of components: - -- **Plugins** add individual capabilities, like defining tables or serving static assets. -- **Applications** pull multiple plugins and resources together into a complete product. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring up a backend from scratch, you can piece together pre-built functionality and get to working endpoints fast. -::: - -## Applications (a type of Component) - -An **application** is a special kind of component that pulls everything together. -Applications rely on plugins to do the work: - -- Use `graphqlSchema` to define your data tables. -- Add `rest` to query that data instantly. -- Plug in `static` to serve files or front-end assets. - -You can even run full frameworks like [Next.js](https://github.com/HarperDB/nextjs) or [Apollo](https://github.com/HarperDB/apollo) as Harper applications. - -:::info -πŸ’‘ **Why it matters:** Applications are how you ship real products on Harper. They let you stitch together resources, APIs, and UI in one place. -::: - -## Plugins - -**Plugins** are a special kind of component that are not meant to run standalone, but instead add features to applications or other components. These were originally called **extensions** (and the [extension API](../reference/components/extensions) is still supported), but the new [plugin API](../reference/components/plugins) is simultaneously a simplification and extensibility upgrade. - -Examples you’ll see in the ecosystem include: - -- **Built in plugins**: These are embedded in Harper and work out of the box. Examples include [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) for database and table definitions, [rest](../reference/components/built-in-extensions#rest) for RESTful access to your data, and [static](../reference/components/built-in-extensions#static) for serving files or frontend assets. - -- **Custom plugins**: These live outside of Harper and are installed from GitHub or npm. Harper supports a few official ones, and the ecosystem may include community plugins as well. Examples include [@harperdb/nextjs](https://github.com/HarperDB/nextjs) for Next.js integration and [@harperdb/apollo](https://github.com/HarperDB/apollo) for Apollo GraphQL. - -:::info -πŸ’‘ **Why it matters:** Plugins give Harper its flexibility. You can compose them into applications to get powerful functionality without writing boilerplate yourself. -::: - -## Resources - -**Resources** are Harper’s data layer and are implemented using the [`Resource`](../reference/resources/) class. -They represent databases, tables, and other data entities, and they provide a unified API for accessing, querying, modifying, and monitoring records. - -At the simplest level, resources let you: - -- Define schemas and tables for your application data. -- Query and update that data through Harper’s APIs. -- Extend the base `Resource` class with JavaScript to define custom data sources or behaviors. - -Each `Resource` instance can represent a single record or a collection of records at a given point in time. -Static methods on the `Resource` class handle common operations like parsing paths, running transactions, and enforcing access controls, while instance methods give you a transactional view of individual records. - -:::info -πŸ’‘ **Why it matters:** Whether you’re working with standard tables or custom-defined resources, everything in Harper’s data layer builds on the same model. This gives you consistency when modeling data and flexibility to extend it with your own logic. For full details, see the [Resource reference documentation](../reference/resources/). -::: - -## Server - -At the edge of Harper is the **server layer**, which connects your data to the outside world. Harper supports REST/HTTP, WebSockets, MQTT, and more. A single resource can be available through multiple protocols at onceβ€”so the same table can power a real-time dashboard, a mobile app, and a backend API. - -:::info -πŸ’‘ **Why it matters:** You don’t have to choose between protocols. One data model, many ways to access it. -::: - ---- - -βœ… With these concepts in mind, you’re ready to [build your first application](../getting-started/quickstart). That’s where you’ll see how Components, Resources, and Extensions come together in practice. diff --git a/versioned_docs/version-4.6/foundations/harper-architecture.md b/versioned_docs/version-4.6/foundations/harper-architecture.md deleted file mode 100644 index 0c6dfb28..00000000 --- a/versioned_docs/version-4.6/foundations/harper-architecture.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Harper Architecture ---- - -# Harper Architecture - -Before diving deep into APIs and configuration, it helps to understand the big picture of how Harper works. -Harper uses a **three-layer architecture** designed for distributed, edge-first computing. Each layer builds on the next, letting you start simple and scale as your app grows. - -![](/img/v4.6/harper-architecture.png) - -At a high level: - -- **Core services** handle data, networking, and files. -- **Plugins** layer in reusable features (REST, GraphQL, Next.js, etc.). -- **Applications** bring everything together to deliver user-facing functionality. - -:::info -πŸ’‘ **Why it matters:** You focus on building your app, while Harper takes care of scaling, networking, and consistency behind the scenes. -::: - ---- - -## Core Services - -Harper ships with three essential services: - -- **Database** β†’ Fast storage, queries, and transactions. -- **Networking** β†’ REST/HTTP, WebSockets, MQTT, and cluster communication. -- **Component Management** β†’ The system that loads, configures, and connects components (applications, plugins, resources) so they work together consistently. - -Think of these as Harper’s foundationβ€”every extension and app builds on them. - ---- - -## Applications & Extensions - -Most of your work will happen here. - -### Applications - -Applications sit at the top layer. They’re where you implement user-facing features. Examples: - -- A **Next.js app** served directly from Harper. -- A **basic app** from the [Getting Started guide](../getting-started/quickstart) that defines a schema, adds a table, and automatically exposes REST endpoints with the `rest` extension. - -Applications don’t re-invent core logicβ€”they declare the plugins they need. - -### Component Configuration - -Every Harper project starts with a **root configuration**. -This configuration declares which components (applications, plugins/extensions, resources) should be loaded and how they should be initialized. - -Some components are self-contained, while others include configuration that ties into additional components. For example: - -- An application in the root config might load the `rest` plugin. -- The `rest` plugin exposes data from the database, so its configuration links to `graphqlSchema`. -- `graphqlSchema` defines the tables that the database service makes available. - -This layering of configuration is what makes Harper composable: by declaring one component in your root config, you can enable entire sets of functionality. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring everything manually, you declare the root config, and Harper initializes the components in the right relationships. -::: - ---- - -## Resource API - -At the heart of Harper is the **Resource API**. It gives you a unified, consistent way to interact with data. - -- `get()` β†’ fetch data -- `post()` β†’ create data or trigger actions -- `put()` β†’ replace existing data -- `patch()` β†’ update part of a record - -Every call is wrapped in a transaction, so multi-table operations stay consistent without extra boilerplate. - -For the complete API, see the [Resource reference](../reference/resources). - -:::info -πŸ’‘ **Why it matters:** You can build reliable featuresβ€”like signups, payments, or analyticsβ€”without hand-rolling transaction logic. -::: - ---- - -## Transaction Model - -All requests run inside automatic transactions: - -- Read/write across multiple tables in a single request. -- Automatic change tracking. -- Guaranteed consistency at commit. - -:::info -πŸ’‘ **Why it matters:** You don’t have to think about database race conditions or half-finished writesβ€”Harper guarantees integrity by default. -::: - ---- - -βœ… With this architecture in mind, you can see how Harper scales from β€œhello world” to complex, distributed applications. Next, try putting it into practice by [building your first app](../developers/applications/). diff --git a/versioned_docs/version-4.6/foundations/use-cases.md b/versioned_docs/version-4.6/foundations/use-cases.md deleted file mode 100644 index 642a74f7..00000000 --- a/versioned_docs/version-4.6/foundations/use-cases.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Harper Use Cases ---- - -# Harper Use Cases - -Harper is designed to cut out infrastructure complexity so you can move faster. -Here are some common ways developers use Harper in production today β€” each one showing how Harper’s architecture translates into real-world outcomes. - ---- - -## RESTful APIs for Distributed & Cached Data - -**Great for:** web apps, mobile apps, data-heavy platforms. - -Harper’s most common use case is exposing distributed, cached data over a RESTful interface. -This lets you serve complex or large-scale datasets efficiently, with built-in caching and global distribution. - -- Define your schema with the `graphqlSchema` plugin. -- Expose it instantly over REST using the `rest` plugin. -- Take advantage of Harper’s caching layer to serve hot data without extra infrastructure. -- Power both web and mobile applications from the same API. - -:::info -πŸ’‘ **Why it matters:** Instead of bolting a cache or API layer onto a database, Harper gives you a unified system that scales for real-world apps. -::: - ---- - -## Online Catalogs & Content Delivery - -**Great for:** e-commerce sites, real estate listings, media & content platforms. - -Harper’s distributed architecture makes your pages load fast worldwide, improving **SEO** and **conversion rates**. - -- Host your frontend directly with the [Next.js Extension](https://github.com/HarperDB/nextjs). -- Support any framework using Harper’s extension system. -- Use Harper’s built-in caching + JavaScript layer to [server-side render pages](https://www.harpersystems.dev/development/tutorials/server-side-rendering-with-multi-tier-cache). -- Keep pages instantly fresh with built-in [WebSocket connections](../developers/real-time#websockets). - -:::info -πŸ’‘ **Why it matters:** Instead of stitching together CDN + DB + API layers, you deliver catalog and content experiences from a single platform. -::: - ---- - -## Data Delivery Networks - -**Great for:** live sports updates, flight tracking, software updates. - -Harper combines **messaging**, **data storage**, and **application logic** in one system. That means: - -- Push real-time updates directly to clients. -- Process and store data without leaving Harper. -- Eliminate extra message brokers or caching systems. - -Explore the [real-time docs](../developers/real-time) to see how it works. - -:::info -πŸ’‘ **Why it matters:** You can build real-time data services in hours, not weeks, with fewer moving parts to manage. -::: - ---- - -## Edge Inference Systems - -**Great for:** IoT pipelines, sensor networks, edge AI. - -Normally, capturing and analyzing streams at the edge requires a patchwork of tools. Harper simplifies this with: - -- **Self-healing connections** that keep data flowing even in flaky environments. -- The same Harper runtime running at both layers. - -:::info -πŸ’‘ **Why it matters:** One consistent stack across edge and cloud makes AI/ML inference faster, cheaper, and easier to scale. -::: - ---- - -βœ… Want to explore more? [Contact us](https://www.harpersystems.dev/contact) and we’ll walk you through building your own use case. diff --git a/versioned_docs/version-4.6/getting-started/installation.md b/versioned_docs/version-4.6/getting-started/installation.md deleted file mode 100644 index f7cb1cf3..00000000 --- a/versioned_docs/version-4.6/getting-started/installation.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Install and Connect Harper ---- - -# Install and Connect Harper - -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. - -## Install with npm - -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 -``` - -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, 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 -``` - -Harper can also be [installed with our Docker image or you can download Harper for manual or offline installation](../deployments/install-harper). - -## Manage and Deploy 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](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 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) -- Learn about [Harper's architecture](../foundations/harper-architecture) -- Review [Configuration options](../deployments/configuration) - -:::info -Need help? Please don’t hesitate to [reach out](https://www.harpersystems.dev/contact). -::: diff --git a/versioned_docs/version-4.6/getting-started/quickstart.md b/versioned_docs/version-4.6/getting-started/quickstart.md deleted file mode 100644 index 3e26b5cf..00000000 --- a/versioned_docs/version-4.6/getting-started/quickstart.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Create Your First Application ---- - -# Create Your First Application - -Now that you've set up Harper, let's build a simple API. Harper lets you build powerful APIs with minimal effort. In just a few minutes, you'll have a functional REST API with automatic validation, indexing, and queryingβ€”all without writing a single line of code. - -## Setup Your Project - -If you have installed Harper locally, start by cloning the [Harper Application Template](https://github.com/HarperDB/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. 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 { - # properties will go here soon -} -``` - -And then we'll add a primary key named `id` of type `ID`: - -_(Note: A GraphQL schema is a fast method to define tables in Harper, but you are by no means required to use GraphQL to query your application, nor should you necessarily do so)_ - -```graphql -type Dog @table { - id: ID @primaryKey -} -``` - -Now we tell Harper to run this as an application: - -```bash -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 - -Next, let's expand our `Dog` table by adding additional typed attributes for dog `name`, `breed` and `age`. - -```graphql -type Dog @table { - id: ID @primaryKey - name: String - breed: String - age: Int -} -``` - -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 -type Dog @table @sealed { - id: ID @primaryKey - name: String - breed: String - age: Int - tricks: [String] -} -``` - -## Adding an Endpoint - -Now that we have a running application with a database (with data if you imported any data), let's make this data accessible from a RESTful URL by adding an endpoint. To do this, we simply add the `@export` directive to our `Dog` table: - -```graphql -type Dog @table @export { - id: ID @primaryKey - name: String - breed: String - age: Int - tricks: [String] -} -``` - -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/ \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Harper", - "breed": "Labrador", - "age": 3, - "tricks": ["sits"] - }' -``` - -Or in Fabric: - -```bash -curl -X POST https://your-cluster.your-org.harperfabric.com/Dog/ \ - -H "Content-Type: application/json" \ - -H "Authentication: Basic " - -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/` to view that record. Alternately, the curl command `curl http://localhost:9926/Dog/` 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` 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). - -### Content Negotiation - -These endpoints support various content types, including `JSON`, `CBOR`, `MessagePack` and `CSV`. Simply include an `Accept` header in your requests with the preferred content type. We recommend `CBOR` as a compact, efficient encoding with rich data types, but `JSON` is familiar and great for web application development, and `CSV` can be useful for exporting data to spreadsheets or other processing. - -Harper works with other important standard HTTP headers as well, and these endpoints are even capable of caching interaction: - -``` -Authorization: Basic -Accept: application/cbor -If-None-Match: "etag-id" # browsers can automatically provide this -``` - -## Querying - -Querying your application database is straightforward and easy, as tables exported with the `@export` directive are automatically exposed via [REST endpoints](../developers/rest). Simple queries can be crafted through [URL query parameters](https://en.wikipedia.org/wiki/Query_string). - -In order to maintain reasonable query speed on a database as it grows in size, it is critical to select and establish the proper indexes. So, before we add the `@export` declaration to our `Dog` table and begin querying it, let's take a moment to target some table properties for indexing. We'll use `name` and `breed` as indexed table properties on our `Dog` table. All we need to do to accomplish this is tag these properties with the `@indexed` directive: - -```graphql -type Dog @table { - id: ID @primaryKey - name: String @indexed - breed: String @indexed - owner: String - age: Int - tricks: [String] -} -``` - -And finally, we'll add the `@export` directive to expose the table as a RESTful endpoint - -```graphql -type Dog @table @export { - id: ID @primaryKey - name: String @indexed - breed: String @indexed - owner: String - age: Int - tricks: [String] -} -``` - -Now we can start querying. Again, we just simply access the endpoint with query parameters (basic GET requests), like: - -``` -http://localhost:9926/Dog/?name=Harper -http://localhost:9926/Dog/?breed=Labrador -http://localhost:9926/Dog/?breed=Husky&name=Balto&select(id,name,breed) -``` - -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://git@github.com/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= \ - package= \ # optional, uses cwd if not specified - target= \ - username= \ - 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. diff --git a/versioned_docs/version-4.6/index.mdx b/versioned_docs/version-4.6/index.mdx index e6e11ca2..7143837b 100644 --- a/versioned_docs/version-4.6/index.mdx +++ b/versioned_docs/version-4.6/index.mdx @@ -19,36 +19,12 @@ 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. - - +The best way to get started using Harper is to head over to the [Learn](../../learn/) section and work through the Getting Started and Developer guides. ## Building with Harper diff --git a/versioned_docs/version-4.7/foundations/core-concepts.md b/versioned_docs/version-4.7/foundations/core-concepts.md deleted file mode 100644 index 8ef3113d..00000000 --- a/versioned_docs/version-4.7/foundations/core-concepts.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Core Concepts ---- - -# Core Concepts - -Before you build your first app with Harper, it helps to understand a few key ideas. These concepts show you how Harper is structured and why it’s flexible enough to power everything from a quick proof-of-concept to a production-ready platform. - -## Components - -**Components** are the building blocks of Harper. -They’re JavaScript-based modules that extend Harper’s core, and they can talk directly to Harper’s [Global APIs](../reference/globals) (databases, tables, resources). - -Because components can build on top of each other, they give you composability. For example, both [Applications](../developers/applications/) and [Plugins](../reference/components/plugins) are just kinds of components: - -- **Plugins** add individual capabilities, like defining tables or serving static assets. -- **Applications** pull multiple plugins and resources together into a complete product. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring up a backend from scratch, you can piece together pre-built functionality and get to working endpoints fast. -::: - -## Applications (a type of Component) - -An **application** is a special kind of component that pulls everything together. -Applications rely on plugins to do the work: - -- Use `graphqlSchema` to define your data tables. -- Add `rest` to query that data instantly. -- Plug in `static` to serve files or front-end assets. - -You can even run full frameworks like [Next.js](https://github.com/HarperDB/nextjs) or [Apollo](https://github.com/HarperDB/apollo) as Harper applications. - -:::info -πŸ’‘ **Why it matters:** Applications are how you ship real products on Harper. They let you stitch together resources, APIs, and UI in one place. -::: - -## Plugins - -**Plugins** are a special kind of component that are not meant to run standalone, but instead add features to applications or other components. These were originally called **extensions** (and the [extension API](../reference/components/extensions) is still supported), but the new [plugin API](../reference/components/plugins) is simultaneously a simplification and extensibility upgrade. - -Examples you’ll see in the ecosystem include: - -- **Built in plugins**: These are embedded in Harper and work out of the box. Examples include [graphqlSchema](../reference/components/built-in-extensions#graphqlschema) for database and table definitions, [rest](../reference/components/built-in-extensions#rest) for RESTful access to your data, and [static](../reference/components/built-in-extensions#static) for serving files or frontend assets. - -- **Custom plugins**: These live outside of Harper and are installed from GitHub or npm. Harper supports a few official ones, and the ecosystem may include community plugins as well. Examples include [@harperdb/nextjs](https://github.com/HarperDB/nextjs) for Next.js integration and [@harperdb/apollo](https://github.com/HarperDB/apollo) for Apollo GraphQL. - -:::info -πŸ’‘ **Why it matters:** Plugins give Harper its flexibility. You can compose them into applications to get powerful functionality without writing boilerplate yourself. -::: - -## Resources - -**Resources** are Harper’s data layer and are implemented using the [`Resource`](../reference/resources/) class. -They represent databases, tables, and other data entities, and they provide a unified API for accessing, querying, modifying, and monitoring records. - -At the simplest level, resources let you: - -- Define schemas and tables for your application data. -- Query and update that data through Harper’s APIs. -- Extend the base `Resource` class with JavaScript to define custom data sources or behaviors. - -Each `Resource` instance can represent a single record or a collection of records at a given point in time. -Static methods on the `Resource` class handle common operations like parsing paths, running transactions, and enforcing access controls, while instance methods give you a transactional view of individual records. - -:::info -πŸ’‘ **Why it matters:** Whether you’re working with standard tables or custom-defined resources, everything in Harper’s data layer builds on the same model. This gives you consistency when modeling data and flexibility to extend it with your own logic. For full details, see the [Resource reference documentation](../reference/resources/). -::: - -## Server - -At the edge of Harper is the **server layer**, which connects your data to the outside world. Harper supports REST/HTTP, WebSockets, MQTT, and more. A single resource can be available through multiple protocols at onceβ€”so the same table can power a real-time dashboard, a mobile app, and a backend API. - -:::info -πŸ’‘ **Why it matters:** You don’t have to choose between protocols. One data model, many ways to access it. -::: - ---- - -βœ… With these concepts in mind, you’re ready to [build your first application](../getting-started/quickstart). That’s where you’ll see how Components, Resources, and Plugins come together in practice. diff --git a/versioned_docs/version-4.7/foundations/harper-architecture.md b/versioned_docs/version-4.7/foundations/harper-architecture.md deleted file mode 100644 index 0c6dfb28..00000000 --- a/versioned_docs/version-4.7/foundations/harper-architecture.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Harper Architecture ---- - -# Harper Architecture - -Before diving deep into APIs and configuration, it helps to understand the big picture of how Harper works. -Harper uses a **three-layer architecture** designed for distributed, edge-first computing. Each layer builds on the next, letting you start simple and scale as your app grows. - -![](/img/v4.6/harper-architecture.png) - -At a high level: - -- **Core services** handle data, networking, and files. -- **Plugins** layer in reusable features (REST, GraphQL, Next.js, etc.). -- **Applications** bring everything together to deliver user-facing functionality. - -:::info -πŸ’‘ **Why it matters:** You focus on building your app, while Harper takes care of scaling, networking, and consistency behind the scenes. -::: - ---- - -## Core Services - -Harper ships with three essential services: - -- **Database** β†’ Fast storage, queries, and transactions. -- **Networking** β†’ REST/HTTP, WebSockets, MQTT, and cluster communication. -- **Component Management** β†’ The system that loads, configures, and connects components (applications, plugins, resources) so they work together consistently. - -Think of these as Harper’s foundationβ€”every extension and app builds on them. - ---- - -## Applications & Extensions - -Most of your work will happen here. - -### Applications - -Applications sit at the top layer. They’re where you implement user-facing features. Examples: - -- A **Next.js app** served directly from Harper. -- A **basic app** from the [Getting Started guide](../getting-started/quickstart) that defines a schema, adds a table, and automatically exposes REST endpoints with the `rest` extension. - -Applications don’t re-invent core logicβ€”they declare the plugins they need. - -### Component Configuration - -Every Harper project starts with a **root configuration**. -This configuration declares which components (applications, plugins/extensions, resources) should be loaded and how they should be initialized. - -Some components are self-contained, while others include configuration that ties into additional components. For example: - -- An application in the root config might load the `rest` plugin. -- The `rest` plugin exposes data from the database, so its configuration links to `graphqlSchema`. -- `graphqlSchema` defines the tables that the database service makes available. - -This layering of configuration is what makes Harper composable: by declaring one component in your root config, you can enable entire sets of functionality. - -:::info -πŸ’‘ **Why it matters:** Instead of wiring everything manually, you declare the root config, and Harper initializes the components in the right relationships. -::: - ---- - -## Resource API - -At the heart of Harper is the **Resource API**. It gives you a unified, consistent way to interact with data. - -- `get()` β†’ fetch data -- `post()` β†’ create data or trigger actions -- `put()` β†’ replace existing data -- `patch()` β†’ update part of a record - -Every call is wrapped in a transaction, so multi-table operations stay consistent without extra boilerplate. - -For the complete API, see the [Resource reference](../reference/resources). - -:::info -πŸ’‘ **Why it matters:** You can build reliable featuresβ€”like signups, payments, or analyticsβ€”without hand-rolling transaction logic. -::: - ---- - -## Transaction Model - -All requests run inside automatic transactions: - -- Read/write across multiple tables in a single request. -- Automatic change tracking. -- Guaranteed consistency at commit. - -:::info -πŸ’‘ **Why it matters:** You don’t have to think about database race conditions or half-finished writesβ€”Harper guarantees integrity by default. -::: - ---- - -βœ… With this architecture in mind, you can see how Harper scales from β€œhello world” to complex, distributed applications. Next, try putting it into practice by [building your first app](../developers/applications/). diff --git a/versioned_docs/version-4.7/foundations/use-cases.md b/versioned_docs/version-4.7/foundations/use-cases.md deleted file mode 100644 index 642a74f7..00000000 --- a/versioned_docs/version-4.7/foundations/use-cases.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Harper Use Cases ---- - -# Harper Use Cases - -Harper is designed to cut out infrastructure complexity so you can move faster. -Here are some common ways developers use Harper in production today β€” each one showing how Harper’s architecture translates into real-world outcomes. - ---- - -## RESTful APIs for Distributed & Cached Data - -**Great for:** web apps, mobile apps, data-heavy platforms. - -Harper’s most common use case is exposing distributed, cached data over a RESTful interface. -This lets you serve complex or large-scale datasets efficiently, with built-in caching and global distribution. - -- Define your schema with the `graphqlSchema` plugin. -- Expose it instantly over REST using the `rest` plugin. -- Take advantage of Harper’s caching layer to serve hot data without extra infrastructure. -- Power both web and mobile applications from the same API. - -:::info -πŸ’‘ **Why it matters:** Instead of bolting a cache or API layer onto a database, Harper gives you a unified system that scales for real-world apps. -::: - ---- - -## Online Catalogs & Content Delivery - -**Great for:** e-commerce sites, real estate listings, media & content platforms. - -Harper’s distributed architecture makes your pages load fast worldwide, improving **SEO** and **conversion rates**. - -- Host your frontend directly with the [Next.js Extension](https://github.com/HarperDB/nextjs). -- Support any framework using Harper’s extension system. -- Use Harper’s built-in caching + JavaScript layer to [server-side render pages](https://www.harpersystems.dev/development/tutorials/server-side-rendering-with-multi-tier-cache). -- Keep pages instantly fresh with built-in [WebSocket connections](../developers/real-time#websockets). - -:::info -πŸ’‘ **Why it matters:** Instead of stitching together CDN + DB + API layers, you deliver catalog and content experiences from a single platform. -::: - ---- - -## Data Delivery Networks - -**Great for:** live sports updates, flight tracking, software updates. - -Harper combines **messaging**, **data storage**, and **application logic** in one system. That means: - -- Push real-time updates directly to clients. -- Process and store data without leaving Harper. -- Eliminate extra message brokers or caching systems. - -Explore the [real-time docs](../developers/real-time) to see how it works. - -:::info -πŸ’‘ **Why it matters:** You can build real-time data services in hours, not weeks, with fewer moving parts to manage. -::: - ---- - -## Edge Inference Systems - -**Great for:** IoT pipelines, sensor networks, edge AI. - -Normally, capturing and analyzing streams at the edge requires a patchwork of tools. Harper simplifies this with: - -- **Self-healing connections** that keep data flowing even in flaky environments. -- The same Harper runtime running at both layers. - -:::info -πŸ’‘ **Why it matters:** One consistent stack across edge and cloud makes AI/ML inference faster, cheaper, and easier to scale. -::: - ---- - -βœ… Want to explore more? [Contact us](https://www.harpersystems.dev/contact) and we’ll walk you through building your own use case. diff --git a/versioned_docs/version-4.7/getting-started/installation.md b/versioned_docs/version-4.7/getting-started/installation.md deleted file mode 100644 index f7cb1cf3..00000000 --- a/versioned_docs/version-4.7/getting-started/installation.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Install and Connect Harper ---- - -# Install and Connect Harper - -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. - -## Install with npm - -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 -``` - -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, 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 -``` - -Harper can also be [installed with our Docker image or you can download Harper for manual or offline installation](../deployments/install-harper). - -## Manage and Deploy 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](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 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) -- Learn about [Harper's architecture](../foundations/harper-architecture) -- Review [Configuration options](../deployments/configuration) - -:::info -Need help? Please don’t hesitate to [reach out](https://www.harpersystems.dev/contact). -::: diff --git a/versioned_docs/version-4.7/getting-started/quickstart.md b/versioned_docs/version-4.7/getting-started/quickstart.md deleted file mode 100644 index 3e26b5cf..00000000 --- a/versioned_docs/version-4.7/getting-started/quickstart.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Create Your First Application ---- - -# Create Your First Application - -Now that you've set up Harper, let's build a simple API. Harper lets you build powerful APIs with minimal effort. In just a few minutes, you'll have a functional REST API with automatic validation, indexing, and queryingβ€”all without writing a single line of code. - -## Setup Your Project - -If you have installed Harper locally, start by cloning the [Harper Application Template](https://github.com/HarperDB/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. 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 { - # properties will go here soon -} -``` - -And then we'll add a primary key named `id` of type `ID`: - -_(Note: A GraphQL schema is a fast method to define tables in Harper, but you are by no means required to use GraphQL to query your application, nor should you necessarily do so)_ - -```graphql -type Dog @table { - id: ID @primaryKey -} -``` - -Now we tell Harper to run this as an application: - -```bash -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 - -Next, let's expand our `Dog` table by adding additional typed attributes for dog `name`, `breed` and `age`. - -```graphql -type Dog @table { - id: ID @primaryKey - name: String - breed: String - age: Int -} -``` - -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 -type Dog @table @sealed { - id: ID @primaryKey - name: String - breed: String - age: Int - tricks: [String] -} -``` - -## Adding an Endpoint - -Now that we have a running application with a database (with data if you imported any data), let's make this data accessible from a RESTful URL by adding an endpoint. To do this, we simply add the `@export` directive to our `Dog` table: - -```graphql -type Dog @table @export { - id: ID @primaryKey - name: String - breed: String - age: Int - tricks: [String] -} -``` - -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/ \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Harper", - "breed": "Labrador", - "age": 3, - "tricks": ["sits"] - }' -``` - -Or in Fabric: - -```bash -curl -X POST https://your-cluster.your-org.harperfabric.com/Dog/ \ - -H "Content-Type: application/json" \ - -H "Authentication: Basic " - -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/` to view that record. Alternately, the curl command `curl http://localhost:9926/Dog/` 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` 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). - -### Content Negotiation - -These endpoints support various content types, including `JSON`, `CBOR`, `MessagePack` and `CSV`. Simply include an `Accept` header in your requests with the preferred content type. We recommend `CBOR` as a compact, efficient encoding with rich data types, but `JSON` is familiar and great for web application development, and `CSV` can be useful for exporting data to spreadsheets or other processing. - -Harper works with other important standard HTTP headers as well, and these endpoints are even capable of caching interaction: - -``` -Authorization: Basic -Accept: application/cbor -If-None-Match: "etag-id" # browsers can automatically provide this -``` - -## Querying - -Querying your application database is straightforward and easy, as tables exported with the `@export` directive are automatically exposed via [REST endpoints](../developers/rest). Simple queries can be crafted through [URL query parameters](https://en.wikipedia.org/wiki/Query_string). - -In order to maintain reasonable query speed on a database as it grows in size, it is critical to select and establish the proper indexes. So, before we add the `@export` declaration to our `Dog` table and begin querying it, let's take a moment to target some table properties for indexing. We'll use `name` and `breed` as indexed table properties on our `Dog` table. All we need to do to accomplish this is tag these properties with the `@indexed` directive: - -```graphql -type Dog @table { - id: ID @primaryKey - name: String @indexed - breed: String @indexed - owner: String - age: Int - tricks: [String] -} -``` - -And finally, we'll add the `@export` directive to expose the table as a RESTful endpoint - -```graphql -type Dog @table @export { - id: ID @primaryKey - name: String @indexed - breed: String @indexed - owner: String - age: Int - tricks: [String] -} -``` - -Now we can start querying. Again, we just simply access the endpoint with query parameters (basic GET requests), like: - -``` -http://localhost:9926/Dog/?name=Harper -http://localhost:9926/Dog/?breed=Labrador -http://localhost:9926/Dog/?breed=Husky&name=Balto&select(id,name,breed) -``` - -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://git@github.com/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= \ - package= \ # optional, uses cwd if not specified - target= \ - username= \ - 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. diff --git a/versioned_docs/version-4.7/index.mdx b/versioned_docs/version-4.7/index.mdx index e6e11ca2..7143837b 100644 --- a/versioned_docs/version-4.7/index.mdx +++ b/versioned_docs/version-4.7/index.mdx @@ -19,36 +19,12 @@ 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. - - +The best way to get started using Harper is to head over to the [Learn](../../learn/) section and work through the Getting Started and Developer guides. ## Building with Harper diff --git a/versioned_sidebars/version-4.4-sidebars.json b/versioned_sidebars/version-4.4-sidebars.json index ced3c7f0..71b91fa4 100644 --- a/versioned_sidebars/version-4.4-sidebars.json +++ b/versioned_sidebars/version-4.4-sidebars.json @@ -5,16 +5,6 @@ "id": "index", "label": "Harper Docs" }, - { - "type": "category", - "label": "Getting Started", - "items": ["getting-started/installation", "getting-started/quickstart"] - }, - { - "type": "category", - "label": "Foundations of Harper", - "items": ["foundations/harper-architecture", "foundations/core-concepts", "foundations/use-cases"] - }, { "type": "category", "label": "Administration", diff --git a/versioned_sidebars/version-4.5-sidebars.json b/versioned_sidebars/version-4.5-sidebars.json index 07801d54..c52613e4 100644 --- a/versioned_sidebars/version-4.5-sidebars.json +++ b/versioned_sidebars/version-4.5-sidebars.json @@ -5,16 +5,6 @@ "id": "index", "label": "Harper Docs" }, - { - "type": "category", - "label": "Getting Started", - "items": ["getting-started/installation", "getting-started/quickstart"] - }, - { - "type": "category", - "label": "Foundations of Harper", - "items": ["foundations/harper-architecture", "foundations/core-concepts", "foundations/use-cases"] - }, { "type": "category", "label": "Developers", diff --git a/versioned_sidebars/version-4.6-sidebars.json b/versioned_sidebars/version-4.6-sidebars.json index 07801d54..c52613e4 100644 --- a/versioned_sidebars/version-4.6-sidebars.json +++ b/versioned_sidebars/version-4.6-sidebars.json @@ -5,16 +5,6 @@ "id": "index", "label": "Harper Docs" }, - { - "type": "category", - "label": "Getting Started", - "items": ["getting-started/installation", "getting-started/quickstart"] - }, - { - "type": "category", - "label": "Foundations of Harper", - "items": ["foundations/harper-architecture", "foundations/core-concepts", "foundations/use-cases"] - }, { "type": "category", "label": "Developers", diff --git a/versioned_sidebars/version-4.7-sidebars.json b/versioned_sidebars/version-4.7-sidebars.json index 0fc204ab..58b7ee57 100644 --- a/versioned_sidebars/version-4.7-sidebars.json +++ b/versioned_sidebars/version-4.7-sidebars.json @@ -5,16 +5,6 @@ "id": "index", "label": "Harper Docs" }, - { - "type": "category", - "label": "Getting Started", - "items": ["getting-started/installation", "getting-started/quickstart"] - }, - { - "type": "category", - "label": "Foundations of Harper", - "items": ["foundations/harper-architecture", "foundations/core-concepts", "foundations/use-cases"] - }, { "type": "category", "label": "Developers",