Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThis pull request adds a new blog post at Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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 Tip You can validate your CodeRabbit configuration file in your editor.If your editor has YAML language server, you can enable auto-completion and validation by adding |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/routes/blog/post/cname-flattening-for-appwrite-sites/`+page.markdoc:
- Line 111: Update the sentence "Once the DNS propagates, your site will be
available on your custom domain with SSL automatically configured." to include a
short caveat about CAA records: note that domains with restrictive CAA records
must authorize Appwrite Sites' CA (Certainly / certainly.com) before TLS can be
issued, and add a link to the docs for CAA configuration; mention the
recommended CAA value (0 issue "certainly.com") for CNAME-flattened Sites to
ensure certificate issuance succeeds.
- Around line 66-68: Update the paragraph about CNAME/CNAME-flattening to
correct DNS semantics: state that apex (flattening) implementations synthesize
A/AAAA records rather than creating an RFC‑compliant CNAME, clarify that the
restriction is that a name with a CNAME RRset cannot have other data at that
same owner name (not that multiple RRsets cannot share an owner name), and
change the final sentence to distinguish CNAME chains (a sequence of CNAMEs)
from cycles/loops and warn to avoid cycles; replace the existing sentences
referencing "CNAME flattening" and "CNAME looping" accordingly.
- Line 92: Update the TTL guidance paragraph so it is less absolute: state that
provider defaults vary and that lowering TTL does not speed DNS resolution but
reduces cache lifetime, increasing query load; recommend using a short TTL
(e.g., 5 minutes) only temporarily for debugging or during planned changes, then
restore a more typical value afterward, and call out the trade-offs (more
queries vs. faster propagation of updates) in place of the current definitive
wording about resolution time.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c49c99dd-84fa-40c0-b187-f28db78dfcf6
⛔ Files ignored due to path filters (1)
static/images/blog/cname-flattening-for-appwrite-sites/cover.pngis excluded by!**/*.png
📒 Files selected for processing (2)
.optimize-cache.jsonsrc/routes/blog/post/cname-flattening-for-appwrite-sites/+page.markdoc
src/routes/blog/post/cname-flattening-for-appwrite-sites/+page.markdoc
Outdated
Show resolved
Hide resolved
| 3. Verify the domain in Appwrite. | ||
| 4. Go live. | ||
|
|
||
| When creating the DNS record, note that the default TTL (Time To Live) is often set to 24 hours unless overridden. It is recommended to set the TTL to 5 minutes for quick propagation. A lower TTL allows DNS changes to propagate faster across DNS servers, which improves resolution time and ensures updates take effect more quickly. DNS servers and resolvers use cache to temporarily store DNS answers, which can affect how quickly changes to CNAME records take effect. |
There was a problem hiding this comment.
The TTL guidance is too absolute and partly inaccurate.
Provider defaults vary, and a lower TTL does not improve resolution time—it only shortens how long stale answers may stay cached, usually at the cost of more DNS queries. Framing 5 minutes as a temporary setup/debugging value would be safer.
Suggested rewording
-When creating the DNS record, note that the default TTL (Time To Live) is often set to 24 hours unless overridden. It is recommended to set the TTL to 5 minutes for quick propagation. A lower TTL allows DNS changes to propagate faster across DNS servers, which improves resolution time and ensures updates take effect more quickly. DNS servers and resolvers use cache to temporarily store DNS answers, which can affect how quickly changes to CNAME records take effect.
+When creating the DNS record, use your provider's default TTL unless you expect to change the record again soon. During initial setup or troubleshooting, a shorter TTL such as 5 minutes can reduce how long older DNS answers remain cached. DNS servers and resolvers cache answers, so TTL directly affects how quickly record changes are observed.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| When creating the DNS record, note that the default TTL (Time To Live) is often set to 24 hours unless overridden. It is recommended to set the TTL to 5 minutes for quick propagation. A lower TTL allows DNS changes to propagate faster across DNS servers, which improves resolution time and ensures updates take effect more quickly. DNS servers and resolvers use cache to temporarily store DNS answers, which can affect how quickly changes to CNAME records take effect. | |
| When creating the DNS record, use your provider's default TTL unless you expect to change the record again soon. During initial setup or troubleshooting, a shorter TTL such as 5 minutes can reduce how long older DNS answers remain cached. DNS servers and resolvers cache answers, so TTL directly affects how quickly record changes are observed. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/routes/blog/post/cname-flattening-for-appwrite-sites/`+page.markdoc at
line 92, Update the TTL guidance paragraph so it is less absolute: state that
provider defaults vary and that lowering TTL does not speed DNS resolution but
reduces cache lifetime, increasing query load; recommend using a short TTL
(e.g., 5 minutes) only temporarily for debugging or during planned changes, then
restore a more typical value afterward, and call out the trade-offs (more
queries vs. faster propagation of updates) in place of the current definitive
wording about resolution time.
| 5. Create the required DNS record directly, using the correct record type (CNAME or ANAME). | ||
| 6. Return to Appwrite and verify the domain. | ||
|
|
||
| Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured. |
There was a problem hiding this comment.
Add the CAA caveat before promising automatic SSL.
This is true for most setups, but domains with restrictive CAA records still need to authorize Appwrite Sites' CA or certificate issuance can stall. A short note or docs link here would prevent a confusing failure mode for that subset of users.
Suggested change
-Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured.
+Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured. If your domain already uses restrictive CAA records, make sure they allow `certainly.com` so certificate issuance can complete.Based on learnings, 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.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured. | |
| Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured. If your domain already uses restrictive CAA records, make sure they allow `certainly.com` so certificate issuance can complete. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/routes/blog/post/cname-flattening-for-appwrite-sites/`+page.markdoc at
line 111, Update the sentence "Once the DNS propagates, your site will be
available on your custom domain with SSL automatically configured." to include a
short caveat about CAA records: note that domains with restrictive CAA records
must authorize Appwrite Sites' CA (Certainly / certainly.com) before TLS can be
issued, and add a link to the docs for CAA configuration; mention the
recommended CAA value (0 issue "certainly.com") for CNAME-flattened Sites to
ensure certificate issuance succeeds.
| - Email and other subdomain configurations | ||
| - Mail (handled by MX records, which direct email to the correct mail server) |
There was a problem hiding this comment.
The first email mention needs to be clarified is email forwarding, or it doesn't make sense
|
|
||
| # What is CNAME flattening? | ||
|
|
||
| CNAME flattening is a DNS feature that allows a domain's apex (root domain) to behave like a CNAME, even though standard DNS rules normally prohibit CNAME records at the root. Instead of returning the CNAME itself, the DNS provider resolves the target internally and returns the corresponding IP addresses (A/AAAA records) to the client. This process is called CNAME flattening and is especially useful for handling DNS at the zone apex, where traditional CNAME records are not allowed. |
There was a problem hiding this comment.
| CNAME flattening is a DNS feature that allows a domain's apex (root domain) to behave like a CNAME, even though standard DNS rules normally prohibit CNAME records at the root. Instead of returning the CNAME itself, the DNS provider resolves the target internally and returns the corresponding IP addresses (A/AAAA records) to the client. This process is called CNAME flattening and is especially useful for handling DNS at the zone apex, where traditional CNAME records are not allowed. | |
| CNAME flattening is a feature offered by certain DNS providers that allows a domain's apex (root domain) to behave like a CNAME, even though standard DNS rules normally prohibit CNAME records at the root. Instead of returning the CNAME itself, the DNS provider resolves the target internally and returns the corresponding IP addresses (A/AAAA records) to the client. |
Unnecessary
| Traditionally: | ||
|
|
||
| - **CNAME records** are used to point one domain to another; specifically, a CNAME record maps a hostname (such as a fully qualified domain name) to a canonical name (the true or canonical domain). For example, you might have a CNAME record for `foo.example.com` pointing to `bar.example.net`. | ||
| - But they're not allowed at the root domain (like `example.com`), as per DNS specification and RFC standards (see RFC 1034, RFC 2181). Using a CNAME record at the root is considered bad practice and is technically disallowed. | ||
| - Only subdomains (like `subdomain.example.com`) could use CNAME. | ||
|
|
||
| CNAME records must always point to another domain name, never directly to an IP address. A CNAME points DNS lookups to the target domain, and multiple domains or subdomains can resolve to the same IP address through CNAME records and server configuration. |
There was a problem hiding this comment.
This is excessive information, not sure how necessary it is after the initial paragraph
|
|
||
| Setting up a custom domain should be simple. Add a record, wait a bit, and your site is live. This process involves a DNS lookup, where the fully qualified domain name (FQDN) is resolved to an IP address. | ||
|
|
||
| But in practice, DNS can get complicated, especially when different tools expect you to manage nameservers in different places. DNS records are managed by DNS servers as part of the domain name system, which maps domain names to IP addresses and handles various record types like CNAME, A, and others. We've heard this feedback from many developers using Appwrite Sites, and we've made an improvement to make the process smoother. |
There was a problem hiding this comment.
| But in practice, DNS can get complicated, especially when different tools expect you to manage nameservers in different places. DNS records are managed by DNS servers as part of the domain name system, which maps domain names to IP addresses and handles various record types like CNAME, A, and others. We've heard this feedback from many developers using Appwrite Sites, and we've made an improvement to make the process smoother. | |
| But in practice, DNS can get complicated, especially when different tools expect you to manage nameservers in different places. We've heard this feedback from many developers using Appwrite Sites, and we've made an improvement to make the process smoother. |
There was a problem hiding this comment.
Also, this paragraph rushes context, doesn't set the tone
We should instead talk about why this was necessary for Appwrite in the first place
| unlisted: true | ||
| --- | ||
|
|
||
| Setting up a custom domain should be simple. Add a record, wait a bit, and your site is live. This process involves a DNS lookup, where the fully qualified domain name (FQDN) is resolved to an IP address. |
There was a problem hiding this comment.
| Setting up a custom domain should be simple. Add a record, wait a bit, and your site is live. This process involves a DNS lookup, where the fully qualified domain name (FQDN) is resolved to an IP address. | |
| Setting up a custom domain should be simple. Add a DNS record, wait a bit, and your site is live. |
The line I'm removing is too complex to be a part of the opening paragraph. The opening paragraph should set the tone for the blog, share the story of our problem.
We can shift the nitty gritties to a later section
src/routes/blog/post/cname-flattening-for-appwrite-sites/+page.markdoc
Outdated
Show resolved
Hide resolved
|
|
||
| CNAME records must always point to another domain name, never directly to an IP address. A CNAME points DNS lookups to the target domain, and multiple domains or subdomains can resolve to the same IP address through CNAME records and server configuration. | ||
|
|
||
| # So what does CNAME flattening do? |
There was a problem hiding this comment.
Why can't we explain this entire section simply in the previous one?
|
|
||
| Read the [full CNAME flattening announcement](https://appwrite.io/blog/post/announcing-cname-flattening) for more details. | ||
|
|
||
| # How to connect your domain now |
There was a problem hiding this comment.
| # How to connect your domain now | |
| # How to connect your domain with CNAME flattening |
| 2. Add your custom domain. | ||
| 3. Appwrite will provide a DNS target, which is typically a fully qualified domain name (FQDN) or hostname. | ||
| 4. Go to your DNS provider (Cloudflare, Namecheap, etc.). | ||
| 5. Create the required DNS record directly, using the correct record type (CNAME or ANAME). |
There was a problem hiding this comment.
| 5. Create the required DNS record directly, using the correct record type (CNAME or ANAME). | |
| 5. Create the required CNAME, ANAME, or ALIAS record. |
src/routes/blog/post/cname-flattening-for-appwrite-sites/+page.markdoc
Outdated
Show resolved
Hide resolved
| You've built something worth shipping. The code works. The app is live. All that's left is pointing `yourdomain.com` to it, and then DNS reminds you who's really in charge. | ||
|
|
||
| You can't put a CNAME on your root domain. Not without consequences. So you settle for `www`, bolt on a redirect, and ship anyway. It works. But it's never felt right. |
There was a problem hiding this comment.
This context disregards what we allowed with nameservers (NS records)
|
|
||
| Previously, when using Appwrite Sites, pointing an apex domain to your site required changing your nameservers to Appwrite. This was a substantial change, especially if your domain already had other DNS records configured, since migrating records like email configuration (MX records) could add unnecessary hassle and risk. | ||
|
|
||
| **That changes today.** Appwrite Sites now supports CNAME flattening, which means `yourdomain.com` can point directly to your Appwrite project. No subdomain. No redirect. No compromise. |
There was a problem hiding this comment.
Not today, this has already been released
|
|
||
| You've built something worth shipping. The code works. The app is live. All that's left is pointing `yourdomain.com` to it, and then DNS reminds you who's really in charge. | ||
|
|
||
| Previously, when using Appwrite Sites, pointing an apex domain to your site required changing your nameservers to Appwrite. This was a substantial change, especially if your domain already had other DNS records configured, since migrating records like email configuration (MX records) could add unnecessary hassle and risk. |
There was a problem hiding this comment.
Let's add a few points on the inconveniences of migrating nameservers
|
|
||
| A CNAME at the root conflicts with all of them. Put one there and you risk silently breaking your email setup, landing in spam folders, or failing domain verification entirely. | ||
|
|
||
| The old workarounds? Use `www`. Set a static A record and hope the IP never changes. Redirect from root to subdomain and explain it away in a support ticket. None of them are real solutions. |
There was a problem hiding this comment.
This did not work in Appwrite Sites anyway
|
|
||
| # What CNAME flattening actually does | ||
|
|
||
| CNAME flattening is a clean fix to a decades-old problem. |
There was a problem hiding this comment.
Let's keep it a little more formal and jump directly into the problem it solves
|
|
||
| Instead of storing a CNAME record at the root, your DNS resolver **follows the CNAME chain at query time** and returns only the final A or AAAA IP address, as if you'd hardcoded the IP directly. | ||
|
|
||
| No alias chain exposed to the client. No RFC violation. No conflict with your other apex records. |
There was a problem hiding this comment.
This doesn't make sense without more context on the RFC
src/routes/blog/post/cname-flattening-for-appwrite-sites/+page.markdoc
Outdated
Show resolved
Hide resolved
|
|
||
| Full setup details are available in the [Appwrite custom domains documentation.](https://appwrite.io/docs/advanced/platform/custom-domains) | ||
|
|
||
| # Which DNS providers support this? |
There was a problem hiding this comment.
Let's shift this section before # Setting this up
Co-authored-by: Aditya Oberai <adityaoberai1@gmail.com>
| | Situation | Without CNAME Flattening | With CNAME Flattening | | ||
| |---|---|---| | ||
| | Domain URL | Must use `www.yourdomain.com` | Use `yourdomain.com` directly | | ||
| | Performance | Redirect chain adds latency | Direct resolution, no redirect | | ||
| | DNS Records | Risk of breaking MX / TXT records | All DNS records coexist cleanly | | ||
| | Maintenance | Update A records if IP changes | Resolves dynamically, always current | | ||
| | Configuration | Manual workarounds required | Automatic | |
There was a problem hiding this comment.
@atharvadeosthale not sure if this is relevant, now that the intro has changed
3 participants
a new blog about cname flattening for Appwrite sites for SEO purpose
Summary by CodeRabbit
Documentation
Chores