Add a Custom Domain to your Site

A Custom Domain is a domain you own and connect to your CloudCannon Organization, so visitors reach your Site at your own address (e.g., cloudcannon.com). If you have connected a Custom Domain to your Organization, you can host your website content at that web address by adding the Custom Domain to your Site.

You can host a CloudCannon Site on the Base Domain (e.g., example.com⁠), another Subdomain (e.g., docs.example.com⁠), or a path on either (e.g., example.com/staff/⁠). Several Sites can share a Subdomain, each at its own path. Every Site on a Subdomain shares that Subdomain's hosting, HTTPS, and DNS settings. A Site at a path needs to build into a folder that matches the path. For more information, please read the section on building your Site for a path.

When you add the Base Domain (e.g., example.com⁠) as a new Subdomain, CloudCannon also adds www.example.com as a redirect to it, if www.example.com does not already exist. When you add www.example.com as a new Subdomain, CloudCannon adds example.com as a redirect to www.example.com in the same way.

Before we begin, this article assumes you have connected a Custom Domain to your Organization, and that your Site is in Hosted Mode. CloudCannon hides the Custom Domain page for a Site in Headless Mode. For more information, please read our documentation on what Site Building Mode is.

Add a Custom Domain from Site Settings#

To add a Custom Domain to your Site:

1. Log in to CloudCannon.
2. Select the Organization with the Site you want to add a Custom Domain to.
3. Click the Sites link in the App Sidebar. CloudCannon will open the Sites Browser.
4. Click the Card for the Site you want to add a Custom Domain to. CloudCannon will open the Dashboard for that Site.
5. Navigate to the Custom Domain page under Site Settings. CloudCannon will open the Custom Domain page.
6. Select the Custom Domain you want to add using the Base Domain dropdown.
7. (Optional.) Enter a Subdomain in the Subdomain text field. Leave this field empty to host your Site on the Base Domain itself.
8. (Optional.) Enter a path in the Subpath text field (e.g., /jobs/⁠), using lowercase letters, numbers, _, and -. Leave this field empty to host your Site at the root of the Subdomain.
9. Click the Add custom domain button.

CloudCannon will add your Site to the Subdomain. Visitors reach your Site on your Custom Domain once the DNS for the Subdomain points at CloudCannon. Until then, your Site stays on its Testing Domain, and the Custom Domain page shows a setup guide:

• CloudCannon DNS — If the nameservers of your domain don't point at CloudCannon DNS yet, the guide shows the nameservers to set at your domain registrar. Without the base-domain:settings:dns:read permission, the guide asks you to finish setting up DNS but doesn't list the nameservers. For more information, please read our documentation on configuring CloudCannon DNS.
• External DNS — On external DNS, the guide shows how far along setup is, and its Scroll to DNS Records button scrolls to the DNS section, which lists the record the Subdomain needs at your DNS Provider, with a Copy icon next to each value and the I've updated it button. For more information, please read our documentation on configuring external DNS.

If the Subdomain you enter already exists, CloudCannon adds your Site to it:

• The Subdomain already serves Sites — Your Site joins it and uses its hosting, HTTPS, and DNS settings. The path you choose must not already be in use on the Subdomain.
• The Subdomain is a redirect — Adding your Site stops the redirect and serves your Site on the Subdomain instead. Before you add it, the Custom Domain page warns you (e.g., www.example.com redirects to example.com now. Adding Marketing site stops the redirect and serves Marketing site there.).

The Base Domain dropdown disables any domain whose settings you can't edit and labels it No permission. If you have the base-domain:create permission, you can also connect a new domain from the dropdown. For more information, please read our documentation on connecting a Custom Domain to your Organization.

If the Subdomain has no other Sites and takes your Organization over the number of Subdomains serving Sites that its Subscription Plan includes, CloudCannon will ask you to confirm the extra cost before adding it. If your Organization has no payment method, CloudCannon opens the Add your Credit Card modal 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 shortens the trial so that it ends five days later, whether or not the Client Organization is still within the limits of its Subscription Plan. CloudCannon asks you to confirm before it shortens the trial. For more information, please read our documentation on how billing works in the Partner Program.

You can also add a Site to a Subdomain from the Subdomain page, which you can open from the Subdomains tab of your Domain page. For more information, please read our documentation on managing the Sites on a Subdomain.

Build your Site for a path#

If you host your Site at a path (e.g., example.com/docs/⁠), your build output needs a folder that matches the path. CloudCannon doesn't remove the path from a request before it looks for the file, so it serves example.com/docs/about/ from docs/about/index.html in your build output. Your Site's links also need to include the path, so that a link to /about/ becomes /docs/about/.

Many SSGs have a setting that adds a path to your links, but not all of them also build your files into a matching folder. After you add a path, check that your build output has a folder with that name and that every page of your Site is inside it.

If your Jekyll Site sets baseurl in its _config.yml file, CloudCannon serves the build output under that baseurl instead. Set baseurl to the same path (e.g., /docs⁠) rather than moving your files.

Use Reseed to build for a path

Reseed is an open-source tool that copies your build output into a folder named after the path and rewrites the links in your pages to include it. You can run Reseed after your build in a postbuild script:

#!/bin/bash

npx reseed -s _site -d _reseed -b docs
rm -rf _site
mv _reseed _site

Replace _site with the Output Path of your Site, and docs with your path. CloudCannon uploads the files in your Output Path once the postbuild script finishes, so the script must leave the rewritten files there. For more information, please read our documentation on extending your build process with hooks and configuring your command line options.

CloudCannon can also run Reseed as a build step for you.

To run Reseed as a build step:

1. Contact our support team with the name of your Site and the path.
2. Enter the path in the Baseurl field on the Reseed page under Site Settings.
3. Click the Update Reseed Details button.

CloudCannon will rebuild your Site with the new path.

Review your Site's Custom Domain#

Once your Site has a Custom Domain, the Custom Domain page under Site Settings shows the address of your Site on the Subdomain, the same way the Testing Domain page shows its Testing Domain. The line above the address says which state it is in:

• [Site Name] goes live at this address once [Subdomain] points at CloudCannon - The DNS record for the Subdomain doesn't point at CloudCannon yet.
• [Site Name] is live at - Visitors reach your Site at this address over HTTPS.
• [Site Name] is live at this address, and CloudCannon is turning HTTPS on - Visitors reach your Site, and its SSL Certificate is on its way.
• [Site Name] is live at this address, but HTTPS is not working, so visitors see a security warning - The HTTPS section under Subdomain settings says why.

Until the Subdomain is live, the setup guide appears below the address. The Danger zone section above the Subdomain settings heading has the Remove custom domain button, which stops hosting your Site on the Subdomain. For more information, please read our documentation on removing a Custom Domain from your Site.

Below the Subdomain settings heading, a line links to the page for the Subdomain on your Domain page, and the page for the Subdomain follows, without its heading. It has the same Sites, Hosting, HTTPS, DNS, and Danger zone sections as the Subdomain page you open from the Subdomains tab of your Domain page, because these settings belong to the Subdomain and apply to every Site on it. The Sites section lists every Site the Subdomain serves, with the path at which each Site is served, and labels your Site with This site.

From the Subdomain settings, you can:

• Click the Add a Site button in the Sites section to serve another Site on the Subdomain.
• Click the Context Menu for a Site in the Sites section and select the Open Site, Swap for another Site, Change Subpath, or Remove from [Subdomain] option. For more information, please read our documentation on managing the Sites on a Subdomain.
• Click the Configure hosting button in the Hosting section or the Configure HTTPS button in the HTTPS section, or check the DNS in the DNS section. For more information, please read our documentation on configuring a Subdomain's hosting, HTTPS, and DNS.
• Click the Change Subdomain Type button next to Change Subdomain type to Redirect in the Danger zone section to change the Subdomain into a redirect to another domain. For more information, please read our documentation on managing your Redirect Subdomains.
• Click the Delete Subdomain button in the Danger zone section to delete the Subdomain. For more information, please read our documentation on deleting a Subdomain.

If a change in the Subdomain settings takes your Site off the Subdomain, such as removing or swapping your Site, changing the Subdomain to a redirect, or deleting the Subdomain, CloudCannon opens the [Site Name] is no longer on [Subdomain] modal. The modal explains what happened and that your Site keeps its Testing Domain. Click the Stay here button to stay on the Custom Domain page, or the Go to [Subdomain] settings button to open the page for the Subdomain. If you deleted the Subdomain, the second button is Go to subdomains, and it opens the Subdomains tab instead.

If you can view the Custom Domain but don't have the base-domain:settings:details:write permission for its Base Domain, a sentence that explains which permission you need replaces the Subdomain settings. If you don't have the base-domain:details:read permission for the Custom Domain, the Custom Domain page shows only your Site's address, with a Subpath for [Site Name] field, an Update Subpath button, and the Remove custom domain button. All three are disabled, and hovering over each one shows a tooltip that names the permission you need. To change the path or remove the Custom Domain, ask a member of your Organization who can edit the settings of the Base Domain (the base-domain:settings:details:write permission), such as a member of the Owners, Developers, or Partner Default Permission Groups, to make the change.

You should also check the SSL Certificate for your Site's Subdomain. For more information, please read our documentation on adding an auto-generated SSL Certificate or adding a Custom SSL Certificate.