Skip to main content
Log inGet free account

Custom Domains

Learn how to add a custom domain.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

This section provides information on how to add a custom domain to the Pantheon platform.

Custom Domains

Pantheon provides the values for your DNS records that are assigned with your DNS service provider when adding a custom domain to your site:

DNS Recommendations

If you don't already own a domain name, register one with a third-party provider. Pantheon is not a domain registrar, but we've created documentation for several popular DNS managers:

Connect your custom domain on the Site Dashboard, and point DNS at Pantheon to trigger automated HTTPS provisioning.

A paid plan is required to connect custom domains to your site, up to the following limits:

Custom Domain Limit (per site)Free and Managed HTTPS
Basic5✔
Performance S10✔
Performance M15✔
Performance L35✔
Performance XL70✔
Elite270✔

For more details on connecting custom domains, see https://docs.pantheon.io/guides/domains/custom-domains

Note

Add all domains (example.com and www.example.com are different domains) you want to resolve to Pantheon within the Site Dashboard, for each respective environment, as described in Launch Essentials. Automatic resolution of domains and wildcards are not supported.

Note that each custom domain is counted regardless of the environment to which it's added.

Add a Custom Domain

Google Top Level Domains and HSTS

In September 2017, Google announced that is was planning to make HSTS preloading mandatory for the Top-Level Domains (TLDs) available exclusively through Google Registry. That means that, moving forward, some TLDs will automatically redirect to HTTPS, and will be unable to load insecure sites or site pages. When selecting a domain to use as a custom or vanity domain, it's important to note the 45 TLDs that are subject to mandatory HSTS preloading:

.gle .prod .docs .cal .soy .how .chrome .ads .mov .youtube .channel .nexus .goog
.boo .dad .drive .hangout .new .eat .app .moto .ing .meme .here .zip .guge .car
.foo .day .dev .play .gmail .fly .gbiz .rsvp .android .map .page .google .dclk
.search .prof .phd .esq .みんな .谷歌 .グーグル

When using one of the above domains as a vanity domain, keep in mind that every environment domain must have HTTPS provisioned or that environment's domain will be inaccessible. Because Pantheon doesn't provision HTTPS for vanity domains, this will need to be set up and managed using a custom certificate. You should also keep in mind that any Multidev environments created using a secure only TLD will need to have HTTPS provisioned before the site domain will work.

When using one of the above TLDs as a custom domain for your site, Pantheon will provision the necessary certificates if you are using Pantheon's automated Global CDN. If the site is using a custom certificate, then each custom domain needs to have the certificate provisioned by the 3rd-party used to manage HTTPS for the site.

  1. Log in as an Admin, Team Member, or Privileged User.

  2. Go to the Site Dashboard for the environment you want the domain to point to (usually Live), and then click the Domains / HTTPS tab.

  3. Enter a domain and click Connect Domain:

    Adding a first domain to the Site Dashboard

    If one (or more) domains have already been added, click Connect Domain:

    Adding an additional domain to the Site Dashboard

  4. Verify ownership by adding a new DNS TXT value or by uploading a file to a specific URL.

  5. Select the method you prefer, and follow the instructions. Note that the values are randomized for security.

  6. Click Verify Ownership to confirm:

    Note

    Professional workspaces that have wildcard domain(s) pointed at Pantheon may have a valid use case for opt-ing out of domain verification (e.g., WordPress Multisite with many subdomains). For details, see this FAQ below.

    Verify domain ownership for HTTPS by DNS or by uploading a file to an existing site

    It might take 30 minutes or more for DNS records to propagate, depending on your DNS host and your domain's TTL values. If you encounter issues after 30 minutes, check some of the following:

    • Ensure that there's no "parking page" or redirect configured in your DNS.

    • The TXT record's Host value doesn't have a trailing ..

    • That the DNS value has propagated.

      You'll automatically be taken to the domain's Details page where you will see both the current DNS records detected (the Detected Values), as well as the values to be added at your DNS host (Required Values):

      Custom domain Details page

    If you instead see:

    Waiting for HTTPS, DNS records will be provided when HTTPS provisioning completes.

    Wait a minute, then refresh the page.

  7. Add the values to your DNS management service. Refer to Introduction to Domain Name Services for more details.

    • Note that if the Platform detects a CNAME record, the Status will show Remove this detected record on the line with the CNAME. Remove the CNAME from the DNS management service to avoid potential issues or interruptions.

FAQ

I have existing custom domains which were previously connected and launched prior to the enforcement of Domain Verification, will those be impacted?

No. Any custom domains previously added or launched will not require explicit domain verification. However, if any of those domains are deleted by the customer and then re-added, the process of re-addition (whether to the same environment or any other environment) will trigger domain verification.

Is pre-provisioning HTTPS now a requirement to connect a custom domain?

Yes. Skipping HTTPS provisioning is no longer an option.

Is Wild Card DNS routing supported by Domain Verification?

Pantheon does not allow wild card domains to be directly added as a custom domain. Customers may point wildcard domains (eg: *.example.com) in their own DNS to Pantheon, but are still required to have specific domains (eg: mysite.example.com) added and connected to specific environments on Pantheon.

How can I know which domains are still pending ownership verification ?

For any domain that has been added that is pending verification, clicking on the "Details" button in the Domains list page for that domain will take you to another page where you can put in the information required to verify ownership for that domain. If the ownership of the domain has been already verified, the detail page will instead show the DNS records you need to update in your authoritative DNS to point to Pantheon, as well as the status of HTTPS provisioning. In other words, if your domain is not verified, we will require you to provide the necessary information to verify ownership first.

You can get a high-level status view for all custom domains connected to a given environment via Terminus using the https:info command. Domains that are pending verification will have the "Verification Pending" status returned as part of the Terminus https:info command.

Can I opt-out of Domain Verification?

Yes, a professional workspace can opt-out from domain verifications across all sites in their organization but only by request. Please contact support to request exemption from domain verification, and once granted - you will see an option to skip domain verification when connecting domains to sites in your workspace.

Exemption is only available at the workspace level. For example, you cannot request exemption for just one site in your workspace, or an individual custom domain such as example.com.

How does the enforcement of Domain Verification impact the established relaunch procedure?

For details, see the relevant FAQ found in the Relaunch procedure documentation.

More Resources