Skip to main content
Log inGet free account
Last Reviewed: September 03, 2024

Relaunch Existing Pantheon Site

Take a new site live by moving custom domains from one Site Dashboard to another, with minimal HTTPS interruptions.

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

Sites are considered to have launched on Pantheon after traffic is routed through a custom domain(s). Relaunching a previously launched site is done by rerouting traffic from the existing Site Dashboard to an entirely new Site Dashboard.

Note

The relaunch process applies exclusively to live sites already hosted on Pantheon. For more information on launching a site that is not already on the Pantheon platform, refer to Launch Essentials.

Prepare for Relaunch

Expected Disruption

During this procedure, there will be a brief period of disruption where requests to the custom domain will serve a 404 Unknown Site error.

The 404 Unknown Site error will be returned as soon as the custom domain is removed from the old site, and once connected to the new site dashboard with ownership verified, requests will immediately start to return a 200 OK status once again. Requests will start routing to the new site dashboard after the TTL for the DNS records expires.

Due to the brief period of disruption when a 404 Unknown Site error is returned to site visitors, we recommend planning a relaunch based on historical traffic patterns for the given site and scheduling the switch during off-peak hours.

When following the below procedure for relaunch, the duration of the disruption should be low, usually less than a few minutes.

Before You Begin:

  1. Log in to the new Pantheon Site Dashboard as an Admin, Team Member, or Privileged User.

  2. Open a new tab for the old Pantheon Site Dashboard.

  3. In another tab, log in to the domain's DNS service provider (e.g., Cloudflare, Amazon Route 53, etc.).

  4. Examine existing records pointing to Pantheon.

    Standard DNS configurations utilize the following for both the bare domain (example.com) and any subdomains (like www):

    • Two AAAA records pointing to unique IPv6 addresses
    • One A record pointing to an IPv4 address
    Note

    For subdomains that are using Custom Certificates, use the bare domain's recommended A/AAAA records instead of using CNAME records.

  5. Set the TTL of existing DNS records as low as possible to minimize the impact of upcoming DNS changes

    Learn More

    Time to Live (TTL)

    The TTL dictates the lifespan of a DNS record; a shorter time means less time to wait until the changes go into effect. TTLs are always set in seconds with a few common ones being 86400 (24 hours), 43200 (12 hours), and 3600 (1 hour).

    When you make a change to the TTL of an existing record, you need to wait for the old TTL time to pass - that is, if it had been set to 86400, you would need to wait a full 24 hours for the new setting to begin propagating everywhere.

  6. In your terminal, use dig to obtain the new site's A and AAAA records:

    dig +short live-site-name.pantheonsite.io
dig +short AAAA live-site-name.pantheonsite.io

    You can also use the Google web implementation of dig.

    Note

    The dig command will not provide the correct DNS information for domains using Custom Certificates. If you are using a Custom Certificate, DNS records should not be changed.

Roles & Permissions

The permission to manage billing and plans is granted only to the role of Site Owner / Workspace Administrators. Other roles do not have access as described on this page.

Note

If you need to assume site and billing ownership, the current Site Owner must transfer it to you directly.

To retain Preferred Pricing an updated invitation to pay must be sent from the Supporting Workspace for the new site.

The new Site Plan will be billed immediately.

Relaunch Procedure

For a fast, smooth relaunch, consider having two browser tabs open, one with the old Site Dashboard, and one with the new.

  1. In the new Site Dashboard, upgrade the site from free to a paid plan.

  2. In the old Site Dashboard, remove the custom domain affected by the relaunch:

    Live > Domains / HTTPS > Details > Remove Domain

  3. In the new Site Dashboard, connect the custom domain affected by the relaunch:

    Live > Domains / HTTPS > Connect Domain

  4. Complete domain validation by adding a new DNS TXT record or by uploading a file to a specific URL, then click Verify Ownership:

    Domain validation prompt

  5. From the DNS hosting service (not Pantheon), replace values in DNS records pointed to Pantheon with new values provided in the Site Dashboard.

    Standard DNS configurations utilize the following for both the bare domain (example.com) and any subdomains (like www):

    • Two AAAA records pointing to unique IPv6 addresses
    • One A record pointing to an IPv4 address

  6. Wait for TTL to expire.

  7. Test and confirm that the new site is accessible via the custom domain over HTTPS (e.g., https://www.example.com/).

  8. Repeat steps 2-6 above for each affected domain. Note www.example.com and example.com are different domains.

  9. In the new Site Dashboard, standardize traffic for the primary domain.

  10. In the old Site Dashboard, downgrade the site from a paid plan to Sandbox.

  11. In the old Site Dashboard, remove the existing card as a payment method for the site. If you're a contract customer, you can skip this step.

Frequently Asked Questions

Why is this process needed?

Custom domains can only be attached to a single site environment at any given time. For scenarios where you want to move a custom domain to a new site, you must first remove the custom domain before it may be re-connected elsewhere on Pantheon.

Will my site experience downtime?

If you follow the process outlined above, downtime will be minimal.

Once you complete step 2 above, the domain is unreachable until you complete the relaunch procedure. We recommend that you open the new site's Dashboard in another browser tab, then copy and paste the domain name from the old site to the new for a quick transition. You can also use Terminus to run the two commands in immediate succession.

Set the TTL as low as possible (most DNS providers set a lower limit of 300 seconds, or 5 minutes). Having a long TTL on the changing DNS records increases how long you have to wait until you start getting routed to the new site dashboard.

Finally, the relaunch procedure should be done as a single process, as quickly as possible. Once you remove a domain from a site, you must quickly re-connect it to the new site dashboard and update DNS to mitigate disruption.

Why do I need to lower my DNS TTL?

DNS records propagate across many different servers and aren't refreshed until the record on each server expires. This means that a record with a 24 hour TTL can take several days to be updated across DNS servers globally. We recommend lowering the TTL before a site relaunch.

Best practices during normal operation (e.g. not during a site relaunch) suggest a longer TTL (for example, 86400 seconds, or one day) because a long TTL helps reduce the number of DNS lookups that visitors' browsers need to perform. During a site relaunch, a long TTL can extend the time frame that return visitors are pointed to the old site, while new visitors are pointed to the new site.

When do I switch the site from the old site to the new one?

As soon as the TTL expires after making the DNS changes (after step 5 above), visitors to your domain will start to see the new site. For some time afterwards, your visitors may still see the new site with the old site's HTTPS certificate, that will be spun down by the platform automatically once the new certification is provisioned and deployed.

More Resources