Platform and Custom Domains
Work with platform domains or connect custom domains in the Site Dashboard, then redirect requests via PHP to standardize traffic on HTTPS and a primary domain.
Discuss in our Forum Discuss in SlackA domain name is the web address or URL used to visit your site. The Domain Name System (DNS) resolves human-readable names like www.example.com
into machine-readable IP addresses like 127.0.0.1
. All Pantheon sites are accessible via platform domains, and you can easily connect your own custom domain to paid sites.
Get WebOps Training
Optimize your dev team and streamline internal workflows. Pantheon delivers custom workshops to help development teams master our platform and improve their internal WebOps
Platform Domains
Pantheon issues platform domains for all environments. Each environment (Dev, Test, Live, each Multidev) is accessible via the platform domain, matching the following patterns:
- dev-site-name.pantheonsite.io
- test-site-name.pantheonsite.io
- live-site-name.pantheonsite.io
- multidev-env-site-name.pantheonsite.io
All platform domains are available over HTTPS. Redirecting to HTTPS during development and testing is a good best practice to ensure you are ready to go live with HTTPS. See Redirect to HTTPS for more information.
robots.txt
Pantheon serves a default robots.txt
that disallows crawlers on platform domains (/*.pantheonsite.io
, /*.pantheon.io
, /*.gotpantheon.com
, and /*.sites.my-agency.com
). Crawlers are allowed on the Live environment for requests served with a custom domain (e.g., www.example.com
). If you attempt to access your Live environment with a platform domain, even if you have a domain associated with the environment, the default robots.txt
will be served.
Pantheon does not allow crawlers on Dev, Test, or Multidev environments. Adding a custom domain to an environment other than Live will not permit crawlers to that environment.
Custom Domains
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:
DNS Host-Specific Instructions
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:
Basic | Performance S | Performance M | Performance L | Performance XL | Elite | |
---|---|---|---|---|---|---|
Custom Domain Limit (per site) | 5 | 10 | 15 | 35 | 70 | 270 |
Free and Managed HTTPS | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
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.
Log in as an Admin, Team Member, or Privileged User.
From the Site Dashboard, for the environment you want the domain to point to (usually Live), click on the Domains / HTTPS tab.
If no domains have been added yet, enter a domain and click Connect Domain:
If one (or more) domains have already been added, click Connect Domain:
Verify ownership by adding a new DNS TXT value or by uploading a file to a specific URL. Select the method you prefer, and follow the instructions. Note that the values are randomized for security. Click Verify Ownership to confirm, or to skip HTTPS provisioning for now, click Skip without HTTPS:
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.
After you add your domain, you'll be automatically 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):
If you instead see:
Waiting for HTTPS, DNS records will be provided when HTTPS provisioning completes.
Wait a minute, then refresh the page.
Add the values to your DNS management service. For more details, see Introduction to Domain Name Services.
- 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.
- Note that if the Platform detects a CNAME record, the Status will show
Choose Primary Domain
Pantheon uses the term primary domain to refer to a single domain used to serve all traffic from a site. For example, configuring www.example.com
as the primary domain means that requests to example.com
(or any other custom domain connected to the environment) all get redirected to www.example.com
. This assumes that you have added both example.com
and www.example.com
to the Site Dashboard.
Redirecting all traffic to a primary domain is a best practice for SEO since it avoids duplicate content. It also prevents session strangeness, where a user can be logged in to one domain but logged out of other domains at the same time, and it can make it easier to measure and monitor website traffic.
Choose a primary domain from the dropdown at the bottom of Domains / HTTPS:
Note
Redirects cannot be managed via .htaccess
, which is ignored on our platform. For details, see Configure Redirects.
Set a Primary Domain via the Dashboard
Warning
With a Primary Domain set at the platform level, all other domains (except the platform domain) will be pointed to your Primary domain at the root level. If you want to redirect secondary domains to specific pages on your site (for example, olddomain.com
to newdomain.com/old-landing-page
), do not set a Primary Domain. Instead use PHP redirects.
From the environment you want to set a primary domain for (typically Test or Live), navigate to Domains / HTTPS.
Ensure that all domains have been added and are listed.
In the Choose Primary Domain section, select the domain to which traffic should be redirected, and click Save Configuration.
Set a Primary Domain with Terminus
Install or upgrade to the latest version of Terminus.
Use Terminus to add the primary domain. In this example, replace:
my-site
with your site name,live
if you'd like to set it for a different environmentwww.example.com
with your primary domain:
terminus domain:primary:add my-site.live www.example.com
Update or Remove Primary Domain
Update the Primary Domain using either method provided in the previous section.
Remove an existing selection for the Primary Domain on any environment using Terminus:
terminus domain:primary:remove my-site.live
Replace my-site
with your site name, and live
with the environment you're removing a primary domain from.
Verify
You can confirm that the Primary Domain has been removed with cURL pointed at one of your other custom domains, which would previously have been redirected:
curl -I https://example.com
HTTP/2 301
retry-after: 0
server: Pantheon
location: https://www.example.com/
x-pantheon-redirect: primary-domain-policy-docdate: Wed, 05 Feb 2020 16:43:21 GMT
x-served-by: cache-mdw17355-MDW
x-cache: HIT
x-cache-hits: 0
x-timer: S1580921002.586800,VS0,VE1
age: 0
accept-ranges: bytes
via: 1.1 varnish
content-length: 0
The presence of x-pantheon-redirect: primary-domain-policy-doc
indicates that the domain is still being pointed at the former Primary Domain. Contact support if this value persists.
Redirect to HTTPS
It's a best practice for SEO and security to standardize all traffic on HTTPS and choose a primary domain. Configure redirects to the primary domain with HTTPS in pantheon.yml
Redirect with PHP
If your site configuration prevents you from setting the primary domain from the platform level, you can use PHP redirects:
PHP Redirection
Add the following to wp-config.php
, usually placed above /* That's all, stop editing! Happy Pressing. */
. Don't forget to replace www.example.com
:
if (isset($_ENV['PANTHEON_ENVIRONMENT']) && php_sapi_name() != 'cli') {
// Redirect to https://$primary_domain in the Live environment
if ($_ENV['PANTHEON_ENVIRONMENT'] === 'live') {
// Replace www.example.com with your registered domain name.
$primary_domain = 'www.example.com';
}
else {
// Redirect to HTTPS on every Pantheon environment.
$primary_domain = $_SERVER['HTTP_HOST'];
}
$requires_redirect = false;
// Ensure the site is being served from the primary domain.
if ($_SERVER['HTTP_HOST'] != $primary_domain) {
$requires_redirect = true;
}
// If you're not using HSTS in the pantheon.yml file, uncomment this next block.
// if (!isset($_SERVER['HTTP_USER_AGENT_HTTPS'])
// || $_SERVER['HTTP_USER_AGENT_HTTPS'] != 'ON') {
// $requires_redirect = true;
// }
if ($requires_redirect === true) {
// Name transaction "redirect" in New Relic for improved reporting (optional).
if (extension_loaded('newrelic')) {
newrelic_name_transaction("redirect");
}
header('HTTP/1.0 301 Moved Permanently');
header('Location: https://'. $primary_domain . $_SERVER['REQUEST_URI']);
exit();
}
}
WordPress users should also run a search and replace to update any references to the platform domain.
Add the following to the end of your settings.php
file (replace www.example.com
):
if (isset($_ENV['PANTHEON_ENVIRONMENT']) && php_sapi_name() != 'cli') {
// Redirect to https://$primary_domain in the Live environment
if ($_ENV['PANTHEON_ENVIRONMENT'] === 'live') {
// Replace www.example.com with your registered domain name.
$primary_domain = 'www.example.com';
}
else {
// Redirect to HTTPS on every Pantheon environment.
$primary_domain = $_SERVER['HTTP_HOST'];
}
$requires_redirect = FALSE;
// Ensure the site is being served from the primary domain.
if ($_SERVER['HTTP_HOST'] != $primary_domain) {
$requires_redirect = TRUE;
}
// If you're not using HSTS in the pantheon.yml file, uncomment this next block.
// if (!isset($_SERVER['HTTP_USER_AGENT_HTTPS'])
// || $_SERVER['HTTP_USER_AGENT_HTTPS'] != 'ON') {
// $requires_redirect = TRUE;
// }
if ($requires_redirect === TRUE) {
// Name transaction "redirect" in New Relic for improved reporting (optional).
if (extension_loaded('newrelic')) {
newrelic_name_transaction("redirect");
}
header('HTTP/1.0 301 Moved Permanently');
header('Location: https://'. $primary_domain . $_SERVER['REQUEST_URI']);
exit();
}
// Drupal 8 Trusted Host Settings
if (is_array($settings)) {
$settings['trusted_host_patterns'] = array('^'. preg_quote($primary_domain) .'$');
}
}
Add the following to the end of your settings.php
file (replace www.example.com
):
if (isset($_ENV['PANTHEON_ENVIRONMENT']) && php_sapi_name() != 'cli') {
// Redirect to https://$primary_domain in the Live environment
if ($_ENV['PANTHEON_ENVIRONMENT'] === 'live') {
// Replace www.example.com with your registered domain name.
$primary_domain = 'www.example.com';
}
else {
// Redirect to HTTPS on every Pantheon environment.
$primary_domain = $_SERVER['HTTP_HOST'];
}
$requires_redirect = false;
// Ensure the site is being served from the primary domain.
if ($_SERVER['HTTP_HOST'] != $primary_domain) {
$requires_redirect = true;
}
// If you're not using HSTS in the pantheon.yml file, uncomment this next block.
// if (!isset($_SERVER['HTTP_USER_AGENT_HTTPS'])
// || $_SERVER['HTTP_USER_AGENT_HTTPS'] != 'ON') {
// $requires_redirect = true;
// }
if ($requires_redirect === true) {
// Name transaction "redirect" in New Relic for improved reporting (optional).
if (extension_loaded('newrelic')) {
newrelic_name_transaction("redirect");
}
header('HTTP/1.0 301 Moved Permanently');
header('Location: https://'. $primary_domain . $_SERVER['REQUEST_URI']);
exit();
}
}
For more redirect scenarios, see Configure Redirects.
Vanity Domains for Organizations
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
).
For details, see Vanity Domains.
Troubleshooting
Failed cache clears, search and replace, or Drush and WP-CLI operations
All redirect logic should include the php_sapi_name() != "cli"
conditional statement to see if WordPress or Drupal is running via the command line. Drush and WP-CLI are used by the platform for operations like cache clearing and search and replace, so it is important to only redirect web requests, otherwise the redirect will kill the PHP process before Drush or WP-CLI is executed, resulting in a silent failure:
[notice] Command: site.env -- 'drush <command>' [Exit: 1]
[error]
Infinite Redirect Loops
HTTP_X_FORWARDED_PROTO
Errors referencing too many redirects may be a result of using the $_SERVER['HTTP_X_FORWARDED_PROTO']
variable within redirect logic located in your site's wp-config.php
or settings.php
file.
Resolve this error by replacing the offending redirect logic with the recommended code samples in the above section and for your specific use case.
Modules and Plugins
Modules and plugins that support managing redirects in the Site Admin interface can produce redirect errors when repeating or conflicting with redirects managed via PHP in your site's configuration file. Some examples include:
WordPress plugins: Redirection, Quick Page/Post Redirect, Safe Redirect Manager, Simple 301 Redirects
Drupal modules: Language (when using URL detection), Securepages, Redirect
When troubleshooting a redirect loop, you may want to deactivate any module or plugin that may be providing its own redirect logic.
Mixed-mode Browser Warnings
Replace http://
in the site's database and configure your CMS to assume users are visiting via HTTPS and the site’s primary domain. Templates for example should reference HTTPS in absolute CSS and Javascript sources, even when accessed with HTTP.
Mixed Case DNS Is Not Supported
If you have your name server configured to use a mixed case domain, visitors might not be able to access your site.
Configure your DNS to accept an entirely lowercase domain to avoid this issue.
Test Domain Names Before DNS
You can modify your local hosts
file to validate domain-specific settings before DNS is in place.
Note that modifying the hosts
file usually requires administrative privileges from the OS.
The location of the hosts
file varies depending on your operating system:
- MacOS / Linux:
/etc/hosts
- Windows:
C:\\Windows\System32\Drivers\etc\hosts
Add lines to your operating system's hosts
file in the following format:
203.0.113.10 example.com
203.0.113.20 www.example.com
In the example above, replace the IP addresses with those provided by Pantheon, and the domains with your own.