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 new file mode 100644 index 00000000..aa800922 --- /dev/null +++ b/fabric/custom-domains.md @@ -0,0 +1,117 @@ +--- +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: + +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. 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.”_ + +## 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` +- **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`) + +:::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 + +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. + +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 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 a64d356b..529e8778 100644 --- a/sidebarsFabric.ts +++ b/sidebarsFabric.ts @@ -27,6 +27,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',