Add cname flattening docs #2745
Conversation
WalkthroughAdds four image assets to the optimize cache (light and dark variants for add-domain-cname and add-domain-ns) and updates the apex domain documentation page. The doc edits clarify NS-based instructions, add NS-specific UI guidance and a propagation note, and introduce a new section describing CNAME flattening (steps, record types, and CAA guidance) as an alternative for adding an apex domain. The narrative is reorganized to separate the NS-record and CNAME-flattening approaches. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts (beta)
No actionable comments were generated in the recent review. 🎉 🧹 Recent nitpick comments
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@src/routes/docs/products/sites/domains/`+page.markdoc:
- 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.
🧹 Nitpick comments (1)
src/routes/docs/products/sites/domains/+page.markdoc (1)
91-100: Steps 5 and 8 overlap; consider consolidating.Step 5 says to copy the CNAME record (
appwrite.network), and step 8 says to "point the record to the Appwrite hostname provided in the console." These describe the same target value but are split across two steps, which may confuse readers. Consider merging them so step 7 reads something like: "Create an ALIAS/ANAME/CNAME record at the apex pointed toappwrite.network" and remove step 8.
| 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"`). |
There was a problem hiding this comment.
🧩 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:
- 1: https://www.fastly.com/blog/announcing-certainly-fastlys-own-tls-certification-authority?utm_source=openai
- 2: https://groups.google.com/a/mozilla.org/g/dev-security-policy/c/EhXhiHfWGC8/m/3PcJHizqAAAJ?utm_source=openai
- 3: https://groups.google.com/a/mozilla.org/g/dev-security-policy/c/EhXhiHfWGC8/m/3PcJHizqAAAJ?utm_source=openai
- 4: https://groups.google.com/a/mozilla.org/g/dev-security-policy/c/EhXhiHfWGC8/m/3PcJHizqAAAJ?utm_source=openai
- 5: https://www.fastly.com/blog/announcing-certainly-fastlys-own-tls-certification-authority?utm_source=openai
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.
There was a problem hiding this comment.
Certainly here is correct.
But worth checking rest of docs (for cloud), to make sure we dont have mistake elsewhere.
There was a problem hiding this comment.
🧩 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.
| 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"`). |
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
We also need to do this in the TLS Certificates section of the docs
I'll do that today
3 participants
What does this PR do?
Adds docs to explain how to add apex domains with CNAME flattening
Test Plan
Visit
/docs/products/sites/domainsRelated PRs and Issues
No
Have you read the Contributing Guidelines on issues?
Yes
Summary by CodeRabbit