> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qirtaas.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting

> Implement the /v1 contract on your own backend and point the SDK at it.

The SDK is backend-agnostic: it talks to whatever `apiUrl` you give it, over
the [frozen `/v1` contract](/backend/documents). Self-hosting means
implementing that contract on your own backend and pointing the SDK at it.

```ts theme={null}
const qirtaas = createQirtaasClient({
  apiUrl: "https://qirtaas.your-domain.com", // your deployment
  getToken: () => fetchEmbedToken(),
});
```

Everything else in these docs — mounting, autosave, the renderer's auth modes —
is identical to the managed cloud.

## What your backend must provide

<Steps>
  <Step title="The /v1 document endpoints">
    List/create/read/update/delete plus the shared-token read, exactly as
    specified in the [Documents API](/backend/documents). Paths are rooted at
    `<apiUrl>/v1/…`.
  </Step>

  <Step title="Bearer-token auth">
    The editor sends `Authorization: Bearer <token>` with whatever your
    `getToken` returns. On your own backend you control both sides, so this
    can be the standard [embed-token exchange](/backend/authentication) or any
    token scheme of yours — the SDK only requires that a `401` means "refresh
    via getToken and retry once". If the token is a JWT with an `exp` claim,
    the SDK also refreshes proactively before expiry.
  </Step>

  <Step title="Signature verification (renderers only)">
    For cross-user reads, verify `?sig=&exp=` as HMAC-SHA256 over
    `"<doc_id>|<exp>"` — see
    [Signatures](/backend/authentication#signatures-cross-user-reads).
  </Step>

  <Step title="Quran / hadith content">
    The editor's insertion dialogs read `/v1/quran/…` and `/v1/hadith/…`, so
    your backend needs to serve those endpoints and source the underlying
    datasets. On the managed cloud they are hosted and kept current for you.
  </Step>

  <Step title="Image storage">
    The upload/confirm/url image endpoints backed by S3-compatible storage,
    if your documents include images.
  </Step>
</Steps>

## When to choose this

While Qirtaas seems simple, the backend that powers it isn't. To self-host it, you need:

1. Elasticsearch for content API
2. S3-compatible storage
3. Background job processing for content API syncing

You should self host if you already have a cluster that you can deploy these services to, or if you don't need all of the features in Qirtaas.
For the trade-offs, see
[Self-host vs Cloud](/get-started/self-host-vs-cloud).