From ff3c5d9e371d2ca1cfd765195e803dd452105593 Mon Sep 17 00:00:00 2001 From: adityaoberai Date: Thu, 21 May 2026 01:08:58 +0530 Subject: [PATCH 1/5] Add CAA records docs --- .../docs/products/network/+layout.svelte | 4 + .../network/caa-records/+page.markdoc | 112 ++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 src/routes/docs/products/network/caa-records/+page.markdoc diff --git a/src/routes/docs/products/network/+layout.svelte b/src/routes/docs/products/network/+layout.svelte index c6bccf0bb75..fe7304d018f 100644 --- a/src/routes/docs/products/network/+layout.svelte +++ b/src/routes/docs/products/network/+layout.svelte @@ -45,6 +45,10 @@ label: 'DNS', href: '/docs/products/network/dns' }, + { + label: 'CAA records', + href: '/docs/products/network/caa-records' + }, { label: 'DDoS mitigation', href: '/docs/products/network/ddos' diff --git a/src/routes/docs/products/network/caa-records/+page.markdoc b/src/routes/docs/products/network/caa-records/+page.markdoc new file mode 100644 index 00000000000..7edb8025fe0 --- /dev/null +++ b/src/routes/docs/products/network/caa-records/+page.markdoc @@ -0,0 +1,112 @@ +--- +layout: article +title: CAA records +description: Learn what DNS Certification Authority Authorization (CAA) records are, when they are required to use a custom domain with Appwrite, and how to configure one or more of them at your DNS provider. +--- + +A Certification Authority Authorization (CAA) record is a DNS record that specifies which certificate authorities (CAs) are allowed to issue TLS certificates for your domain. CAA records help prevent unauthorized certificate issuance and are defined in [RFC 8659](https://datatracker.ietf.org/doc/html/rfc8659). + +When Appwrite issues a TLS certificate for a [custom domain](/docs/advanced/platform/custom-domains), an [Appwrite Sites domain](/docs/products/sites/domains), or a [Function domain](/docs/products/functions/domains), the certificate authority used by Appwrite checks your domain's CAA records before issuing. If your CAA records do not authorize the CA that Appwrite uses, issuance fails and your domain stays unverified. + +{% info title="CAA records are additive, not exclusive" %} +Adding a CAA record for Appwrite does **not** replace your existing CAA records, override certificates issued by other CAs, or invalidate certificates already in use elsewhere. CAA only controls **future** certificate issuance. You can safely keep every CAA record you already have and add Appwrite's alongside them. See [Setting multiple CAA records](#multiple). +{% /info %} + +# Certificate authorities used by Appwrite {% #certificate-authorities %} + +The CA that needs authorization depends on your deployment. + +| Deployment | Certificate authority | CAA value | +| ---------- | --------------------- | --------- | +| Appwrite Cloud (Sites, Functions, custom domains) | [Certainly](https://docs.fastly.com/products/certainly) (operated by Fastly) | `certainly.com` | +| Self-hosted | [Let's Encrypt](https://letsencrypt.org/) | `letsencrypt.org` | + +For more on how Appwrite manages certificates, see the [TLS documentation](/docs/advanced/security/tls). + +# When CAA records are optional {% #optional %} + +CAA records are not mandatory in DNS. If your domain has no CAA records at all, any publicly trusted CA, including the one Appwrite uses, is permitted to issue a certificate for it. In this case, you do not need to add a CAA record to use a custom domain with Appwrite. + +This is the common case for most domains that have never been configured with a CAA policy. + +# When CAA records are required {% #required %} + +You must add a CAA record that authorizes Appwrite's CA in any of these situations. + +- Your domain already has one or more CAA records that do not include `certainly.com` (Appwrite Cloud) or `letsencrypt.org` (self-hosted). Existing CAA records form an allow-list, and any CA not on it is blocked. +- Your DNS provider, registrar, or organization adds CAA records automatically for new domains. +- The Appwrite Console shows a CAA record alongside the CNAME or NS record when adding a domain. The Console only shows CAA records when one is needed for your domain to be verified. + +If you are unsure, you can inspect existing CAA records for your domain with a public tool like [DNS Checker](https://dnschecker.org/) or by running `dig CAA example.com` from a terminal. + +## Apex domains and subdomains {% #scope %} + +CAA records are scoped to where they sit in DNS, so adding one for Appwrite does not have to touch your main domain. + +- A CAA record at an apex like `example.com` applies to the apex and is inherited by every subdomain that does **not** have its own CAA records. +- A CAA record at a subdomain like `app.example.com` applies only to that subdomain. As soon as a subdomain has any CAA record of its own, the inherited apex records are ignored for that subdomain. + +If you are adding an Appwrite Site or custom domain on a subdomain and you already have a CAA policy at the apex for another CA, you have two safe choices. + +1. Add Appwrite's CAA record at the subdomain only. This leaves your apex policy untouched and lets the apex CA continue issuing certificates for the apex domain. +2. Add Appwrite's CAA record at the apex alongside your existing CAA records. Both CAs remain authorized everywhere. See [Setting multiple CAA records](#multiple). + +# How to add a CAA record {% #add %} + +The exact UI differs between DNS providers, but the values are the same. + +1. Open your DNS provider's DNS management dashboard. +2. Create a new record and select **CAA** as the record type. +3. Set the **name** (or **host**) to the domain you are configuring, for example `example.com` for an apex domain or `app.example.com` for a subdomain. +4. Set the **flags** to `0`. +5. Set the **tag** to `issue`. +6. Set the **value** to the CA shown in the Appwrite Console, for example `certainly.com` on Appwrite Cloud. +7. Save the record and wait for DNS propagation. This can take up to 48 hours. + +A complete CAA record in zone file format looks like this. + +```text +example.com. IN CAA 0 issue "certainly.com" +``` + +# Setting multiple CAA records {% #multiple %} + +CAA records are additive. Each record authorizes one CA, and a CA is allowed to issue a certificate if any record at the domain matches it. To allow more than one CA, create one CAA record per CA at the same domain name. + +For example, to allow both Appwrite Cloud's CA and Let's Encrypt on the same domain, add two records. + +```text +example.com. IN CAA 0 issue "certainly.com" +example.com. IN CAA 0 issue "letsencrypt.org" +``` + +Most DNS dashboards model this as two separate CAA entries on the same host. Do not replace existing CAA records when adding the one Appwrite needs. Add the Appwrite record next to them so both your existing CAs and Appwrite's CA stay authorized. + +## Wildcard certificates {% #wildcard %} + +The `issue` tag controls non-wildcard certificate issuance. If a CA needs to issue a wildcard certificate (for example, `*.example.com`), it checks the `issuewild` tag instead. If no `issuewild` record exists, the CA falls back to the `issue` records. + +If you have set restrictive `issuewild` records for other CAs, add an `issuewild` record for Appwrite's CA as well. + +```text +example.com. IN CAA 0 issuewild "certainly.com" +``` + +## Reporting violations {% #iodef %} + +The `iodef` tag is optional and tells CAs where to report attempts at unauthorized issuance. It is independent of `issue` and `issuewild` records and does not need to change to use Appwrite. + +```text +example.com. IN CAA 0 iodef "mailto:security@example.com" +``` + +# Troubleshooting {% #troubleshooting %} + +If a custom domain stays unverified or its certificate fails to issue, check the following. + +- Confirm the CAA record uses the exact value shown in the Appwrite Console, with no trailing spaces, quotes, or `https://` prefix. +- Confirm the CAA record sits at the right level. For an apex domain, it belongs at the apex. For a subdomain, CAA records at the apex are inherited unless the subdomain itself has CAA records, in which case only the subdomain's records apply. +- Wait for DNS propagation. CAA changes can take up to 48 hours to be visible to the CA. +- Check the current state of your CAA records with [DNS Checker](https://dnschecker.org/) or `dig CAA example.com`. + +If issues persist, [contact us](/contact-us) and we will help debug your DNS setup. From 7289d2b2e6b1e4dffc6ca7b00a0e94b64b4e0c3d Mon Sep 17 00:00:00 2001 From: Aditya Oberai Date: Thu, 21 May 2026 01:14:45 +0530 Subject: [PATCH 2/5] Update src/routes/docs/products/network/caa-records/+page.markdoc Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- src/routes/docs/products/network/caa-records/+page.markdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routes/docs/products/network/caa-records/+page.markdoc b/src/routes/docs/products/network/caa-records/+page.markdoc index 7edb8025fe0..b67f15ff3e2 100644 --- a/src/routes/docs/products/network/caa-records/+page.markdoc +++ b/src/routes/docs/products/network/caa-records/+page.markdoc @@ -1,6 +1,6 @@ --- layout: article -title: CAA records +title: Certification Authority Authorization (CAA) records description: Learn what DNS Certification Authority Authorization (CAA) records are, when they are required to use a custom domain with Appwrite, and how to configure one or more of them at your DNS provider. --- From 4c83805dc40265d55d940d88e1a26ee9b03b18c1 Mon Sep 17 00:00:00 2001 From: adityaoberai Date: Thu, 21 May 2026 01:18:14 +0530 Subject: [PATCH 3/5] cross link docs --- .../advanced/platform/custom-domains/+page.markdoc | 5 +++-- src/routes/docs/advanced/security/tls/+page.markdoc | 6 ++++++ src/routes/docs/products/network/dns/+page.markdoc | 10 +++++++--- src/routes/docs/products/sites/domains/+page.markdoc | 4 ++-- 4 files changed, 18 insertions(+), 7 deletions(-) diff --git a/src/routes/docs/advanced/platform/custom-domains/+page.markdoc b/src/routes/docs/advanced/platform/custom-domains/+page.markdoc index a0bd9bb7432..980a5438b22 100644 --- a/src/routes/docs/advanced/platform/custom-domains/+page.markdoc +++ b/src/routes/docs/advanced/platform/custom-domains/+page.markdoc @@ -32,8 +32,9 @@ This will allow browsers to respect the Appwrite sessions cookies as they are se 2. Click on the **Settings** tab in the left sidebar. 3. Select the **Custom domains** section and click **Create domain**. 4. Add your domain, and copy associated CNAME record to your DNS provider. See the [Add a CNAME record](#cname-record) section. -5. Verify your domain. DNS changes might take up to 48 hours to propagate worldwide, you may not be able to do this in the same day. -6. Once you verify your domain, you can generate an SSL certificate. +5. If the Console also shows a [CAA record](/docs/products/network/caa-records), add it to your DNS provider so Appwrite's certificate authority is authorized to issue a certificate for your domain. Existing CAA records should be kept in place. See [Setting multiple CAA records](/docs/products/network/caa-records#multiple). +6. Verify your domain. DNS changes might take up to 48 hours to propagate worldwide, you may not be able to do this in the same day. +7. Once you verify your domain, you can generate an SSL certificate. With these steps, your Appwrite project will accept API requests from your custom domain. diff --git a/src/routes/docs/advanced/security/tls/+page.markdoc b/src/routes/docs/advanced/security/tls/+page.markdoc index 7c7f0a076e1..cadd64140da 100644 --- a/src/routes/docs/advanced/security/tls/+page.markdoc +++ b/src/routes/docs/advanced/security/tls/+page.markdoc @@ -17,3 +17,9 @@ TLS certificates are generated for all of the following. TLS certificates are crucial to ensure all connections between your apps and Appwrite Cloud are encrypted. This protects your users from attack vectors like man-in-the-middle and eavesdropping attacks. + +# CAA records {% #caa-records %} + +If your domain has restrictive [CAA records](/docs/products/network/caa-records) in DNS, you must authorize the certificate authority Appwrite uses before a certificate can be issued. On Appwrite Cloud, add `certainly.com` to your CAA policy. On self-hosted deployments, add `letsencrypt.org`. Domains without any CAA records do not require this step. + +[Learn more about CAA records >](/docs/products/network/caa-records) diff --git a/src/routes/docs/products/network/dns/+page.markdoc b/src/routes/docs/products/network/dns/+page.markdoc index 2a2c59b4e62..724bf248b3d 100644 --- a/src/routes/docs/products/network/dns/+page.markdoc +++ b/src/routes/docs/products/network/dns/+page.markdoc @@ -50,7 +50,7 @@ Appwrite DNS supports various DNS record types to meet your domain configuration | TXT | Stores text information (often used for verification) | | NS | Specifies the nameservers for the domain | | SRV | Specifies services available for a domain (used for Voice over IP, instant messaging, etc.) | -| CAA | Specifies which certificate authorities (CAs) are authorized to issue certificates for a domain | +| [CAA](/docs/products/network/caa-records) | Specifies which certificate authorities (CAs) are authorized to issue certificates for a domain | | HTTPS | Provides configuration for HTTPS connections | | ALIAS | Similar to CNAME but can be used at the zone apex | @@ -80,15 +80,19 @@ Depending on your DNS provider, this feature may be provided through **CNAME rec To use this method: -1. In the Appwrite Console, add your apex domain and copy the provided CNAME and CAA records +1. In the Appwrite Console, add your apex domain and copy the provided CNAME and [CAA](/docs/products/network/caa-records) records 2. In your DNS provider's settings, create an ALIAS, ANAME, or CNAME record at the apex (depending on what your provider supports) 3. Point the record to the Appwrite hostname provided in the console -4. Add the CAA record at the apex level in your DNS provider's settings +4. Add the [CAA record](/docs/products/network/caa-records) at the apex level in your DNS provider's settings, alongside any CAA records you already have 5. Wait for DNS propagation (may take up to 48 hours) 6. Return to Appwrite Console to verify the domain This method allows you to maintain control over your remaining DNS configuration while still using your apex domain with Appwrite. +{% info title="Existing CAA records?" %} +If your apex already has CAA records for other certificate authorities, do not replace them. CAA records are additive. Add Appwrite's record next to your existing ones to keep every authorized CA. See [Setting multiple CAA records](/docs/products/network/caa-records#multiple). +{% /info %} + # Adding records in Appwrite {% #adding-records %} If you delegated your domain to Appwrite's DNS servers using NS records, you can add and manage records: diff --git a/src/routes/docs/products/sites/domains/+page.markdoc b/src/routes/docs/products/sites/domains/+page.markdoc index ec0e9cb40d7..e5a43778ea3 100644 --- a/src/routes/docs/products/sites/domains/+page.markdoc +++ b/src/routes/docs/products/sites/domains/+page.markdoc @@ -89,10 +89,10 @@ To add an apex domain without changing your NS records via [CNAME flattening](/d 3. Enter your apex domain (e.g., `example.com`). 4. Select the appropriate domain rule type (Active deployment, Git branch, or Redirect) and configure its settings. See the [Domain rule types](#domain-rule-types) section for details. 5. Copy the **CNAME** record provided by Appwrite. -6. Copy the **CAA** record provided by Appwrite. +6. Copy the **[CAA](/docs/products/network/caa-records)** record provided by Appwrite. 7. In your DNS provider's settings, create an ALIAS, ANAME, or CNAME record at the apex (depending on what your provider supports). 8. Point the record to the Appwrite hostname provided in the console. -9. Add the CAA record to your DNS provider's settings, also pointed at the apex. +9. Add the [CAA record](/docs/products/network/caa-records) to your DNS provider's settings, also pointed at the apex. If you already have CAA records on your domain, keep them and add Appwrite's alongside them. See [Setting multiple CAA records](/docs/products/network/caa-records#multiple). 10. Return to the Site settings and wait for verification status. {% only_dark %} From 92634cf8542af68e31856a7c0883652dafa7bf6b Mon Sep 17 00:00:00 2001 From: adityaoberai Date: Thu, 21 May 2026 01:36:37 +0530 Subject: [PATCH 4/5] apply fixes --- .../network/caa-records/+page.markdoc | 36 +++++++++---------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/src/routes/docs/products/network/caa-records/+page.markdoc b/src/routes/docs/products/network/caa-records/+page.markdoc index b67f15ff3e2..d59532fa143 100644 --- a/src/routes/docs/products/network/caa-records/+page.markdoc +++ b/src/routes/docs/products/network/caa-records/+page.markdoc @@ -6,38 +6,32 @@ description: Learn what DNS Certification Authority Authorization (CAA) records A Certification Authority Authorization (CAA) record is a DNS record that specifies which certificate authorities (CAs) are allowed to issue TLS certificates for your domain. CAA records help prevent unauthorized certificate issuance and are defined in [RFC 8659](https://datatracker.ietf.org/doc/html/rfc8659). -When Appwrite issues a TLS certificate for a [custom domain](/docs/advanced/platform/custom-domains), an [Appwrite Sites domain](/docs/products/sites/domains), or a [Function domain](/docs/products/functions/domains), the certificate authority used by Appwrite checks your domain's CAA records before issuing. If your CAA records do not authorize the CA that Appwrite uses, issuance fails and your domain stays unverified. +When Appwrite issues a TLS certificate for a [custom domain](/docs/advanced/platform/custom-domains), an [Appwrite Sites domain](/docs/products/sites/domains), or a [Function domain](/docs/products/functions/domains), the certificate authority used by Appwrite checks your domain's CAA records before issuing. If your domain has no CAA records at all, any CA, including Appwrite's, is allowed to issue and no action is needed from you. If your domain already has CAA records and none of them authorize the CA that Appwrite uses, issuance fails and your domain stays unverified until you add the required record. {% info title="CAA records are additive, not exclusive" %} Adding a CAA record for Appwrite does **not** replace your existing CAA records, override certificates issued by other CAs, or invalidate certificates already in use elsewhere. CAA only controls **future** certificate issuance. You can safely keep every CAA record you already have and add Appwrite's alongside them. See [Setting multiple CAA records](#multiple). {% /info %} -# Certificate authorities used by Appwrite {% #certificate-authorities %} +# Certificate authority used by Appwrite {% #certificate-authority %} -The CA that needs authorization depends on your deployment. - -| Deployment | Certificate authority | CAA value | -| ---------- | --------------------- | --------- | -| Appwrite Cloud (Sites, Functions, custom domains) | [Certainly](https://docs.fastly.com/products/certainly) (operated by Fastly) | `certainly.com` | -| Self-hosted | [Let's Encrypt](https://letsencrypt.org/) | `letsencrypt.org` | +Appwrite Cloud uses [Certainly](https://docs.fastly.com/products/certainly), Fastly's certificate authority, to issue TLS certificates for Sites, Functions, and custom API domains. If you need to authorize Appwrite's CA in a CAA record, use the value `certainly.com`. For more on how Appwrite manages certificates, see the [TLS documentation](/docs/advanced/security/tls). -# When CAA records are optional {% #optional %} - -CAA records are not mandatory in DNS. If your domain has no CAA records at all, any publicly trusted CA, including the one Appwrite uses, is permitted to issue a certificate for it. In this case, you do not need to add a CAA record to use a custom domain with Appwrite. +# Do you need a CAA record? {% #do-you-need-one %} -This is the common case for most domains that have never been configured with a CAA policy. +By default, no. CAA records are not mandatory in DNS, and if your domain has no CAA records at all, any publicly trusted CA, including the one Appwrite uses, is permitted to issue a certificate for it. This is the common case for most domains, and no action is needed from you. -# When CAA records are required {% #required %} +You **do** need to add a CAA record that authorizes Appwrite's CA in either of these situations. -You must add a CAA record that authorizes Appwrite's CA in any of these situations. - -- Your domain already has one or more CAA records that do not include `certainly.com` (Appwrite Cloud) or `letsencrypt.org` (self-hosted). Existing CAA records form an allow-list, and any CA not on it is blocked. +- Your domain already has one or more CAA records that do not include `certainly.com`. Existing CAA records form an allow-list, and any CA not on it is blocked. - Your DNS provider, registrar, or organization adds CAA records automatically for new domains. -- The Appwrite Console shows a CAA record alongside the CNAME or NS record when adding a domain. The Console only shows CAA records when one is needed for your domain to be verified. -If you are unsure, you can inspect existing CAA records for your domain with a public tool like [DNS Checker](https://dnschecker.org/) or by running `dig CAA example.com` from a terminal. +If you are unsure, inspect your existing CAA records with a tool like [DNS Checker](https://dnschecker.org/) or by running `dig CAA example.com` from a terminal. + +{% info title="What the Appwrite Console shows" %} +When you add a custom domain, the Appwrite Console may surface a CAA value alongside the CNAME or NS record as part of the standard setup. Adding it is only strictly necessary when one of the conditions above applies. If neither applies, you can safely skip the CAA step. +{% /info %} ## Apex domains and subdomains {% #scope %} @@ -60,7 +54,7 @@ The exact UI differs between DNS providers, but the values are the same. 3. Set the **name** (or **host**) to the domain you are configuring, for example `example.com` for an apex domain or `app.example.com` for a subdomain. 4. Set the **flags** to `0`. 5. Set the **tag** to `issue`. -6. Set the **value** to the CA shown in the Appwrite Console, for example `certainly.com` on Appwrite Cloud. +6. Set the **value** to the CA shown in the Appwrite Console (`certainly.com` for Appwrite Cloud). 7. Save the record and wait for DNS propagation. This can take up to 48 hours. A complete CAA record in zone file format looks like this. @@ -82,6 +76,10 @@ example.com. IN CAA 0 issue "letsencrypt.org" Most DNS dashboards model this as two separate CAA entries on the same host. Do not replace existing CAA records when adding the one Appwrite needs. Add the Appwrite record next to them so both your existing CAs and Appwrite's CA stay authorized. +{% info title="Using Appwrite DNS as your nameserver?" %} +If you have delegated your domain to [Appwrite DNS](/docs/products/network/dns) by pointing your nameservers to `ns1.appwrite.zone` and `ns2.appwrite.zone`, Appwrite automatically applies the CAA record needed for its certificate authority. You do not need to add a CAA record manually in this case. You can still add additional CAA records for other CAs from the **Domains** tab in your organization if you want to authorize them alongside Appwrite's CA. +{% /info %} + ## Wildcard certificates {% #wildcard %} The `issue` tag controls non-wildcard certificate issuance. If a CA needs to issue a wildcard certificate (for example, `*.example.com`), it checks the `issuewild` tag instead. If no `issuewild` record exists, the CA falls back to the `issue` records. From d38301d3c94a99838dcfdffe0dcbebc462b4ad1c Mon Sep 17 00:00:00 2001 From: Aditya Oberai Date: Thu, 21 May 2026 01:40:59 +0530 Subject: [PATCH 5/5] Apply suggestion from @adityaoberai --- src/routes/docs/advanced/security/tls/+page.markdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/routes/docs/advanced/security/tls/+page.markdoc b/src/routes/docs/advanced/security/tls/+page.markdoc index cadd64140da..b0c21bdee10 100644 --- a/src/routes/docs/advanced/security/tls/+page.markdoc +++ b/src/routes/docs/advanced/security/tls/+page.markdoc @@ -20,6 +20,6 @@ This protects your users from attack vectors like man-in-the-middle and eavesdro # CAA records {% #caa-records %} -If your domain has restrictive [CAA records](/docs/products/network/caa-records) in DNS, you must authorize the certificate authority Appwrite uses before a certificate can be issued. On Appwrite Cloud, add `certainly.com` to your CAA policy. On self-hosted deployments, add `letsencrypt.org`. Domains without any CAA records do not require this step. +If your domain has restrictive [CAA records](/docs/products/network/caa-records) in DNS, you must authorize the certificate authority Appwrite uses before a certificate can be issued. On Appwrite Cloud, add `certainly.com` to your CAA policy. Domains without any CAA records do not require this step. [Learn more about CAA records >](/docs/products/network/caa-records)