Skip to main content
Log inGet free account

Connect a Domain Name

Learn how to connect your domain to your Pantheon-hosted site.

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

This section provides information on how to connect a bare domain and www domain to Pantheon's Live environment.

Note

Pantheon is not a domain registrar, and we do not offer DNS management as a service. To connect a custom domain to Pantheon, you need to register the domain with a third-party provider.

The steps below will guide you through the process of migrating a site onto Pantheon for the first time. If you are migrating a site already on Pantheon, follow the steps for relaunching an existing Pantheon site.

Connect Domain

  1. Access the Live environment in your Pantheon Site Dashboard.

  2. Navigate to the Domains / HTTPS page.

  3. Enter the www domain (for example, www.example.com), then click Connect Domain. You'll enter the bare domain (without the www) in a later step.

  4. 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.

  5. Click Verify Ownership to confirm.

    Note

    Sites associated with Diamond or Platinum workspaces have the option to skip this step. For details, see this related FAQ.

    It can 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 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.

  6. Open a new tab or browser window, and copy the Required Values to your DNS provider. If you see:

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

    Wait one minute, then refresh the page.

  7. Click Back to Domains/HTTPS.

  8. Select Connect Domain and enter the bare domain (for example, example.com, and then click Connect Domain.

Existing Sites

Avoid HTTPS Interruption

Sites can pre-provision certificates and avoid HTTPS service interruption by verifying ownership of the domain.

To pre-provision HTTPS, Certification Authority Authorization (CAA) records must either:

  • Not exist for the domain and its parent domains, OR
  • Authorize Let's Encrypt
Warning

Skipping this step will result in service interruption for existing sites that require or expect HTTPS. If you skip this step, HTTPS will be available within an hour after DNS routes to Pantheon.

After you begin this process, you have:

  • 7 days to complete the challenge response. If the challenge is not completed in that time frame, you will see a 0006 error. To resolve the error, you would just need to remove then re-add the custom domain.
  • 30 days to adjust DNS values.

  1. Navigate to the Live environment in your Pantheon Site Dashboard.

  2. Select the Domains / HTTPS page.

  3. Select Details next to the bare domain.

  4. Click Download File.

  5. Serve the file from your existing live site. Drupal users can use the Let's Encrypt Challenge module to easily serve the contents of the challenge file.

    Note

    The validation file to pre-provision HTTPS must be accessible over HTTP, not just HTTPS. A redirect from HTTP to HTTPS will work, but if a request over HTTP returns a 404, for example, the validation will fail.

    A misconfiguration of the validation file invalidates these records. You will receive an error message if the DNS validation fails.

  6. Return to the Site Dashboard and refresh the Domains / HTTPS page.

Your domain's HTTPS certificate(s) will begin to generate automatically after your verify domain ownership. The certificate will automatically deploy to Pantheon’s Global CDN within an hour.

You can switch DNS destinations from your existing site to your new Pantheon site without HTTPS interruption when your certificate is ready.

Maintenance Window

You will not be able to pre-provision HTTPS to prevent service interruption if you can't prove domain ownership (for example, WP Engine blocks serving the required challenge file). We recommend completing the next section (Configure DNS) during a planned maintenance window lasting up to one hour. HTTPS will be available for the domain within an hour of pointing DNS to Pantheon.

More Resources