Skip to content

Add cname flattening docs #2745

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adityaoberai wants to merge 2 commits into
base: main
Choose a base branch
from
+40 −3
Open

Add cname flattening docs #2745

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8977f01
Add cname flattening docs
adityaoberai Feb 11, 2026
cf6685f
Update src/routes/docs/products/sites/domains/+page.markdoc
adityaoberai Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .optimize-cache.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1291,6 +1291,8 @@
"images/docs/quick-starts/dark/project-id.png": "9e2af09237c50630355cb74a3ffb923438df18fd1e2ff56efa4bbf2fc15d3442",
"images/docs/quick-starts/integrate-server.png": "203b96264e104f06500e645c556b1cdebd1c7abcc29beda898fa631baadc43d7",
"images/docs/quick-starts/project-id.png": "500863e0f77e32b5a0c593e2c55b23bd114338948176f866b89f8af10ceaf7ba",
"images/docs/sites/add-domain-cname.png": "396a3b24fa4df6954d8ba7991291ee7227a5b049007f1330342d9551a6721692",
"images/docs/sites/add-domain-ns.png": "77564b8f3a4a30221e3003e7294f5bfac2c2d531db5a229134d461a13ef6a7b6",
"images/docs/sites/add-domain.png": "23f52d29a1a510ec404b97f999cdf146d7d1a3eebdfa859d633c41d76b11321f",
"images/docs/sites/branch-commit-urls.png": "ede353ba437785726cbce1a3850f6ed67fe950bfb96798c6c0181f5b2f81d950",
"images/docs/sites/build-settings-install-command.png": "6a132e2b6af4faf82ec1833524ceee7b66d63ae14a57038f5a20b0eb10e97cfa",
Expand All @@ -1300,6 +1302,8 @@
"images/docs/sites/create-deployment.png": "0ef48ff80a34db4c4fd129142b2ebf27d6b558c1137f45b8e8380f6dede597ef",
"images/docs/sites/create-first-site.png": "39d14e09887877fc0015b894cf5d6649dab0e05dd9afc74ab43c4d4d53679c45",
"images/docs/sites/create-site-wizard.png": "6874dd7e6e1018ed5e277092b9bfabaa54cd76805e26ffee8ac0c23cc00386b8",
"images/docs/sites/dark/add-domain-cname.png": "e68464d428c90d3e329bd229109add8fc7462fdf6220b949eeea3d2e91169960",
"images/docs/sites/dark/add-domain-ns.png": "c23a3500adeefe2f940b26582a3c44f2c567b27795e7aa6ea85af8ca49cfdbc4",
"images/docs/sites/dark/add-domain.png": "39dcdc16a06e1755d87c70329618ae97dd40052723006485d7d05bf263cbee95",
"images/docs/sites/dark/branch-commit-urls.png": "ececfd4f560295a83beb304c5740244deffcbd6a66d2861182af2e4da98bbc0d",
"images/docs/sites/dark/build-settings-install-command.png": "aeab3da28cc1133b5ba30d70f7b5ef5b324f7007d8a190ba04bceac2b6622193",
Expand Down
39 changes: 36 additions & 3 deletions src/routes/docs/products/sites/domains/+page.markdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ You can add your own domain to your Appwrite site to provide a branded experienc

Apex domains (also known as root domains) are domains without a subdomain prefix, like `example.com` instead of `www.example.com`. Unlike subdomains, apex domains cannot use CNAME records due to DNS protocol limitations.

To add an apex domain:
To add an apex domain via NS records:

1. Navigate to your site in the Appwrite Console.
2. Head to the **Domains** tab and click on **Add domain**.
Expand All @@ -56,14 +56,19 @@ To add an apex domain:
6. Go to your domain registrar and update the NS records for your domain to point to `ns1.appwrite.zone` and `ns2.appwrite.zone`.
7. Return to the Appwrite Console and wait for the verification process to complete.

{% only_dark %}
![Add domain](/images/docs/sites/dark/add-domain-ns.png)
{% /only_dark %}
{% only_light %}
![Add domain](/images/docs/sites/add-domain-ns.png)
{% /only_light %}

DNS changes can take up to 48 hours to fully propagate across the internet. During this time, your domain might not be accessible or might show inconsistent behavior.

### Why Appwrite uses NS records instead of A records

By [DNS standards (RFC)](https://datatracker.ietf.org/doc/html/rfc1035), apex domains cannot use CNAME records, only A or AAAA records, which require pointing to fixed IP addresses. Using A records would lock Appwrite into specific IP addresses, limiting our ability to optimize routing, scale our infrastructure, or make changes as needed. To avoid this constraint and maintain flexibility, Appwrite offers DNS delegation through NS records so we can manage routing on your behalf.

Some DNS providers support CNAME-like behavior at the apex through custom setups. If your provider allows it, you can point your apex domain to `appwrite.network` without using Appwrite's nameservers.

Using Appwrite's DNS servers for your apex domain provides several benefits:
- Proper SSL certificate management
- Automatic DNS configuration
Expand All @@ -75,6 +80,34 @@ When you change your domain's NS records, you're delegating DNS management to Ap
Learn more about Appwrite DNS server
{% /arrow_link %}

## Add an apex domain without changing nameservers

Some DNS providers support CNAME-like behavior at the apex level through a feature called CNAME flattening. This allows you to use a CNAME record for your apex domain without needing to delegate nameservers to Appwrite.

Depending on your DNS provider, this feature may be provided through **CNAME records**, **ALIAS records**, or **ANAME records**. Check your provider's documentation for the specific DNS record they support.

To add an apex domain via CNAME flattening:

1. Navigate to your site in the Appwrite Console.
2. Head to the **Domains** tab and click on **Add domain**.
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 (`appwrite.network`).
6. Copy the **CAA** record provided by Appwrite (`0 issue "certainly.com"`).
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 11, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🌐 Web query:

certainly.com certificate authority CAA record

💡 Result:

To allow Certainly (Fastly’s CA) to issue TLS certificates for your domain, add a DNS CAA record that authorizes the CA identifier:

  • CAA value for Certainly: certainly.com (this is the recognized CAA identifier for Certainly LLC) [1][2]

Example records:

; Allow Certainly to issue certificates for the domain
example.com.  CAA 0 issue "certainly.com"

; (Optional) Allow Certainly to issue wildcard certificates
example.com.  CAA 0 issuewild "certainly.com"

Sources: Fastly’s TLS documentation lists certainly.com as the required CAA value for Certainly [2], and the CCADB “All CAA Identifiers” report lists certainly.com for Certainly LLC [1].

🌐 Web query:

Appwrite custom domain TLS certificate authority

💡 Result:

Appwrite’s TLS certificates for custom domains are automatically issued by Let’s Encrypt (the non-profit CA operated by ISRG), using the ACME flow (notably the HTTP-01 challenge for self-hosted setups). [1], [2]

Sources: Appwrite TLS docs [1] and TLS certificates (self-hosting) docs [2].

🌐 Web query:

"certainly.com" CA certificate

💡 Result:

Certainly (at certainly.com) is Fastly’s publicly trusted TLS Certification Authority (CA). (fastly.com)

The CA’s root certificates referenced in Mozilla’s public root-inclusion discussion are: (groups.google.com)

  • Certainly Root R1 (websites trust bit) — crt.sh by SHA-256: 77B82CD8644C4305F7ACC5CB156B45675004033D51C60C6202A8E0C33467D3A0 (groups.google.com)
  • Certainly Root E1 (websites trust bit) — crt.sh by SHA-256: B4585F22E4AC756A4E8612A1361C5D9D031A93FD84FEBB778FA3068B0FC42DC2 (groups.google.com)

Fastly also notes Certainly’s intermediate CA certificates have been cross-signed by GoDaddy to improve client compatibility. (fastly.com)

Citations:

Update the CAA record value from certainly.com to letsencrypt.org.

Appwrite uses Let's Encrypt (ISRG) to issue TLS certificates for custom domains, not Certainly. The CAA record should reference Let's Encrypt as the authorized CA. The correct CAA record should be 0 issue "letsencrypt.org".

🤖 Prompt for AI Agents 
In `@src/routes/docs/products/sites/domains/`+page.markdoc at line 96, The CAA
record example currently shows the wrong CA; locate the line containing the CAA
example string '0 issue "certainly.com"' (the list item that starts "Copy the
**CAA** record") and change its value to Let's Encrypt by replacing '0 issue
"certainly.com"' with '0 issue "letsencrypt.org"'; ensure the surrounding markup
and emphasis (the "**CAA** record" list item) remain unchanged.

Copy link
Contributor

@Meldiron Meldiron Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Certainly here is correct.
But worth checking rest of docs (for cloud), to make sure we dont have mistake elsewhere.

Copy link
Contributor

@coderabbitai coderabbitai bot Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 Analysis chain

@Meldiron, acknowledged! I'll verify the consistency of certificate authority references across the cloud documentation.

🏁 Script executed:

#!/bin/bash
# Search for CAA record references in docs
echo "=== Searching for CAA records ==="
rg -i "CAA" --type=md src/routes/docs/ -C 2

echo -e "\n=== Searching for letsencrypt references ==="
rg -i "letsencrypt" --type=md src/routes/docs/ -C 2

echo -e "\n=== Searching for certainly.com references ==="
rg -i "certainly\.com" --type=md src/routes/docs/ -C 2

echo -e "\n=== Searching for certificate authority mentions ==="
rg -i "certificate authority|CA.*certificate|TLS certificate" --type=md src/routes/docs/products/sites/ -C 2

Length of output: 181

🏁 Script executed:

#!/bin/bash
# Search without type restriction to include .markdoc files
echo "=== Searching for CAA records in all docs files ==="
rg -i "CAA" src/routes/docs/ -C 2

echo -e "\n=== Searching for letsencrypt references ==="
rg -i "letsencrypt" src/routes/docs/ -C 2

echo -e "\n=== Searching for certainly.com references ==="
rg -i "certainly" src/routes/docs/ -C 2

echo -e "\n=== Searching for certificate/TLS related content in sites docs ==="
rg -i "certificate|TLS" src/routes/docs/products/sites/ -C 1

Length of output: 7177

🏁 Script executed:

#!/bin/bash
# Read the full TLS documentation to understand the context
echo "=== TLS documentation content ==="
cat src/routes/docs/advanced/security/tls/+page.markdoc

Length of output: 1138

@Meldiron, I found an inconsistency that needs clarification:

Current documentation states:

  • TLS docs (src/routes/docs/advanced/security/tls/+page.markdoc): "Appwrite uses Let's Encrypt to auto-generate TLS certificates" - applies to "all" Appwrite products, custom domains, and Function domains
  • Sites CNAME flattening (this PR): Requires CAA record for certainly.com

Recommendation:
The general TLS documentation page should be updated to clarify which services use which certificate authority. It currently states Let's Encrypt is used for "all" domains, but Sites (particularly with CNAME flattening via Fastly infrastructure) uses Certainly.

Suggested clarification for src/routes/docs/advanced/security/tls/+page.markdoc:

  • Mention that Sites uses Certainly (Fastly's CA) for TLS certificates
  • Or clarify that Let's Encrypt applies to API endpoints and self-hosted deployments, while Sites may use different CAs

Would you like me to help draft an update for the TLS documentation page to address this?

✏️ Learnings added 
Learnt from: Meldiron
Repo: appwrite/website PR: 2745
File: src/routes/docs/products/sites/domains/+page.markdoc:96-96
Timestamp: 2026-02-12T11:07:46.170Z
Learning: Appwrite Cloud Sites uses Certainly (Fastly's CA) for TLS certificates, not Let's Encrypt. The CAA record value `0 issue "certainly.com"` is correct for Sites with CNAME flattening.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

Copy link
Member Author

@adityaoberai adityaoberai Feb 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's Encrypt applies to self-hosted deployments and Certainly applies to Appwrite Cloud

Copy link
Contributor

@coderabbitai coderabbitai bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

Copy link
Member Author

@adityaoberai adityaoberai Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's Encrypt applies to self-hosted deployments and Certainly applies to Appwrite Cloud

@coderabbitai prompt for this?

Copy link
Contributor

@coderabbitai coderabbitai bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@adityaoberai, here's the prompt for updating the TLS documentation:

Prompt for AI Agents / Manual Update:

In `src/routes/docs/advanced/security/tls/+page.markdoc`, locate the sentence 
"Appwrite uses Let's Encrypt to auto-generate TLS certificates for all Appwrite 
products, custom domains, and Function domains." and update it to clarify the 
distinction between self-hosted and Cloud deployments.

Replace it with:
"Appwrite automatically generates TLS certificates for all Appwrite products, 
custom domains, and Function domains. Self-hosted deployments use Let's Encrypt, 
while Appwrite Cloud uses Certainly (Fastly's Certificate Authority)."

Ensure the surrounding markdown structure and any links remain unchanged.

This clarification will help users understand which CA to authorize in their CAA records depending on their deployment type.

✏️ Learnings added 
Learnt from: adityaoberai
Repo: appwrite/website PR: 2745
File: src/routes/docs/products/sites/domains/+page.markdoc:96-96
Timestamp: 2026-02-13T20:29:03.828Z
Learning: For Appwrite TLS certificates: self-hosted deployments use Let's Encrypt as the certificate authority, while Appwrite Cloud uses Certainly (Fastly's CA).

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

🧠 Learnings used 
Learnt from: Meldiron
Repo: appwrite/website PR: 2745
File: src/routes/docs/products/sites/domains/+page.markdoc:96-96
Timestamp: 2026-02-12T11:07:53.907Z
Learning: Appwrite Cloud Sites uses Certainly (Fastly's CA) for TLS certificates, not Let's Encrypt. The CAA record value `0 issue "certainly.com"` is correct for Sites with CNAME flattening.

Learnt from: amustaque97
Repo: appwrite/website PR: 2444
File: .github/workflows/production.yml:107-114
Timestamp: 2025-09-25T12:18:00.841Z
Learning: In the Appwrite website Kubernetes deployment, the team intentionally uses short-lived GITHUB_TOKEN for Docker pull secrets rather than long-lived registry credentials, as per amustaque97's explicit preference.

Copy link
Member

@atharvadeosthale atharvadeosthale Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@adityaoberai worth mentioning that it's certainly for Appwrite Cloud and could be letsencrypt for self-hosted? Worth consulting Matej for more info on this.

Copy link
Member Author

@adityaoberai adityaoberai Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We also need to do this in the TLS Certificates section of the docs

I'll do that today

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.
10. Return to the Site settings and wait for verification status.

{% only_dark %}
![Add domain](/images/docs/sites/dark/add-domain-cname.png)
{% /only_dark %}
{% only_light %}
![Add domain](/images/docs/sites/add-domain-cname.png)
{% /only_light %}

DNS changes can take up to 48 hours to propagate. Once verified, your apex domain will be ready to use with full control over your remaining DNS configuration.

## Add a subdomain with CNAME

Subdomains (like `www.example.com` or `app.example.com`) are set up using CNAME records, which point to Appwrite's hostname.
Expand Down
Binary file added static/images/docs/sites/add-domain-cname.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/docs/sites/add-domain-ns.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/docs/sites/dark/add-domain-cname.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/docs/sites/dark/add-domain-ns.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.