Skip to main content
Last Reviewed: September 08, 2020

Relaunch Existing Pantheon Site

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


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.

Info:
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

  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
    Info:
    Note

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

  5. Lower the TTL of existing DNS records 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.

    Info:
    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.

Info:
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

    Warning:
    Warning

    Do not update DNS yet. The Site Dashboard instructs you to configure DNS after connecting the domain, however for this relaunch procedure you should not change record values until instructed in step 7 below.

    Once you make this change, traffic will be routed to the new site. However, if you do not complete the rest of the steps as outlined here, you may run into cases where the new site has an invalid HTTPS certificate.

  4. In the Live environment tab of the Site Dashboard for the old site, click Clear Caches.

  5. Repeat on the Live environment of the new site.

  6. Wait for HTTPS to provision for the newly connected domains:

    Live > Domains / HTTPS > Details

    HTTPS
    
    Let’s Encrypt certificate deployed to Pantheon’s Global CDN. Certificate renews automatically with no additional cost.

    This process typically takes about an hour.

  7. 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
  8. Test and confirm that the new site is accessible via the custom domain over HTTPS (e.g., https://www.example.com/).

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

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

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

  12. 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?

If you remove domains from the old site and add them to the new site, HTTPS certificates will not be immediately available for the new site. This can cause security warnings for client browsers, and potentially affect processes that require a secure connection (like commerce transactions).

This procedure temporarily uses the existing HTTPS certificate until the new one is generated and ready for use.

Will my site experience downtime?

If you follow the process outlined above, downtime will be minimal and depends on the TTL configuration.

Once you complete step 2 above, the domain is unreachable until you add it to a new site in step 3. 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.

To minimize the chance to HTTPS certificate errors, 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 the chance of HTTPS Certificate errors during the transition.

Finally, the relaunch procedure should be done as a single process, as quickly as possible. Once you remove a domain from a site, the existing HTTPS certificate will be removed within a few hours and the new site's HTTPS certificate will be available within an hour. Be ready to update your DNS records as soon as the new certificate is available to minimize the chance of visitors encountering an invalid HTTPS certificate.

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 you complete step 3, visitors to your domain will see the new site. Until step 5 is complete and the DNS is fully propagated, your visitors may still see the new site with the old site's HTTPS certificate, that will go offline shortly.

More Resources