Add a Subdomain to your Custom Domain

Every address you host on a Custom Domain is a Subdomain in CloudCannon, including the Base Domain itself (e.g., example.com⁠). When you add a Subdomain, you choose its Type:

• Site — The Subdomain serves one or more Sites, each at its own subpath. You can add a Subdomain with or without a Site.
• Redirect — The Subdomain sends every visitor to another domain, keeping the path and query string.

For more information, please read our documentation on what a Subdomain is.

This article covers adding a Subdomain from the Domain page. You can also add a Subdomain while you add a Custom Domain to your Site from Site Settings.

Before we begin, this article assumes you have connected a Custom Domain to your Organization.

Add a Subdomain that serves Sites#

To serve a Site on the Subdomain, the Site must be in Hosted Mode. A Site in Headless Mode can't have a Custom Domain. For more information, please read our documentation on what Site Building Mode is.

To add a Subdomain that serves Sites:

1. Log in to CloudCannon.
2. Select the Organization your Custom Domain is connected to.
3. Click the Custom Domains link in the App Sidebar. CloudCannon will open the Domains Browser.
4. Click the Card for the domain you want to add a Subdomain to. CloudCannon will open the Summary tab of the Domain page.
5. Click the Subdomains tab. CloudCannon will open the list of Subdomains on your Custom Domain.
6. Click the Add a Subdomain button. CloudCannon will open the Add a Subdomain modal.
7. Enter the Subdomain name in the Subdomain field (e.g., docs⁠). Leave this field empty to add the Base Domain itself.
8. Select the Site option from the Type dropdown. CloudCannon will show the Site dropdown and the Subpath field.
9. (Optional.) Select the Site you want the Subdomain to serve from the Site dropdown.
10. (Optional.) Enter a path in the Subpath field to serve the Site at that subpath (e.g., /docs/⁠). Leave this field empty to serve the Site at the root of the Subdomain.
11. Click the Add Subdomain button.

CloudCannon will add the Subdomain to the list on the Subdomains tab.

You can also click the Add a Subdomain button on the Summary tab of the Domain page.

If you leave the Site dropdown empty, CloudCannon configures the Subdomain with no Site yet, and its visitors see a 404 page until you add a Site.

When you add the Base Domain (e.g., example.com⁠) as a Subdomain that serves Sites, CloudCannon also adds www.example.com as a redirect to it, unless www.example.com already exists. When you add www.example.com, CloudCannon adds example.com as a redirect to it in the same way. The Add a Subdomain modal shows this redirect below the Site dropdown (e.g., CloudCannon will also add www.example.com as a Redirect Subdomain to example.com.).

If the Site you select already has a Custom Domain, the Add a Subdomain modal shows where the Site moves from and to. For more information, please read our documentation on managing the Sites on a Subdomain.

If you select a Site and the new Subdomain takes your Organization over the number of Custom Domains in its Subscription Plan, CloudCannon opens the Confirm Billing Change modal. Click the Accept Billing Increase button to continue. Subdomains with no Site yet do not count toward this number, so CloudCannon asks when you add the first Site to them instead. For more information, please read our documentation on what Add-Ons and Overages are.

In a Client Organization on its extended six-month Free Trial, serving a Site on a Subdomain that had no Sites ends the trial five days later. CloudCannon opens the Confirm End of Trial modal first. Click the End extended trial button to continue. For more information, please read our documentation on how billing works in the Partner Program.

Add a Redirect Subdomain#

To add a Redirect Subdomain:

1. Log in to CloudCannon.
2. Select the Organization your Custom Domain is connected to.
3. Click the Custom Domains link in the App Sidebar. CloudCannon will open the Domains Browser.
4. Click the Card for the domain you want to add a Subdomain to. CloudCannon will open the Summary tab of the Domain page.
5. Click the Subdomains tab. CloudCannon will open the list of Subdomains on your Custom Domain.
6. Click the Add a Subdomain button. CloudCannon will open the Add a Subdomain modal.
7. Enter the Subdomain name in the Subdomain field (e.g., promo⁠). Leave this field empty to add the Base Domain itself.
8. Select the Redirect option from the Type dropdown. CloudCannon will show the Redirect visitors to field and the Status code dropdown.
9. Enter the domain to which you want to send visitors in the Redirect visitors to field.
10. (Optional.) Select a status code from the Status code dropdown. Leave it on 301 permanent redirect for a permanent redirect.
11. Click the Add Subdomain button.

CloudCannon will add the Redirect Subdomain to the list on the Subdomains tab.

The destination can be a Subdomain on your Custom Domain or any other domain. If the destination is on a Custom Domain connected to your Organization, it must already be a Subdomain there. CloudCannon won't add a redirect to the Subdomain itself, or a redirect that sends visitors around in a loop, and shows why below the Redirect visitors to field. For how loops form and how to fix one, please read our documentation on fixing a redirect loop.

Redirect Subdomains do not count toward the number of Custom Domains in your Subscription Plan. For more information on status codes, and on redirecting a whole domain to another domain, please read our documentation on managing your Redirect Subdomains.

After you add a Subdomain#

Every new Subdomain starts on CloudCannon Hosting. Once the Subdomain's DNS points at CloudCannon, visitors can reach it, and CloudCannon issues its SSL Certificate. If your Custom Domain uses external DNS and the Subdomain is already live elsewhere, you can get the certificate before you switch DNS, using TXT records. This isn't available for your Base Domain. For more information, please read our documentation on issuing the SSL Certificate with TXT validation.

If your Custom Domain has no Fallback Redirect yet, the new Subdomain becomes your Fallback Redirect, whichever Type you chose. If it is a Site Subdomain with no Site yet, its visitors, and visitors to subdomains you haven't set up, see a 404 page until you add a Site.

On CloudCannon DNS, the wildcard record CloudCannon adds for your Base Domain covers new Subdomains one level below it (e.g., docs.example.com⁠) on CloudCannon Hosting. A Subdomain nested more than one level deep (e.g., api.docs.example.com⁠) needs its own record. On external DNS, the DNS tab of the Domain page and the DNS section of the Subdomain page list the records the new Subdomain needs at your DNS Provider. For more information, please read our documentation on configuring CloudCannon DNS and configuring external DNS.

To change how visitors reach the Subdomain, or how it gets its certificate, please read our documentation on configuring a Subdomain's hosting, HTTPS, and DNS and adding an auto-generated SSL Certificate.