What is a Subdomain?

A Subdomain is a name in front of your Base Domain, for example the www in www.example.com or docs in docs.example.com. In CloudCannon, every address you host on a Custom Domain is a Subdomain, including the Base Domain itself (i.e., example.com is an empty Subdomain).

After you connect a Custom Domain to your Organization, you can add a Subdomain to your Custom Domain and choose whether each one serves one or more Sites, or redirects visitors to another domain. Each Subdomain has its own hosting, HTTPS, and DNS settings, which apply to every Site it serves. You can also configure a Fallback Redirect for visitors to subdomains you haven't set up (e.g., typo.example.com⁠).

CloudCannon lists all the Subdomains on your Custom Domain on the Subdomains tab of its Domain page. For more information, please read our documentation on what the Domain page is.

This article covers the Subdomains on a Custom Domain. For the Custom Domain itself, including who owns it and its DNS Provider, please read our documentation on what a Custom Domain is.

Why use a Subdomain?#

Subdomains let you give each area of your website its own address on one Custom Domain. You might use a Subdomain to:

• Serve a separate Site for each area. Each Site can use its own Git Repository, or several Sites can share one Git Repository, each with its own build settings and configured to show different content.
• Give an area its own hosting option or SSL Certificate, such as putting one Subdomain behind your own Cloudflare account.
• Send an old or alternative address, such as www.example.com, to your main Site with a redirect.

You can also serve several Sites on one Subdomain, each at its own subpath (e.g., /docs/ in example.com/docs/⁠). To choose between them:

• Subdomain — Has its own hosting, HTTPS, and DNS settings. On external DNS, it needs its own DNS record. Each Subdomain that serves Sites counts toward the number of Custom Domains in your Subscription Plan.
• Subpath — Shares the hosting, HTTPS, and DNS settings of its Subdomain, and doesn't count as another Custom Domain.

For more information, please read our documentation on managing the Sites on a Subdomain and adding a Custom Domain to your Site.

Subdomain types#

When you add a Subdomain to your Custom Domain, you must select its Type. The Type decides what the Subdomain does:

• Site — The Subdomain serves one or more Sites, each at its own subpath.
• Redirect — The Subdomain sends every visitor to another domain.

You can switch your Subdomain Type at any time. For more information, please read our documentation on adding a Subdomain to your Custom Domain and managing your Redirect Subdomains.

Site Subdomains

A Site Subdomain serves built files to website visitors from one or more CloudCannon Sites. CloudCannon builds your Site each time it syncs a change from your Git Repository, including the changes you save in CloudCannon, and when you start a build yourself, such as with the Rebuild button. For more information, please read our documentation on what a Site build is.

To build and serve Site files on a Subdomain, that Site must be in Hosted Mode. This is the default setting for Sites in CloudCannon, but you can configure the Site Building Mode on the Details page under Site Settings. For more information, please read our documentation on what Site Building Mode is and enabling Headless Mode.

You can serve several Sites on one Subdomain, each at its own subpath. For example, example.com can serve a marketing Site at / and a documentation Site at /docs/:

• A visit to example.com/docs/setup/ goes to the documentation Site, because CloudCannon serves the Site with the longest subpath that matches the request.
• A visit to example.com/about/ goes to the marketing Site, the only Site whose subpath matches.
• If example.com had no Site at /, a visit to a path that doesn't match any Site, such as example.com/about/, would show a 404 page.

A Site at a subpath needs to build its files into a folder that matches the subpath (e.g., a docs folder for /docs/⁠). For more information, please read our documentation on adding a Custom Domain to your Site and managing the Sites on a Subdomain.

A Subdomain belongs to your Custom Domain, not to any Site, so removing a Site doesn't remove its Subdomain. When you remove the last Site from a Subdomain, CloudCannon asks whether to leave the Subdomain set up with no Site, turn it into a redirect, or delete it. A Subdomain with no Site keeps its hosting and certificate, and its visitors see a 404 page until you add a Site. For more information, please read our documentation on managing the Sites on a Subdomain and removing a Custom Domain from your Site.

Redirect Subdomains

A Redirect Subdomain sends every visitor to another domain, keeping the path and query string. For example, if www.example.com redirects to example.com, a visit to www.example.com/about/ goes to example.com/about/. The destination can be a Subdomain on your Custom Domain or any other domain. Each Redirect Subdomain also has its own status code, which is 301 permanent redirect unless you choose another.

Redirects send visitors to the destination over HTTPS when the destination has an SSL Certificate. A Redirect Subdomain still needs DNS records that point at CloudCannon, and its own SSL Certificate, but it doesn't count toward the number of Custom Domains in your Subscription Plan. CloudCannon won't save a redirect that points at its own Subdomain or sends visitors around in a loop.

You change the destination and status code with the Change Target button in the Redirect section of the Subdomain page. For more information, please read our documentation on managing your Redirect Subdomains.

The Fallback Redirect#

Subdomains you haven't set up (e.g., a misspelled subdomain), including Subdomains you have deleted, send visitors to your Fallback Redirect. A Site Subdomain with no Site yet shows its visitors a 404 page instead. On external DNS, visitors only reach a subdomain that isn't set up if you add a wildcard DNS record at your DNS Provider. Your Fallback Redirect can be any Subdomain on your Custom Domain, including a Redirect Subdomain. If your Fallback Redirect is a Site Subdomain with no Site yet, its visitors see a 404 page until you add one.

For example, suppose you have one Site on example.com and another Site on docs.example.com, and example.com is your Fallback Redirect. CloudCannon sends anyone trying to access an unconfigured subdomain (e.g., app.example.com⁠) to example.com.

The Fallback Redirect uses a 307 temporary redirect, keeping the method status code by default, because a temporary redirect stops search engines from treating an unconfigured subdomain as moved. You can choose any of the status codes that Redirect Subdomains use, which are described in our documentation on managing your Redirect Subdomains. You change the Fallback Redirect and its status code with the Change Fallback button in the Fallback Redirect section of the Subdomains tab.

For more information, please read our documentation on updating the Fallback Redirect for your Custom Domain. For the wildcard DNS record, please read our documentation on configuring external DNS.

Hosting, HTTPS, and DNS#

Hosting, HTTPS, and DNS belong to the Subdomain, not to each Site, so they apply to every Site on the Subdomain. Each has its own section on the Subdomain page. The Custom Domain page under Site Settings shows the same sections under the Subdomain settings heading, for the Subdomain that serves that Site. For more information, please read our documentation on configuring a Subdomain's hosting, HTTPS, and DNS.

Hosting

You can choose one of three hosting options for each Subdomain: CloudCannon Hosting, Cloudflare Proxy, or Single Origin. To choose between them:

• CloudCannon Hosting — CloudCannon serves your Site from its global network, so pages load quickly everywhere. This is the default and recommended option, and suits most Subdomains. If your Custom Domain uses external DNS, your Base Domain (e.g., example.com⁠) can't use a CNAME record, so it uses two A records instead. Visitors to your Base Domain reach CloudCannon's origin servers directly rather than through the global network, and your Site works the same way.
• Cloudflare Proxy — Your own Cloudflare account proxies the Subdomain to CloudCannon. Choose this if your DNS is on Cloudflare and you want to keep Cloudflare in front of your Site. Cloudflare Proxy isn't available while your Custom Domain uses CloudCannon DNS. Cloudflare may serve cached pages, so your Site won't show updates until you clear your Cloudflare cache.
• Single Origin — Visitors reach CloudCannon's origin servers directly, without going through CloudCannon's global network. Choose this if you run your own proxy or firewall in front of CloudCannon. Your Base Domain uses two A records, and other Subdomains use a CNAME record. CloudCannon can only validate the certificate once DNS points at CloudCannon.

The hosting option decides which DNS records the Subdomain needs, so changing it can mean updating your records. For more information, please read our documentation on how hosting works on CloudCannon and configuring external DNS.

HTTPS

Each Subdomain gets its own SSL Certificate, which covers every Site on that Subdomain. Subdomains you haven't set up yet are covered by the domain's wildcard SSL Certificate instead, which covers one level of subdomain (e.g., typo.example.com, but not a.typo.example.com⁠). On external DNS, the wildcard SSL Certificate needs records at your DNS Provider to be issued and renewed, and without them HTTPS stops working for subdomains you haven't set up.

Each Subdomain also has its own minimum TLS version, which can't be lower than the minimum for your Custom Domain. The minimum you set on your Base Domain's own Subdomain also applies to subdomains you haven't set up. For more information, please read our documentation on increasing the minimum TLS version for your domains, what an SSL Certificate is, adding an auto-generated SSL Certificate, renewing the wildcard SSL Certificate on external DNS, and adding a Custom SSL Certificate.

DNS

Each Subdomain needs a DNS record that points at CloudCannon. On CloudCannon DNS, the wildcard record CloudCannon adds for your Base Domain covers every Subdomain one level below it (e.g., docs.example.com⁠) on CloudCannon Hosting, unless you add a record for a Subdomain that points somewhere else. A Subdomain on Single Origin, or one nested more than one level deep (e.g., api.docs.example.com⁠), needs its own record. On external DNS, you add a record for each Subdomain at your DNS Provider. For more information, please read our documentation on configuring CloudCannon DNS and configuring external DNS.

Who can change a Subdomain#

Changing a Subdomain's hosting, HTTPS, or redirect, or your Fallback Redirect, requires permission to edit the settings of the Base Domain (the base-domain:settings:details:write permission). Adding, swapping, or removing a Site on a Subdomain, or changing the subpath at which it is served, requires that permission and the site:settings:hosting:write permission for the Site, from the Subdomain page and the Custom Domain page under Site Settings alike. Deleting a Subdomain that serves Sites, or changing it to a redirect, also requires the site:settings:hosting:write permission for each of those Sites.

Members of the Owners and Developers Default Permission Groups, and of the Partner group in a Client Organization, hold both permissions. On the Team Plan or Enterprise Plan, you can also grant them to a Custom Permission Group. If you don't have permission, the buttons and Context Menu options for these changes are disabled on the Subdomain page, and on the Custom Domain page under Site Settings, a sentence that explains which permission you need replaces the Subdomain settings. Hover over a disabled option in a Site's Context Menu to see which permission you're missing. To get access, ask a member of the Owners group in your Organization.