Vanity Domains

Replace "pantheonsite.io" within Pantheon environments by adding a custom vanity domain.

Edit this page on GitHub | Report an issue with this doc

This section provides information on to set up a vanity domain.

Pantheon Partners, Strategic Partners, Enterprise accounts, Resellers, and OEM Partners have the ability to provision a custom vanity domain for each environment on every site running on the platform, in addition to the default Platform domain (pantheonsite.io).

Note

HTTPS is not provisioned for vanity domains. Only custom domains will have HTTPS provisioned. To provision HTTPS for vanity domains, contact Sales to learn how to host your custom certificate on Pantheon.

The Vanity domain can either be a subdomain of your primary site (sites.mydomain.com) or a dedicated domain name (mypantheonprojects.com).

If a subdomain of your primary site is configured, a newly created site named "supersite" will then have a Dev environment URL of dev-supersite.sites.mydomain.com. If a dedicated domain name is used, the site would instead have a Dev environment URL of dev-supersite.mypantheonprojects.com.

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.

Request the Vanity Domain

Go to the Workspace, and select the Dashboard to open a support ticket with "Request for custom Vanity domain" as the subject.
Provide the Vanity domain required on the site, such as sites.example.com.

Note

We recommend using a separate domain from your production site. This prevents any security issues related to domain-specific cookies. Even the same domain under a different TLD (.com, .net, etc) would suffice.

AGCDN Vanity Domains

You must provide a custom certificate if you want to use a vanity domain on your Advanced Global CDN site.

Our Custom Certificate service is only available to contract customers, including Elite, Enterprise, Higher Education, and Resellers.

Create Wildcard DNS Records

Warning

Using wildcard DNS settings is not considered best practice on a cloud-hosted platform such as Pantheon. It is more secure to create explicit records for each subdomain you require. Learn more about preventing DNS hijacking.

At your DNS provider, create a wildcard A/AAAA record pointing to our edge. Using the example domain sites.example.com, the record would need to be created as follows. Replace X with a 1, 2, 3, or 4:

*.sites.example.com A 23.185.0.X
*.sites.example.com AAAA 2620:12a:8000::X
*.sites.example.com AAAA 2620:12a:8001::X

Refer Introduction to Domain Name Services for more information about AAAA records.

Note

If the domain in question is already in use, be sure to configure your vanity domain at Pantheon before changing DNS records to avoid any downtime.

Effects and Considerations

Existing sites created before configuring a Vanity domain will continue to use the default Platform domains and will not use the custom Vanity domain.
Sites associated with your Workspace will receive the custom Vanity domain for all environments (including Multidev) created while the Workspace remains a Supporting Workspace.
After adding a custom Vanity domain to your Workspace, some workflow operations such as restoring an environment from a backup or changing the PHP version, can cause site domain URLs in other environments to unexpectedly change from the Pantheon domain to the custom domain.
Environment URLs are permanent. If an Workspace is removed as the Supporting Workspace, any environment created during its association will keep the original URL after removal. Paid sites can add custom domains to any environment, as a workaround for those wishing to use different URLs after launch and disassociation of the site with the Workspace.
Do not configure DNS for custom domains using Vanity domain values. Even after configuring a vanity domain, your custom domain records should always be A/AAAA records pointing to the platform IP addresses, as recommended within the Domains / HTTPS page. Vanity domains are designed to be viewed by end users, not added into records for other domains.

Incorrect DNS Configuration

Incorrect vanity domain A record required DNS value

Correct DNS Configuration

Correct vanity domain A record required DNS value

If your site uses a custom domain instead of a platform domain, edit the wp-config.php to reflect the custom domain.

Security Considerations

If you run sites on subdomains of your primary site (for example, sites.awesomeagency.com), you should be aware of some security considerations:

Note

Sites on the subdomains may be able to read cookies set on your primary site.
If a site on the subdomain is reported as a malicious phishing/spam/malware site, it could prevent access to your main marketing site if Google/Norton/etc. block the site.

Robots.txt with Custom Vanity Domains

The robots.txt file attached to the custom vanity domain will contain the following by default for SEO and to prevent duplicate content:

robots.txt

# https://live-sitename.agencyname.com/robots.txt
User-agent: *
Disallow: /

You can add a custom domain to the site's Dashboard and create the appropriate DNS record to present an alternate robots.txt file from within the source code.