Skip to content

cname flattening #2799

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
aishwaripahwa12 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

cname flattening #2799

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 1 addition & 0 deletions .optimize-cache.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,6 +346,7 @@
"images/blog/client-vs-server-components-react/cover.png": "b7ae8b7614902c8b4dd7826d59cfdb36db9abbe27bde99b3deb69c4bf178f425",
"images/blog/cloud-beta.png": "7e44c7c7108d43bfcc77ba0c9910bfb14ba208bf559863d91610b29fc07da87c",
"images/blog/cloud-pricing.png": "2018d3cd01b12c289c3f66b780ff8518a13fc44da58efb19420fc67e367dc8cf",
"images/blog/cname-flattening-for-appwrite-sites/cover.png": "612a77f799df64b9407ba37f64ca4acf2f4772b5e883de00102b0b606b60e674",
"images/blog/community-pr.png": "112e1637eb62a95da227bb45bfe18a474cdd86b078877e21ae5ee57bfc959e29",
"images/blog/community-pr1.png": "22362832160073257e59cec48d4bea2bdd92139a6d1ee409c66a51cb1e2ccc47",
"images/blog/comparing-functions/1.png": "0c1add3fc0112aab08dc28188f8f997dcb20338e516db685284e6251145d5cb0",
Expand Down
126 changes: 126 additions & 0 deletions src/routes/blog/post/cname-flattening-for-appwrite-sites/+page.markdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
---
layout: post
title: CNAME flattening for Appwrite sites
description: Appwrite Sites now supports CNAME flattening, making it easier to connect custom domains without transferring DNS control or changing nameservers.
date: 2026-03-12
cover: /images/blog/cname-flattening-for-appwrite-sites/cover.png
timeToRead: 5
author: aishwari
category: tutorial
featured: false
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.
Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

Suggested change
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


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.
Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

Suggested change
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.

Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

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


Appwrite Sites now supports configurations that work with CNAME flattening and similar apex-domain features provided by modern DNS providers. This means you can connect your domain using standard DNS records, without transferring your nameservers to Appwrite.

# The previous setup

Until now, connecting a custom domain to an Appwrite Site required a nameserver change.

The process looked something like this:

1. Buy a domain from a provider like Namecheap or GoDaddy.
2. Open the domain's DNS settings.
3. Change the domain's **nameservers** to Appwrite.
4. Wait for DNS propagation.
5. Finish the domain setup inside Appwrite.

This worked, but it came with trade-offs.

Many developers manage their DNS through services like **Cloudflare**. They use it for:

- DNS management
- Caching and performance
- Security features
- Email and other subdomain configurations
- Mail (handled by MX records, which direct email to the correct mail server)
Comment on lines +39 to +40
Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

The first email mention needs to be clarified is email forwarding, or it doesn't make sense


Switching nameservers just to connect a single site meant handing over full DNS control. For some users, this felt unnecessary, especially on domains that were already in production.

When configuring subdomains, it's common to use the 'www' subdomain with a CNAME record pointing to the hosting environment, while the root domain (naked domain) cannot use a CNAME due to DNS restrictions.

# 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.
Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

Suggested change
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.
Comment on lines +50 to +56
Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

This is excessive information, not sure how necessary it is after the initial paragraph


# So what does CNAME flattening do?
Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

Why can't we explain this entire section simply in the previous one?


CNAME flattening solves this limitation. It allows DNS providers to:

- Accept a CNAME-like configuration at the root domain (zone apex).
- Resolve it internally.
- Return the correct IP addresses to the browser.

In addition, CNAME flattening allows you to create a CNAME record at the root of your domain without violating the RFC's rules. However, CNAME records cannot coexist with other CNAME records or other DNS records (such as MX, TXT, or A) at the same name, except in special cases involving CNAME flattening. Only one DNS record can exist with the same name, and CNAME records must not share the same name with other records, as specified in the RFCs.

When a DNS lookup occurs on a CNAME record, the DNS resolver performs another DNS lookup on the target domain, restarting the query using the canonical name instead of the original name, and returns the answer to the client. CNAMEs introduce an extra DNS lookup, though this usually causes negligible latency. CNAMEs also facilitate failover by allowing traffic to be redirected to a backup server if the primary one goes down. However, CNAME looping (when a CNAME points to another CNAME) should be avoided to prevent inefficiencies.
Comment on lines +66 to +68
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 12, 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 | 🟠 Major

This paragraph misstates the DNS rules.

Apex flattening does not make a literal apex CNAME RFC-compliant; the provider synthesizes A/AAAA answers instead. Also, multiple RRsets can share the same owner name—the restriction is specifically that a name with a CNAME cannot have other data at that same name. The last sentence also describes a chain, not a loop/cycle.

Suggested rewording 
-In addition, CNAME flattening allows you to create a CNAME record at the root of your domain without violating the RFC's rules. However, CNAME records cannot coexist with other CNAME records or other DNS records (such as MX, TXT, or A) at the same name, except in special cases involving CNAME flattening. Only one DNS record can exist with the same name, and CNAME records must not share the same name with other records, as specified in the RFCs.
-
-When a DNS lookup occurs on a CNAME record, the DNS resolver performs another DNS lookup on the target domain, restarting the query using the canonical name instead of the original name, and returns the answer to the client. CNAMEs introduce an extra DNS lookup, though this usually causes negligible latency. CNAMEs also facilitate failover by allowing traffic to be redirected to a backup server if the primary one goes down. However, CNAME looping (when a CNAME points to another CNAME) should be avoided to prevent inefficiencies.
+In practice, CNAME flattening gives you CNAME-like behavior at the root without publishing a literal apex CNAME in DNS responses. The DNS provider resolves the target internally and serves synthesized A/AAAA answers instead.
+
+When a DNS lookup follows a CNAME, the resolver continues resolution using the canonical target name and returns the final answer to the client. CNAMEs can add another lookup step, though the latency impact is usually small. A name that has a CNAME must not also have other record types at that same name, and CNAME cycles (for example, `a.example` -> `b.example` -> `a.example`) should be avoided.
📝 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.

Suggested change
In addition, CNAME flattening allows you to create a CNAME record at the root of your domain without violating the RFC's rules. However, CNAME records cannot coexist with other CNAME records or other DNS records (such as MX, TXT, or A) at the same name, except in special cases involving CNAME flattening. Only one DNS record can exist with the same name, and CNAME records must not share the same name with other records, as specified in the RFCs.
When a DNS lookup occurs on a CNAME record, the DNS resolver performs another DNS lookup on the target domain, restarting the query using the canonical name instead of the original name, and returns the answer to the client. CNAMEs introduce an extra DNS lookup, though this usually causes negligible latency. CNAMEs also facilitate failover by allowing traffic to be redirected to a backup server if the primary one goes down. However, CNAME looping (when a CNAME points to another CNAME) should be avoided to prevent inefficiencies.
In practice, CNAME flattening gives you CNAME-like behavior at the root without publishing a literal apex CNAME in DNS responses. The DNS provider resolves the target internally and serves synthesized A/AAAA answers instead.
When a DNS lookup follows a CNAME, the resolver continues resolution using the canonical target name and returns the final answer to the client. CNAMEs can add another lookup step, though the latency impact is usually small. A name that has a CNAME must not also have other record types at that same name, and CNAME cycles (for example, `a.example` -> `b.example` -> `a.example`) should be avoided.
🤖 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
around lines 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.

Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

@aishwaripahwa12

Copy link
Contributor

@coderabbitai coderabbitai bot Mar 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!


CNAME records are very common and help administrators avoid repeating IP addresses or other information across multiple DNS records.

From the developer's perspective, it behaves just like a normal CNAME setup, but works at the root domain too.

Depending on your DNS provider, apex-domain CNAME-like behavior may be supported through **CNAME records**, **ALIAS records**, or **ANAME records**.

- **CNAME flattening** (used by providers like Cloudflare) resolves the target hostname internally and returns A/AAAA records for the root domain.
- **ALIAS records** (used by providers like Route 53 and others) behave similarly by dynamically resolving a hostname and returning its IP addresses at the apex.
- **ANAME records** are another variation that achieves the same goal, allowing the root domain to point to a hostname while remaining DNS-compliant.
- The exact implementation varies by provider, but the outcome is the same: your root domain can point to another hostname without breaking DNS standards.

# What changed in Appwrite sites

With CNAME flattening support, you no longer need to switch your nameservers to Appwrite.

You can now:

1. Keep your existing DNS provider.
2. Add a DNS record pointing to Appwrite.
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.
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 12, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

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.

Suggested change
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.


No nameserver migration. No full DNS handover.

This makes Appwrite Sites much easier to integrate into existing setups, especially for teams using Cloudflare or other advanced DNS configurations.

Read the [full CNAME flattening announcement](https://appwrite.io/blog/post/announcing-cname-flattening) for more details.

# How to connect your domain now
Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

Suggested change
# How to connect your domain now
# How to connect your domain with CNAME flattening


When you add a custom domain to your Appwrite Site:

1. Open your site settings in the Appwrite console.
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).
Copy link
Member

@adityaoberai adityaoberai Mar 13, 2026

Choose a reason for hiding this comment

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

Suggested change
5. Create the required DNS record directly, using the correct record type (CNAME or ANAME).
5. Create the required CNAME, ANAME, or ALIAS record.

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.
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 12, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

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.

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.
🤖 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.


# Before vs now

Before, connecting a custom domain meant transferring full DNS control to Appwrite. You'd migrate your nameservers, wait out propagation, and hope nothing broke on the domains you already had in production. For teams using Cloudflare for security, caching, or email, it meant walking away from a setup that was already working.

Now, none of that is required. Add a single DNS record, verify the domain in Appwrite, and you're live. Your nameservers stay where they are. Your existing records stay untouched. The rest of your DNS configuration , email routing, CDN rules, security settings, carries on exactly as before.

# Try it out

Head to your [Appwrite Console](https://cloud.appwrite.io/), open your site settings, add a custom domain, and follow the updated DNS instructions. No nameserver changes required.

# Resources

- [Appwrite Sites docs](https://appwrite.io/docs/products/sites)
- [Appwrite Discord](https://appwrite.io/discord)
Binary file added static/images/blog/cname-flattening-for-appwrite-sites/cover.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.
Loading