From d1721db124dc65b9a4613318206a278b5702bab5 Mon Sep 17 00:00:00 2001 From: bari124 <157635528+bari124@users.noreply.github.com> Date: Fri, 27 Mar 2026 15:14:46 -0400 Subject: [PATCH 1/4] docs(fabric): add Custom Domains page --- fabric/custom-domains.md | 126 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 fabric/custom-domains.md diff --git a/fabric/custom-domains.md b/fabric/custom-domains.md new file mode 100644 index 00000000..9efa5beb --- /dev/null +++ b/fabric/custom-domains.md @@ -0,0 +1,126 @@ +--- +title: Custom Domains +--- + + +# Custom Domains + + +## What are Custom Domains? + + +Custom domains allow you to serve your Harper Fabric cluster from your own domain (e.g., `api.yourcompany.com`) instead of the default `..harperfabric.com` URL. Harper Fabric handles domain verification, DNS validation, and TLS certificate provisioning — all from within the Fabric Studio UI. + + +## Prerequisites + + +Before adding a custom domain, make sure you have: + + +- An existing Harper Fabric cluster (see [Cluster Creation & Management](/fabric/cluster-creation-management) if you need to create one) +- A domain or subdomain that you own (e.g., `api.example.com`, `data.mycompany.io`) +- Access to your DNS registrar or DNS management provider (e.g., Cloudflare, Route 53, GoDaddy, Namecheap) + + +## Adding a Custom Domain + + +1. Navigate to your cluster’s page within your organization. +2. Select **Config** from the top navigation menu. +3. Select **Domains** from the left sidebar. +4. Enter your domain in the **New Domain Name** field — for example, `api.example.com` or `example.com`. +5. Click the **+ Add** button. + + +Harper Fabric will register the domain and display the DNS records you need to configure. A confirmation notification will appear: *“Domain added! Please add the TXT record above to your domain registrar.”* + + +## Configuring DNS Records + + +After adding your domain, Fabric displays two DNS records in the **Next Steps** column of the domains table. You will need to add both of these records at your DNS registrar. + + +### TXT Record (Domain Verification) + + +This record proves that you own the domain. Add the following to your DNS registrar: + + +- **Type**: `TXT` +- **Name**: `_fabric.` (e.g., `_fabric.api.example.com`) +- **TTL**: Auto +- **Content**: The unique verification string displayed in the Fabric UI + + +(Note: Use the copy buttons next to each value in the Fabric UI to avoid typos.) + + +### CNAME Record (Traffic Routing) + + +This record points your domain to your Harper Fabric cluster. Add the following to your DNS registrar: + + +- **Type**: `CNAME` +- **Name**: Your subdomain prefix (e.g., `api` for `api.example.com`) +- **TTL**: Auto +- **Target**: Your cluster’s Fabric hostname (e.g., `my-cluster.my-org.harperfabric.com`) + + +(Note: If you’re using a root/apex domain like `example.com`, some DNS providers don’t support CNAME records at the root. Check with your provider for ALIAS or CNAME flattening support.) + + +## Validating Your Domain + + +After adding both DNS records at your registrar, you’ll need to wait for DNS propagation. This typically takes a few minutes to an hour, depending on your TTL settings. + + +Once your DNS records have propagated: + + +1. Return to **Config** → **Domains** in your cluster. +2. Click the **Validate** button at the top of the page. + + +Fabric will verify that the required TXT record exists and confirm domain ownership. If validation fails, double-check that the TXT record **Name** and **Content** values match exactly what Fabric provided, then wait a few more minutes and try again. + + +You can verify DNS propagation yourself using tools like [dnschecker.org](https://dnschecker.org) or the command line: + + +```bash +dig _fabric.api.example.com TXT +``` + + +## Binding the Domain + + +After successful validation, use the **Bind** column in the domains table to bind the domain to your cluster. Once bound, traffic to your custom domain will be routed to your Harper Fabric cluster and TLS certificates will be provisioned automatically. + + +## Managing Domains + + +From the **Config** → **Domains** page, you can manage all custom domains associated with your cluster: + + +- **Add additional domains**: Repeat the process above for each domain you want to connect. +- **Remove a domain**: Click **Remove Domain** next to the domain entry in the table. (Note: Don’t forget to also clean up the corresponding DNS records at your registrar.) +- **Refresh status**: Click the **Refresh** button to update the validation status of all domains. + + +Each domain entry also displays a unique **Domain ID** (e.g., `dom-xxxxxxxxxxxx`) for reference. + + +## Additional Information + + +- TLS certificates are managed automatically by Harper Fabric once a domain is validated and bound. You can also manage custom certificates under the **Certificates** section in Config. +- You can add multiple custom domains to the same cluster. +- Your cluster’s default Fabric hostname can be found on the **Config** → **Overview** page under **Application URL**. +- DNS propagation can take up to 24–48 hours in rare cases, though it typically completes within minutes. + From e81421c9420c3740407ca4457c46dbba317c2100 Mon Sep 17 00:00:00 2001 From: bari124 <157635528+bari124@users.noreply.github.com> Date: Fri, 27 Mar 2026 15:17:14 -0400 Subject: [PATCH 2/4] docs(fabric): add custom-domains to sidebar navigation --- sidebarsFabric.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/sidebarsFabric.ts b/sidebarsFabric.ts index a64d356b..1045763b 100644 --- a/sidebarsFabric.ts +++ b/sidebarsFabric.ts @@ -1,5 +1,8 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; + + + const sidebarsFabric: SidebarsConfig = { fabricSidebar: [ { @@ -27,6 +30,11 @@ const sidebarsFabric: SidebarsConfig = { id: 'cluster-creation-management', label: 'Cluster Creation & Management', }, + { + type: 'doc', + id: 'custom-domains', + label: 'Custom Domains', + }, { type: 'doc', id: 'managing-applications', @@ -56,4 +64,10 @@ const sidebarsFabric: SidebarsConfig = { ], }; + + + export default sidebarsFabric; + + + From 2c480111a69e8c091bcd6a311a93e31ac7909d6f Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Mon, 30 Mar 2026 12:25:18 -0400 Subject: [PATCH 3/4] =?UTF-8?q?docs(fabric):=20Add=20some=20technical=20no?= =?UTF-8?q?tes=20to=20Bari=E2=80=99s=20bountiful=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- fabric/custom-domains.md | 46 +++++++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 10 deletions(-) diff --git a/fabric/custom-domains.md b/fabric/custom-domains.md index 9efa5beb..0e4656c2 100644 --- a/fabric/custom-domains.md +++ b/fabric/custom-domains.md @@ -23,14 +23,27 @@ Before adding a custom domain, make sure you have: - Access to your DNS registrar or DNS management provider (e.g., Cloudflare, Route 53, GoDaddy, Namecheap) +## Accessing Domain Configuration + +Domain configuration is accessible through two primary paths: + +1. **From the Fabric Dashboard:** + - Log in to [https://fabric.harper.fast/](https://fabric.harper.fast/). + - Click on your organization name. + - Locate the cluster you want to configure and click the context menu (three dots "**...**"). + - Select the **Domains** configuration option. +2. **From Cluster Configuration:** + - Navigate to your cluster’s page within your organization. + - Select **Config** from the top navigation menu. + - Select **Domains** from the left sidebar. + + ## Adding a Custom Domain -1. Navigate to your cluster’s page within your organization. -2. Select **Config** from the top navigation menu. -3. Select **Domains** from the left sidebar. -4. Enter your domain in the **New Domain Name** field — for example, `api.example.com` or `example.com`. -5. Click the **+ Add** button. +1. Access domain configuration using one of the paths above. +2. Enter your domain in the **New Domain Name** field — for example, `api.example.com` or `example.com`. +3. Click the **+ Add** button. Harper Fabric will register the domain and display the DNS records you need to configure. A confirmation notification will appear: *“Domain added! Please add the TXT record above to your domain registrar.”* @@ -60,8 +73,7 @@ This record proves that you own the domain. Add the following to your DNS regist ### CNAME Record (Traffic Routing) -This record points your domain to your Harper Fabric cluster. Add the following to your DNS registrar: - +After ownership is verified, you will be instructed to add a CNAME record to your domain registrar pointing to the Harper Fabric load balancer. - **Type**: `CNAME` - **Name**: Your subdomain prefix (e.g., `api` for `api.example.com`) @@ -69,7 +81,14 @@ This record points your domain to your Harper Fabric cluster. Add the following - **Target**: Your cluster’s Fabric hostname (e.g., `my-cluster.my-org.harperfabric.com`) -(Note: If you’re using a root/apex domain like `example.com`, some DNS providers don’t support CNAME records at the root. Check with your provider for ALIAS or CNAME flattening support.) +:::info Apex Domains +Some registrars do not support CNAME records for apex domains (e.g., `yourdomain.com`). In this case, we recommend: + +1. Registering a subdomain like `www.yourdomain.com`. +2. Redirecting the apex domain (`@` or `yourdomain.com`) to the `www` subdomain. + +Alternatively, check if your provider supports ALIAS or CNAME flattening. +::: ## Validating Your Domain @@ -78,7 +97,7 @@ This record points your domain to your Harper Fabric cluster. Add the following After adding both DNS records at your registrar, you’ll need to wait for DNS propagation. This typically takes a few minutes to an hour, depending on your TTL settings. -Once your DNS records have propagated: +Once your DNS records have propagated (this may take **10 minutes** or more): 1. Return to **Config** → **Domains** in your cluster. @@ -99,7 +118,14 @@ dig _fabric.api.example.com TXT ## Binding the Domain -After successful validation, use the **Bind** column in the domains table to bind the domain to your cluster. Once bound, traffic to your custom domain will be routed to your Harper Fabric cluster and TLS certificates will be provisioned automatically. +After successful validation, use the **Bind** column in the domains table to bind the domain to your cluster. + +Once bound, Harper Fabric will automatically begin generating an SSL certificate for your domain: + +- This process typically takes **5-10 minutes**. +- The interface will show you the progress as it goes. + +Everything should be working once the SSL certificate is successfully generated! Traffic to your custom domain will then be routed to your Harper Fabric cluster. ## Managing Domains From 80d69921604fac9128c6b4a9503a6c7dd0ddefeb Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Mon, 30 Mar 2026 12:27:45 -0400 Subject: [PATCH 4/4] chore: Run formatter --- docs/developers/applications/caching.md | 14 ++++----- fabric/custom-domains.md | 39 ++----------------------- sidebarsFabric.ts | 9 ------ 3 files changed, 9 insertions(+), 53 deletions(-) diff --git a/docs/developers/applications/caching.md b/docs/developers/applications/caching.md index fd0f1c06..dbd9819a 100644 --- a/docs/developers/applications/caching.md +++ b/docs/developers/applications/caching.md @@ -318,14 +318,14 @@ Or to disable caching on a get operation: await Post.get(primaryKey, { noCache: true, noCacheStore: true }); ``` -| Cache-Control Header Directive | Context Directive Equivalent | Definition | -| ------------------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `max-age` | `expiresAt` | Specifies the time in seconds at which the record is scheduled to expire. | -| `no-store` | `noCacheStore` | Prevents the resource from being cached or stored. | -| `no-cache` | `noCache` | Forces revalidation with the origin server before using cached data. | -| `only-if-cached` | `onlyIfCached` | Returns the resource only if it is already cached, otherwise fails with 504 response. | +| Cache-Control Header Directive | Context Directive Equivalent | Definition | +| ------------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `max-age` | `expiresAt` | Specifies the time in seconds at which the record is scheduled to expire. | +| `no-store` | `noCacheStore` | Prevents the resource from being cached or stored. | +| `no-cache` | `noCache` | Forces revalidation with the origin server before using cached data. | +| `only-if-cached` | `onlyIfCached` | Returns the resource only if it is already cached, otherwise fails with 504 response. | | `must-revalidate` | `mustRevalidate` | Once a resource becomes stale (i.e. past its max-age), the client must contact the origin server to revalidate before using it. It cannot serve the stale copy even as a fallback. | -| `stale-if-error` | `staleIfError` | Allows serving stale resources when the origin server encounters an error. | +| `stale-if-error` | `staleIfError` | Allows serving stale resources when the origin server encounters an error. | ## Caching Flow diff --git a/fabric/custom-domains.md b/fabric/custom-domains.md index 0e4656c2..aa800922 100644 --- a/fabric/custom-domains.md +++ b/fabric/custom-domains.md @@ -2,27 +2,20 @@ title: Custom Domains --- - # Custom Domains - ## What are Custom Domains? - Custom domains allow you to serve your Harper Fabric cluster from your own domain (e.g., `api.yourcompany.com`) instead of the default `..harperfabric.com` URL. Harper Fabric handles domain verification, DNS validation, and TLS certificate provisioning — all from within the Fabric Studio UI. - ## Prerequisites - Before adding a custom domain, make sure you have: - - An existing Harper Fabric cluster (see [Cluster Creation & Management](/fabric/cluster-creation-management) if you need to create one) - A domain or subdomain that you own (e.g., `api.example.com`, `data.mycompany.io`) - Access to your DNS registrar or DNS management provider (e.g., Cloudflare, Route 53, GoDaddy, Namecheap) - ## Accessing Domain Configuration Domain configuration is accessible through two primary paths: @@ -37,42 +30,31 @@ Domain configuration is accessible through two primary paths: - Select **Config** from the top navigation menu. - Select **Domains** from the left sidebar. - ## Adding a Custom Domain - 1. Access domain configuration using one of the paths above. 2. Enter your domain in the **New Domain Name** field — for example, `api.example.com` or `example.com`. 3. Click the **+ Add** button. - -Harper Fabric will register the domain and display the DNS records you need to configure. A confirmation notification will appear: *“Domain added! Please add the TXT record above to your domain registrar.”* - +Harper Fabric will register the domain and display the DNS records you need to configure. A confirmation notification will appear: _“Domain added! Please add the TXT record above to your domain registrar.”_ ## Configuring DNS Records - After adding your domain, Fabric displays two DNS records in the **Next Steps** column of the domains table. You will need to add both of these records at your DNS registrar. - ### TXT Record (Domain Verification) - This record proves that you own the domain. Add the following to your DNS registrar: - - **Type**: `TXT` - **Name**: `_fabric.` (e.g., `_fabric.api.example.com`) - **TTL**: Auto - **Content**: The unique verification string displayed in the Fabric UI - (Note: Use the copy buttons next to each value in the Fabric UI to avoid typos.) - ### CNAME Record (Traffic Routing) - After ownership is verified, you will be instructed to add a CNAME record to your domain registrar pointing to the Harper Fabric load balancer. - **Type**: `CNAME` @@ -80,7 +62,6 @@ After ownership is verified, you will be instructed to add a CNAME record to you - **TTL**: Auto - **Target**: Your cluster’s Fabric hostname (e.g., `my-cluster.my-org.harperfabric.com`) - :::info Apex Domains Some registrars do not support CNAME records for apex domains (e.g., `yourdomain.com`). In this case, we recommend: @@ -90,35 +71,26 @@ Some registrars do not support CNAME records for apex domains (e.g., `yourdomain Alternatively, check if your provider supports ALIAS or CNAME flattening. ::: - ## Validating Your Domain - After adding both DNS records at your registrar, you’ll need to wait for DNS propagation. This typically takes a few minutes to an hour, depending on your TTL settings. - Once your DNS records have propagated (this may take **10 minutes** or more): - 1. Return to **Config** → **Domains** in your cluster. 2. Click the **Validate** button at the top of the page. - Fabric will verify that the required TXT record exists and confirm domain ownership. If validation fails, double-check that the TXT record **Name** and **Content** values match exactly what Fabric provided, then wait a few more minutes and try again. - You can verify DNS propagation yourself using tools like [dnschecker.org](https://dnschecker.org) or the command line: - ```bash dig _fabric.api.example.com TXT ``` - ## Binding the Domain - -After successful validation, use the **Bind** column in the domains table to bind the domain to your cluster. +After successful validation, use the **Bind** column in the domains table to bind the domain to your cluster. Once bound, Harper Fabric will automatically begin generating an SSL certificate for your domain: @@ -127,26 +99,19 @@ Once bound, Harper Fabric will automatically begin generating an SSL certificate Everything should be working once the SSL certificate is successfully generated! Traffic to your custom domain will then be routed to your Harper Fabric cluster. - ## Managing Domains - From the **Config** → **Domains** page, you can manage all custom domains associated with your cluster: - - **Add additional domains**: Repeat the process above for each domain you want to connect. - **Remove a domain**: Click **Remove Domain** next to the domain entry in the table. (Note: Don’t forget to also clean up the corresponding DNS records at your registrar.) - **Refresh status**: Click the **Refresh** button to update the validation status of all domains. - Each domain entry also displays a unique **Domain ID** (e.g., `dom-xxxxxxxxxxxx`) for reference. - ## Additional Information - - TLS certificates are managed automatically by Harper Fabric once a domain is validated and bound. You can also manage custom certificates under the **Certificates** section in Config. - You can add multiple custom domains to the same cluster. - Your cluster’s default Fabric hostname can be found on the **Config** → **Overview** page under **Application URL**. - DNS propagation can take up to 24–48 hours in rare cases, though it typically completes within minutes. - diff --git a/sidebarsFabric.ts b/sidebarsFabric.ts index 1045763b..529e8778 100644 --- a/sidebarsFabric.ts +++ b/sidebarsFabric.ts @@ -1,8 +1,5 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; - - - const sidebarsFabric: SidebarsConfig = { fabricSidebar: [ { @@ -64,10 +61,4 @@ const sidebarsFabric: SidebarsConfig = { ], }; - - - export default sidebarsFabric; - - -