diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index 0059b385..28b23cf6 100644 --- a/.github/workflows/deploy.yaml +++ b/.github/workflows/deploy.yaml @@ -1,8 +1,6 @@ name: Deploy Docusaurus to GitHub Pages on: - # Trigger the workflow on pull requests and pushes to specific branches - pull_request: push: branches: - main @@ -10,34 +8,18 @@ on: workflow_dispatch: # Concurrency configuration to manage parallel workflow runs -# -# Group composition: pages-- -# - event_type: 'pull_request', 'push', or 'workflow_dispatch' -# - unique_identifier: PR number for PRs, branch ref for pushes/manual runs -# -# Examples of group names: -# - PR #123: "pages-pull_request-123" -# - Push to main: "pages-push-refs/heads/main" -# - Manual run on main: "pages-workflow_dispatch-refs/heads/main" -# -# Behavior: -# - PRs: New commits cancel previous runs (cancel-in-progress: true) -# - Main branch: Runs complete without cancellation (cancel-in-progress: false) -# - Manual dispatch: Runs complete without cancellation (cancel-in-progress: false) concurrency: - group: pages-${{ github.event_name }}-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.ref }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + group: production-deploy + cancel-in-progress: true jobs: build: name: Build Docusaurus runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 + - uses: actions/checkout@v6 - - uses: actions/setup-node@v4 + - uses: actions/setup-node@v6 with: node-version: '22' cache: 'npm' @@ -81,8 +63,6 @@ jobs: needs: build name: Deploy to GitHub Pages runs-on: ubuntu-latest - # Only deploy on push to main or manual trigger, not on PRs - if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch' permissions: pages: write diff --git a/.github/workflows/pr-preview.yaml b/.github/workflows/pr-preview.yaml new file mode 100644 index 00000000..0bd3303c --- /dev/null +++ b/.github/workflows/pr-preview.yaml @@ -0,0 +1,203 @@ +name: Deploy PR Preview + +on: + pull_request: + types: [opened, synchronize, reopened, closed] + +# Cancel previous runs when new commits are pushed to the PR +concurrency: + group: pr-preview-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + deploy-preview: + name: Deploy PR Preview + runs-on: ubuntu-latest + if: github.event.action != 'closed' + permissions: + pull-requests: write + deployments: write + contents: read + + steps: + - name: Checkout PR code + uses: actions/checkout@v6 + with: + ref: ${{ github.event.pull_request.head.sha }} + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: '22' + cache: 'npm' + cache-dependency-path: 'package-lock.json' + + - name: Install dependencies + run: | + echo "Installing dependencies..." + npm ci + + - name: Build Docusaurus site + env: + DOCUSAURUS_BASE_URL: /pr-${{ github.event.pull_request.number }} + run: | + echo "Building site with base URL: $DOCUSAURUS_BASE_URL" + npm run build + + - name: Upload build artifact for local testing + uses: actions/upload-artifact@v4 + with: + name: pr-${{ github.event.pull_request.number }}-build + path: build/ + retention-days: 30 + + - name: Prepare deployment directory + run: | + PR_DIR="pr-${{ github.event.pull_request.number }}" + echo "Creating directory: $PR_DIR" + mkdir -p "$PR_DIR" + + # Create config.yaml + cat > "$PR_DIR/config.yaml" << 'EOF' + static: + files: 'build/**' + urlPath: 'pr-${{ github.event.pull_request.number }}' + extensions: ['html'] + index: true + EOF + + # Copy build directory + cp -r build "$PR_DIR/" + + echo "Contents of $PR_DIR:" + ls -la "$PR_DIR" + + - name: Install HarperDB CLI + run: | + npm install -g harperdb + + - name: Deploy to HarperDB + env: + HARPER_PREVIEW_TARGET: ${{ secrets.HARPER_PREVIEW_TARGET }} + HARPER_PREVIEW_USERNAME: ${{ secrets.HARPER_PREVIEW_USERNAME }} + HARPER_PREVIEW_PASSWORD: ${{ secrets.HARPER_PREVIEW_PASSWORD }} + run: | + cd "pr-${{ github.event.pull_request.number }}" + # Add your additional arguments here + harper deploy \ + target=${HARPER_PREVIEW_TARGET}:9925 \ + username=$HARPER_PREVIEW_USERNAME \ + password=$HARPER_PREVIEW_PASSWORD \ + project=pr-${{ github.event.pull_request.number }} \ + restart=true \ + replicated=true + + - name: Create deployment + env: + HARPER_PREVIEW_TARGET: ${{ secrets.HARPER_PREVIEW_TARGET }} + uses: actions/github-script@v8 + with: + script: | + const prNumber = context.payload.pull_request.number; + const target = process.env.HARPER_PREVIEW_TARGET; + const deploymentUrl = `${target}/pr-${prNumber}`; + + // Create deployment + const deployment = await github.rest.repos.createDeployment({ + owner: context.repo.owner, + repo: context.repo.repo, + ref: context.payload.pull_request.head.sha, + environment: `pr-${prNumber}`, + description: `Preview deployment for PR #${prNumber}`, + auto_merge: false, + required_contexts: [] + }); + + // Create deployment status + await github.rest.repos.createDeploymentStatus({ + owner: context.repo.owner, + repo: context.repo.repo, + deployment_id: deployment.data.id, + state: 'success', + environment_url: deploymentUrl, + description: 'Preview deployment successful' + }); + + // Also add a comment to the PR + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: prNumber, + body: `## 🚀 Preview Deployment\n\nYour preview deployment is ready!\n\n🔗 **Preview URL:** ${deploymentUrl}\n\nThis preview will update automatically when you push new commits.` + }); + + cleanup-preview: + name: Cleanup PR Preview + runs-on: ubuntu-latest + if: github.event.action == 'closed' + permissions: + pull-requests: write + deployments: write + contents: read + + steps: + - name: Checkout code + uses: actions/checkout@v6 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: '22' + cache: 'npm' + cache-dependency-path: 'package-lock.json' + + - name: Install HarperDB CLI + run: | + npm install -g harperdb + + - name: Remove preview deployment + env: + HARPER_PREVIEW_TARGET: ${{ secrets.HARPER_PREVIEW_TARGET }} + HARPER_PREVIEW_USERNAME: ${{ secrets.HARPER_PREVIEW_USERNAME }} + HARPER_PREVIEW_PASSWORD: ${{ secrets.HARPER_PREVIEW_PASSWORD }} + run: | + # Add your cleanup command here (e.g., harper undeploy or similar) + harper drop_component \ + target=${HARPER_PREVIEW_TARGET}:9925 \ + username=$HARPER_PREVIEW_USERNAME \ + password=$HARPER_PREVIEW_PASSWORD \ + project=pr-${{ github.event.pull_request.number }} \ + replicated=true \ + restart=true + echo "Cleaning up preview for PR #${{ github.event.pull_request.number }}" + + - name: Update deployment status + uses: actions/github-script@v7 + with: + script: | + const prNumber = context.payload.pull_request.number; + + // Mark deployment as inactive + const deployments = await github.rest.repos.listDeployments({ + owner: context.repo.owner, + repo: context.repo.repo, + environment: `pr-${prNumber}` + }); + + for (const deployment of deployments.data) { + await github.rest.repos.createDeploymentStatus({ + owner: context.repo.owner, + repo: context.repo.repo, + deployment_id: deployment.id, + state: 'inactive', + description: 'Preview deployment removed' + }); + } + + // Add cleanup comment to PR + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: prNumber, + body: `## 🧹 Preview Cleanup\n\nThe preview deployment for this PR has been removed.` + }); diff --git a/docs/developers/applications/index.md b/docs/developers/applications/index.md index f6c8f6b4..8ac979ab 100644 --- a/docs/developers/applications/index.md +++ b/docs/developers/applications/index.md @@ -81,7 +81,7 @@ This guide is going to walk you through building a basic Harper application usin ## Custom Functionality with JavaScript -[The getting started guide](../../getting-started/quickstart) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +[The getting started guide](/learn/) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). Let's add a property to the dog records when they are returned, that includes their age in human years. To do this, we get the `Dog` class from the defined tables, extend it (with our custom logic), and export it: @@ -117,8 +117,8 @@ type Breed @table { We use the new table's (static) `get()` method to retrieve a breed by id. Harper will maintain the current context, ensuring that we are accessing the data atomically, in a consistent snapshot across tables. This provides: 1. Automatic tracking of most recently updated timestamps across resources for caching purposes -1. Sharing of contextual metadata (like user who requested the data) -1. Transactional atomicity for any writes (not needed in this get operation, but important for other operations) +2. Sharing of contextual metadata (like user who requested the data) +3. Transactional atomicity for any writes (not needed in this get operation, but important for other operations) The resource methods are automatically wrapped with a transaction and will automatically commit the changes when the method finishes. This allows us to fully utilize multiple resources in our current transaction. With our own snapshot of the database for the Dog and Breed table we can then access data like this: 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/getting-started/quickstart.md b/docs/getting-started/quickstart.md deleted file mode 100644 index e8956d0e..00000000 --- a/docs/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: - -```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/docs/index.mdx b/docs/index.mdx index e6e11ca2..b7943200 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..0f49d4d1 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -56,9 +56,19 @@ const config: Config = { projectName: 'documentation', // Usually your repo name. onBrokenLinks: 'throw', - onBrokenMarkdownLinks: 'warn', plugins: [ + // Learn documentation + [ + '@docusaurus/plugin-content-docs', + { + id: 'learn', + path: 'learn', + routeBasePath: 'learn', + sidebarPath: './sidebarsLearn.ts', + editUrl: 'https://github.com/HarperFast/documentation/blob/main/', + }, + ], // Main documentation [ '@docusaurus/plugin-content-docs', @@ -283,6 +293,9 @@ const config: Config = { markdown: { mermaid: true, + hooks: { + onBrokenMarkdownLinks: 'warn', + }, }, themeConfig: { @@ -305,6 +318,13 @@ const config: Config = { href: 'https://www.harper.fast/', }, items: [ + { + type: 'docSidebar', + sidebarId: 'learnSidebar', + docsPluginId: 'learn', + position: 'left', + label: 'Learn', + }, { type: 'docSidebar', sidebarId: 'docsSidebar', @@ -345,13 +365,9 @@ const config: Config = { title: 'Documentation', items: [ { - label: 'Quickstart', - to: `${routeBasePath}/getting-started/quickstart`, + label: 'Learn', + to: `/learn`, }, - // { - // label: 'Developers', - // to: `${routeBasePath}/developers`, - // }, { label: 'Administration', to: `${routeBasePath}/administration`, diff --git a/fabric/index.md b/fabric/index.md index 573557ec..5afd0c30 100644 --- a/fabric/index.md +++ b/fabric/index.md @@ -8,7 +8,7 @@ Fabric Studio is the web-based GUI for Harper. Studio enables you to administer, [Sign up for free!](https://fabric.harper.fast/#/sign-up) -Harper includes a simplified local Studio that is packaged with all Harper installations and served directly from the cluster. It can be enabled in the [configuration file](../docs/deployments/configuration#localstudio). This section is dedicated to the hosted Studio accessed at [studio.harperdb.io](https://fabric.harper.fast/). +Harper includes a simplified local Studio that is packaged with all Harper installations and served directly from the cluster. It can be enabled in the [configuration file](/docs/deployments/configuration#localstudio). This section is dedicated to the hosted Studio accessed at [studio.harperdb.io](https://fabric.harper.fast/). --- 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/learn/getting-started/create-your-first-application.mdx b/learn/getting-started/create-your-first-application.mdx new file mode 100644 index 00000000..e6e6099f --- /dev/null +++ b/learn/getting-started/create-your-first-application.mdx @@ -0,0 +1,372 @@ +--- +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. + +## What You Will Learn + +- Overview of Harper architecture +- What are Harper core services, plugins, and applications +- How to define a table using schemas +- How to run a Harper application +- How to automatically create a REST API from a table schema +- How to interact with the table using the generated REST API + +## Prerequisites + +- Working Harper Installation (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. It's 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. + +## Initializing the Harper Application + +Let's get started building 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 clone into 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", 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. + + + + + +## Creating 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. Even though you use GraphQL to define your table schemas, you do not need to use GraphQL for querying. + + + + +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 +The Harper schema system has a lot of great features for making it effortless to define tables. We'll demonstrate more custom directives later. +::: + +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. + +:::note +If you need to check your work, checkout the [`01-create-table`](https://github.com/HarperFast/create-your-first-application/tree/01-create-table) branch. +::: + +## Running the Application + + + + +If Harper is still running, shut it down using `CTRL/CMD + C`. + +Within your application directory, open a command line and run `harper dev .` + +The `dev` command will watch all files (except for `node_modules` directory) within your application directory and restart Harper when changes are detected. + + + + +Click "Restart Cluster" to apply the new file changes. + + + + + +## Enabling the REST API + +Navigate back to the `schema.graphql` file and add `@export` directive to the table schema: + +```graphql +type Dog @table @export { + id: ID @primaryKey + name: String + breed: String + age: Int +} +``` + +Then in `config.yaml` enable the REST API plugin: + +```yaml +graphqlSchema: + files: 'schema.graphql' +rest: true +``` + + + + +If Harper is still running with the `dev` command, it should have automatically restarted. + +If you look closely at the Harper logs, a new line should be added to the system configuration details: + +``` +REST: HTTP: 9926 +``` + +This line tells you that the Harper REST API is configured on port `9926` (this is configurable and this value is the default). + + + + +Click "Restart Cluster" to apply the new file changes. + + + + + +:::note +If you need to check your work, checkout the [`02-rest-api`](https://github.com/HarperFast/create-your-first-application/tree/02-rest-api) branch. +::: + +## Create a Record + +With everything in place, now its time to create your first record for the `Dog` table. + +With the automatic REST API generation you have a plethora of options for interacting with the `Dog` table. We'll keep it simple for now, but will explore everything this has to offer in later guides. + +Create a `PUT` request using the REST API port and the path `/Dog/001`. Include a JSON body with the specified attributes except for `id`. The `001` in the URL will be used as the ID for this entry. + +:::note +If you're using Fabric remember to replace the `localhost` with your cluster's URL +::: + + + + +```bash +curl 'http://localhost:9926/Dog/001' \ + -X PUT \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Harper", + "breed": "Black Labrador / Chow Mix", + "age": 5 + }' \ + -w "%{http_code}" +``` + + + + +```typescript +const response = await fetch('http://localhost:9926/Dog/001', { + method: 'PUT', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + name: 'Harper', + breed: 'Black Labrador / Chow Mix', + age: 5, + }), +}); +console.log(response.status); +``` + + + + +If you see `204` status code, then the record was successfully created! + +## Read a Record + +Now, with the returned ID, create a `GET` request to the endpoint `/Dog/001`: + + + + +```bash +curl -s 'http://localhost:9926/Dog/001' | jq +``` + + + + +```typescript +const response = await fetch('http://localhost:9926/Dog/001'); +const dog = await response.json(); +console.log(dog); +``` + + + + +You should see the record we just created returned as JSON: + +```json +{ + "name": "Harper", + "breed": "Black Labrador / Chow Mix", + "age": 5, + "id": "001" +} +``` + +## Query a Record + +The REST API isn't just for basic CRUD operations. It can also be used to create search queries using URL query strings. + +Start by creating another `GET` query, but this time do not include the ID (`001`) part. Make sure to include a trailing slash. Then, include a query string containing an attribute and a value such as `?age=5`. + + + + +```bash +curl -s 'http://localhost:9926/Dog/?age=5' | jq +``` + + + + +```typescript +const response = await fetch('http://localhost:9926/Dog/?age=5'); +const dog = await response.json(); +console.log(dog); +``` + + + + +Search queries return a list of records that match the specified conditions, in this example there is only one record in the table, so the result will be a list containing just that one record: + +```json +[ + { + "name": "Harper", + "breed": "Black Labrador / Chow Mix", + "age": 5, + "id": "001" + } +] +``` + +Fantastic work! You've successfully created your first Harper application. There is so much more that the Harper platform has to offer. Continue on to more guide content to learn more about building with Harper. + +## Bonus: Deploy your Application to Fabric + +If you have been developing your Harper application locally, this section will walk you through deploying it to Fabric. + +Before continuing, if you haven't already set up a Fabric cluster, go back to the previous article and complete the [Getting started with Fabric](./install-and-connect-harper.mdx#getting-started-with-fabric) step and make sure to keep track of the cluster URL, as well as the admin username and password. + +Harper supports both **pull** and **push** based deployment workflows. + +Pull-based deployments is generally powered by a Git repository where Harper will _pull_ your application from the repository. + +Push-based deployments is powered by the Harper CLI and is where your the user will _push_ your application to the Harper instance. + +For a true production application, Harper recommends using pull-based deployments so that you can deploy tagged versions of your application repository. But for development and experimentation, push-based is perfectly fine. Later guides will explore pull-based deployment workflows in more detail. + +To get started with push-based deployments, open a command line and set the current directory to the application directory. Run the `harper deploy` command using the Fabric cluster's URL, username, and password: + +```bash +harper deploy \ + target= \ + username= \ + password= \ + project=first-harper-app \ + restart=true \ + replicated=true +``` + +## Additional Resources + +- [Table Schema](../../docs/developers/applications/defining-schemas) reference +- [REST](../../docs/developers/rest) reference 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..a30f9354 --- /dev/null +++ b/learn/getting-started/install-and-connect-harper.mdx @@ -0,0 +1,218 @@ +--- +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 one was to be easy to install and get started with. The core Harper application itself is just a Node.js application with some native module dependencies. The simplest and easiest way to get started using Harper is by installing it using npm (or any npm compatible Node.js package manager). In addition to installing Harper directly to your local development environment, the Harper team provides a Docker image ([`harperdb/harperdb`](https://hub.docker.com/r/harperdb/harperdb)), and most recently a platform service called [Harper Fabric](https://fabric.harper.fast). + +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 using a Node.js package manager or a container +- How to use the `harper` CLI +- How to get setup using Harper Fabric +- 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](#getting-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 +``` + +Then, execute the Harper CLI: + +```bash +harper +``` + +When installing locally on your machine, you can specify any destination for Harper, we recommend using something within your home directory such as `$HOME/hdb`. Keep note of what you specify for the username and password. Make sure you select the `dev` default config and set the hostname to `localhost`. + +:::important +Do not actually enter `$HOME` in the destination prompt; it should automatically fill in the value of your home directory. Otherwise, specify the absolute path for the Harper installation. +::: + +``` +Starting HarperDB install... + +Terms & Conditions can be found at https://harperdb.io/legal/end-user-license-agreement +and can be viewed by typing or copying and pasting the URL into your web browser. +I agree to the HarperDB Terms and Conditions: (yes/no) yes +Please enter a destination for HarperDB: $HOME/hdb +Please enter a 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. +``` + + + + +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 $HOME/hdb:/home/harperdb/hdb \ + -v $HOME/dev:/home/harperdb/dev \ + -e DEFAULTS_MODE=dev \ + -e REPLICATION_HOSTNAME=localhost \ + -p 9925:9925 \ + -p 9926:9926 \ + harperdb/harperdb +``` + +The `-v` options will mount the Harper installation (`hdb/`) as well as a development directory (`dev/`) to the container host which is useful for development purposes. The `hdb/` path will contain the Harper installation parts, and the `dev/` directory can be used to create projects (which future guides will require). + +The additional environment variables specified by `-e` options ensures the installation is setup for local development. + +The image is configured to automatically run the `harper` command upon startup. During container creation, this will automatically complete the Harper installation step. + +The Harper installation process is normally an interactive prompt; however, it also supports overrides using environment variables or CLI arguments. Since the image contains preset environment variables and additional environment variables `DEFAULTS_MODE` and `REPLICATION_HOSTNAME` are included in the `docker run` command, Harper will complete its installation step completely non-interactively. + + + + +After completing the installation step, Harper should now be running in the active 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: + +``` +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, the domain socket path, and the Harper application version. Log lines are always prepended with the thread name, number, and log level. `[main/0]` is the main thread. `[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 followed by 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 on getting started with Harper Fabric. + +## 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 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](./create-your-first-application). + +## 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..f3b4e88c --- /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). 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..48fa1a7c 100644 --- a/redirects.ts +++ b/redirects.ts @@ -70,7 +70,10 @@ function generateDocsRedirects(basePath: string): RedirectRule[] { { from: withBase('/install-harperdb/node-ver-requirement'), to: withBase('/deployments/install-harper/') }, { from: withBase('/deployments/install-harperdb'), to: withBase('/deployments/install-harper/') }, { from: withBase('/deployments/install-harperdb/linux'), to: withBase('/deployments/install-harper/linux') }, - { from: withBase('/getting-started/install-harper'), to: withBase('/getting-started/installation') }, + { + from: withBase('/getting-started/install-harper'), + to: '/learn/getting-started/install-and-connect-harper', + }, // Harper Studio (old HarperDB Studio paths) { from: withBase('/harperdb-studio'), to: withBase('/administration/harper-studio/') }, @@ -177,8 +180,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: '/learn/' }, + { from: withBase('/4.6/getting-started'), to: '/learn/' }, + { from: withBase('/4.5/getting-started'), to: '/learn/' }, + { from: withBase('/4.4/getting-started'), to: '/learn/' }, + + { + from: withBase('/getting-started/installation'), + to: '/learn/getting-started/install-and-connect-harper', + }, + { + from: withBase('/4.6/getting-started/installation'), + to: '/learn/getting-started/install-and-connect-harper', + }, + { + from: withBase('/4.5/getting-started/installation'), + to: '/learn/getting-started/install-and-connect-harper', + }, + { + from: withBase('/4.4/getting-started/installation'), + to: '/learn/getting-started/install-and-connect-harper', + }, + + { from: withBase('/getting-started/quickstart'), to: '/learn/' }, + { from: withBase('/4.6/getting-started/quickstart'), to: '/learn/' }, + { from: withBase('/4.5/getting-started/quickstart'), to: '/learn/' }, + { from: withBase('/4.4/getting-started/quickstart'), to: '/learn/' }, + + { from: withBase('/foundations/harper-architecture'), to: '/learn/' }, + { from: withBase('/4.6/foundations/harper-architecture'), to: '/learn/' }, + { from: withBase('/4.5/foundations/harper-architecture'), to: '/learn/' }, + { from: withBase('/4.4/foundations/harper-architecture'), to: '/learn/' }, + + { from: withBase('/foundations/core-concepts'), to: '/learn/' }, + { from: withBase('/4.6/foundations/core-concepts'), to: '/learn/' }, + { from: withBase('/4.5/foundations/core-concepts'), to: '/learn/' }, + { from: withBase('/4.4/foundations/core-concepts'), to: '/learn/' }, + + { from: withBase('/foundations/use-cases'), to: '/learn/' }, + { from: withBase('/4.6/foundations/use-cases'), to: '/learn/' }, + { from: withBase('/4.5/foundations/use-cases'), to: '/learn/' }, + { from: withBase('/4.4/foundations/use-cases'), to: '/learn/' } ); return redirects; diff --git a/release-notes/v4-tucker/4.2.0.md b/release-notes/v4-tucker/4.2.0.md index b7f59936..d59172bd 100644 --- a/release-notes/v4-tucker/4.2.0.md +++ b/release-notes/v4-tucker/4.2.0.md @@ -8,7 +8,7 @@ title: 4.2.0 HarperDB 4.2 introduces a new interface to accessing our core database engine with faster access, well-typed idiomatic JavaScript interfaces, ergonomic object mapping, and real-time data subscriptions. 4.2 also had adopted a new component architecture for building extensions to deliver customized external data sources, authentication, file handlers, content types, and more. These architectural upgrades lead to several key new HarperDB capabilities including a new REST interface, advanced caching, real-time messaging and publish/subscribe functionality through MQTT, WebSockets, and Server-Sent Events. -4.2 also introduces configurable database schemas, using GraphQL Schema syntax. The new component structure is also configuration-driven, providing easy, low-code paths to building applications. [Check out our new getting starting guide](/docs/getting-started/quickstart) to see how easy it is to get started with HarperDB apps. +4.2 also introduces configurable database schemas using GraphQL Schema syntax. The new component structure is also configuration-driven, providing easy, low-code paths to building applications. [Check out our new getting starting guide](/learn/) to see how easy it is to get started with HarperDB apps. ### Resource API diff --git a/scripts/preview-pr.mjs b/scripts/preview-pr.mjs index 48adef74..8e9b3f6a 100644 --- a/scripts/preview-pr.mjs +++ b/scripts/preview-pr.mjs @@ -98,7 +98,7 @@ async function main() { // Get the workflow run for this PR (using sanitized branch name) const runs = JSON.parse( execSync( - `gh api repos/HarperDB/documentation/actions/runs --paginate -X GET -f branch=${sanitizedBranch} --jq '.workflow_runs | map(select(.conclusion == "success" and .name == "Deploy Docusaurus to GitHub Pages")) | sort_by(.created_at) | reverse | .[0]'`, + `gh api repos/HarperFast/documentation/actions/runs --paginate -X GET -f branch=${sanitizedBranch} --jq '.workflow_runs | map(select(.conclusion == "success" and .name == "Deploy PR Preview")) | sort_by(.created_at) | reverse | .[0]'`, { encoding: 'utf-8' } ) ); @@ -121,15 +121,16 @@ async function main() { // Get the artifacts for this run const artifacts = JSON.parse( - execSync(`gh api repos/HarperDB/documentation/actions/runs/${runs.id}/artifacts --jq '.artifacts'`, { + execSync(`gh api repos/HarperFast/documentation/actions/runs/${runs.id}/artifacts --jq '.artifacts'`, { encoding: 'utf-8', }) ); - const artifact = artifacts.find((a) => a.name === 'github-pages'); + const artifactName = `pr-${PR_NUMBER}-build`; + const artifact = artifacts.find((a) => a.name === artifactName); if (!artifact) { - console.error(`❌ No 'github-pages' artifact found for this PR`); + console.error(`❌ No '${artifactName}' artifact found for this PR`); process.exit(1); } @@ -161,7 +162,7 @@ async function main() { // Download the artifact console.log('⬇️ Downloading artifact...'); const artifactZip = join(PR_DIR, 'artifact.zip'); - execSync(`gh api repos/HarperDB/documentation/actions/artifacts/${artifact.id}/zip > "${artifactZip}"`, { + execSync(`gh api repos/HarperFast/documentation/actions/artifacts/${artifact.id}/zip > "${artifactZip}"`, { stdio: 'inherit', }); @@ -170,18 +171,10 @@ async function main() { throw new Error('Downloaded artifact file not found'); } - // Extract the artifact (it's a tar.gz inside a zip) + // Extract the artifact (it's a direct zip of the build directory) console.log('📂 Extracting artifact...'); - execSync(`unzip -q "${artifactZip}" -d "${PR_DIR}"`, { stdio: 'inherit' }); - - // The github-pages artifact contains a tar.gz file - const tarFile = join(PR_DIR, 'artifact.tar'); - if (existsSync(tarFile)) { - mkdirSync(BUILD_DIR, { recursive: true }); - execSync(`tar -xzf "${tarFile}" -C "${BUILD_DIR}"`, { stdio: 'inherit' }); - } else { - throw new Error('Expected artifact.tar not found in artifact'); - } + mkdirSync(BUILD_DIR, { recursive: true }); + execSync(`unzip -q "${artifactZip}" -d "${BUILD_DIR}"`, { stdio: 'inherit' }); // Verify extracted files are within expected directory const resolvedBuildDir = join(BUILD_DIR); @@ -189,9 +182,8 @@ async function main() { throw new Error('Security violation: extracted files outside preview directory'); } - // Clean up compressed files + // Clean up zip file rmSync(artifactZip, { force: true }); - rmSync(tarFile, { force: true }); console.log('\n✅ Preview ready!\n'); console.log(`📁 Build location: ${BUILD_DIR}`); @@ -208,7 +200,10 @@ async function main() { console.log(`\n🚀 Starting preview server...\n`); // Start the server with quoted path to prevent injection - execSync(`npm run serve -- --dir "${BUILD_DIR}"`, { stdio: 'inherit' }); + execSync(`npm run serve -- --dir "${BUILD_DIR}"`, { + stdio: 'inherit', + env: { ...process.env, DOCUSAURUS_BASE_URL: `pr-${PR_NUMBER}` }, + }); } catch (error) { console.error('\n❌ Error:', error.message); process.exit(1); diff --git a/sidebars.ts b/sidebars.ts index f2527587..9219ecf8 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -7,16 +7,6 @@ const sidebars: SidebarsConfig = { 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/sidebarsFabric.ts b/sidebarsFabric.ts index 9a85e6d5..a64d356b 100644 --- a/sidebarsFabric.ts +++ b/sidebarsFabric.ts @@ -52,7 +52,7 @@ const sidebarsFabric: SidebarsConfig = { id: 'grafana-integration', label: 'Grafana Integration', }, - { type: 'autogenerated', dirName: 'fabric' }, + // { type: 'autogenerated', dirName: 'fabric' }, ], }; diff --git a/sidebarsLearn.ts b/sidebarsLearn.ts new file mode 100644 index 00000000..104dd40b --- /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..832c3c0f --- /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.4/index.md b/versioned_docs/version-4.4/index.md index 71b197fb..243d13e7 100644 --- a/versioned_docs/version-4.4/index.md +++ b/versioned_docs/version-4.4/index.md @@ -39,7 +39,7 @@ Finally, when it’s time to deploy, explore [replication](./developers/replicat If you would like to jump into the most advanced capabilities, learn about [components](developers/components/index.md). -For a more comprehensive deep dive, take a look at our [Getting Started Guide](./getting-started/quickstart). +For a more comprehensive deep dive, take a look at our [Getting Started Guide](/learn/). :::warning Need help? Please don’t hesitate to [reach out](https://www.harpersystems.dev/contact). @@ -68,7 +68,7 @@ Capturing, storing, and processing real-time data streams from client and IoT sy

- + Quickstart

diff --git a/versioned_docs/version-4.4/reference/globals.md b/versioned_docs/version-4.4/reference/globals.md index 6256d50c..68742736 100644 --- a/versioned_docs/version-4.4/reference/globals.md +++ b/versioned_docs/version-4.4/reference/globals.md @@ -38,7 +38,7 @@ async function getRecord() { } ``` -It is recommended that you [define a database](../getting-started/quickstart) for all the tables that are required to exist in your application. This will ensure that the tables exist on the `tables` object. Also note that the property names follow a CamelCase convention for use in JavaScript and in the GraphQL Schemas, but these are translated to snake_case for the actual table names, and converted back to CamelCase when added to the `tables` object. +It is recommended that you [define a database](/learn/) for all the tables that are required to exist in your application. This will ensure that the tables exist on the `tables` object. Also note that the property names follow a CamelCase convention for use in JavaScript and in the GraphQL Schemas, but these are translated to snake_case for the actual table names, and converted back to CamelCase when added to the `tables` object. ## `databases` diff --git a/versioned_docs/version-4.5/developers/applications/index.md b/versioned_docs/version-4.5/developers/applications/index.md index 0de66484..02ab0974 100644 --- a/versioned_docs/version-4.5/developers/applications/index.md +++ b/versioned_docs/version-4.5/developers/applications/index.md @@ -34,7 +34,7 @@ flowchart LR ## Custom Functionality with JavaScript -[The getting started guide](../../getting-started/quickstart) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +[The getting started guide](/learn/) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: 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..d697bec7 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/developers/applications/index.md b/versioned_docs/version-4.6/developers/applications/index.md index 1d1ddaa8..804a219d 100644 --- a/versioned_docs/version-4.6/developers/applications/index.md +++ b/versioned_docs/version-4.6/developers/applications/index.md @@ -81,7 +81,7 @@ This guide is going to walk you through building a basic Harper application usin ## Custom Functionality with JavaScript -[The getting started guide](../getting-started/quickstart) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +[The getting started guide](/learn) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: @@ -117,8 +117,8 @@ type Breed @table { We use the new table's (static) `get()` method to retrieve a breed by id. Harper will maintain the current context, ensuring that we are accessing the data atomically, in a consistent snapshot across tables. This provides: 1. Automatic tracking of most recently updated timestamps across resources for caching purposes -1. Sharing of contextual metadata (like user who requested the data) -1. Transactional atomicity for any writes (not needed in this get operation, but important for other operations) +2. Sharing of contextual metadata (like user who requested the data) +3. Transactional atomicity for any writes (not needed in this get operation, but important for other operations) The resource methods are automatically wrapped with a transaction and will automatically commit the changes when the method finishes. This allows us to fully utilize multiple resources in our current transaction. With our own snapshot of the database for the Dog and Breed table we can then access data like this: 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..ee58c9ac 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/developers/applications/index.md b/versioned_docs/version-4.7/developers/applications/index.md index 0a8b9499..5f498f0e 100644 --- a/versioned_docs/version-4.7/developers/applications/index.md +++ b/versioned_docs/version-4.7/developers/applications/index.md @@ -81,7 +81,7 @@ This guide is going to walk you through building a basic Harper application usin ## Custom Functionality with JavaScript -[The getting started guide](../getting-started/quickstart) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. +[The getting started guide](/learn/) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../reference/resources/), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class. To define custom (JavaScript) resources as endpoints, we need to create a `resources.js` module (this goes in the root of your application folder). And then endpoints can be defined with Resource classes that `export`ed. This can be done in addition to, or in lieu of the `@export`ed types in the schema.graphql. If you are exporting and extending a table you defined in the schema make sure you remove the `@export` from the schema so that don't export the original table or resource to the same endpoint/path you are exporting with a class. Resource classes have methods that correspond to standard HTTP/REST methods, like `get`, `post`, `patch`, and `put` to implement specific handling for any of these methods (for tables they all have default implementations). To do this, we get the `Dog` class from the defined tables, extend it, and export it: @@ -117,8 +117,8 @@ type Breed @table { We use the new table's (static) `get()` method to retrieve a breed by id. Harper will maintain the current context, ensuring that we are accessing the data atomically, in a consistent snapshot across tables. This provides: 1. Automatic tracking of most recently updated timestamps across resources for caching purposes -1. Sharing of contextual metadata (like user who requested the data) -1. Transactional atomicity for any writes (not needed in this get operation, but important for other operations) +2. Sharing of contextual metadata (like user who requested the data) +3. Transactional atomicity for any writes (not needed in this get operation, but important for other operations) The resource methods are automatically wrapped with a transaction and will automatically commit the changes when the method finishes. This allows us to fully utilize multiple resources in our current transaction. With our own snapshot of the database for the Dog and Breed table we can then access data like this: 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..ee58c9ac 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",