Upgrading

Introduction

If your site is already using Edge Delivery Services and you wish to upgrade to DA from SharePoint or Google Drive, you have a couple of options on how to upgrade. The path you choose is largely dependent on your QA practices. Speaking of QA, you should plan for an upgrade to DA to be about 90% QA, 5% development, and 5% operations. The goal is to ensure with 100% confidence that your new DA-based site is exactly like the existing SP or GD-based site.

If you want a developer-centric view into the upgrade process including differences you should be aware of, please see our developer guide on upgrading.

Approaches

There are two approaches to upgrading to DA:

  1. fstab swap - Change the fstab of the original repo w/o involving your CDN team.
  2. origin swap - Change your origin at the CDN layer to point to your new DA-based repo.

Both options have their plusses and minuses. Both options require a new project (repoless or full repo) to be made. In the case of an fstab swap, the project is temporary. In the case of an origin swap, the new project replaces the old. Both methods also allow you to work in parallel on each project.

FStab Swap

Pros

  1. Requires no involve from a CDN / web operations team.
  2. Keep your existing repo name.
  3. No re-training creators on new domains (mysite--myorg.aem.page vs da-mysite--myorg.aem.page)

Cons

  1. Impossible to spoof test before go-live w/ the final origin.
  2. Code must be carefully scrubbed for references to different origins.
  3. Any code on the da repo will need to be ported back and done in a way that is forwards and backwards compatible with the new and old content.

Origin Swap

Pros

  1. Ability to spoof test before go-live.
  2. Ability to QA across different phases (dev, stage, prod) before moving to the next phase.
  3. No need to sync code changes back to original repo.

Cons

  1. A typical convention is to make a new repo with a "da-" attached to the existing repo name. You would then have this prefix for your site going forward which can feel a bit redundant and un-clean.
  2. Code changes in the original repo must be brought forward.

Approach recommendation

If you have the ability to spoof test or change your CDN origins before go-live, an origin swap is the safest path to upgrade. It allows you to change each part of your CDN and gain confidence over the lifecycle of your CDN stack:

  1. Point CDN stage to new repo.
  2. Test & QA
  3. Configure CDN prod for new repo (via staging network / spoof test)
  4. Test & QA.
  5. Push staged production config to production.

If you do not have the ability to do any of the above, an fstab swap does have some advantages. Because Edge Delivery Services does not allow different content sources for different branches, when you change your fstab, it changes everywhere.

At the expense of extra work, if the `da-` prefix bothers you post go-live, you can do an origin swap & an fstab swap:

  1. Go-live w/ new `da-` repo.
  2. Change old repo to point to DA-based content.
  3. Change origin back to original repo.

Comprehensive upgrade strategy

Below you will find the steps to upgrade a site to DA. We will use the origin swap method w/ extensive QA. Where time estimates are known, we have added them.

  1. Developer - Fork the existing site and prefix the repo name with da-. You can also create a repoless project, just know that you would need to make any code changes in the source repo. - 5-10 minutes
  2. Developer - Make some dummy content to ensure basic functions work. - 2-5 minutes
  3. Developer - Run the AEM bulk status command to get a list of docs, sheets, fragments, videos, pdfs, svgs, and redirects. - 5-10 minutes
  4. Developer - Run an import of the result from the AEM bulk status result. - 1 minute per 1,000 pieces of content.
  5. Developer - Import redirects, .helix/config as these are not in the status result. 5-10 minutes
  6. Developer - Make note of date & time of this import.
  7. Developer - Preview and publish all content. - 3s per 10 pieces of content.
  8. Developer / QA engineer - Smoke test high profile content on new repo.
  9. Developer - Fix any known issues from smoke test.
  10. Content QA - Full regression / validate new repo content. Any bugs should be checked against original repo to ensure these are not pre-existing issues.
  11. Content author - Fix issues flagged by content QA.
  12. SEO - Validate sitemap parity with original repo.
  13. Web Ops (CDN team) - Point CDN stage to new origin.
  14. Content QA / QA Eng - Full regression test against CDN stage.
  15. Developer - Fix any new issues from CDN stage testing.
  16. Web Ops (CDN team) - Setup spoof test config for production.
  17. Developer / content author - Perform delta import (& publish) to import anything that was published after the initial import.
  18. Everyone (PM, Con QA, QA eng, SEO, dev) - Point /etc/hosts to staged production config & test.
  19. Web Ops (CDN team) - Push staged production config live.
  20. There is no step 20.

Known issues

  1. Edge Delivery Services limits markup sources (i.e. DA & UE) to only have 10MB images. If you have very large images in SharePoint or Google Drive, you may run into errors when trying to preview.
  2. Edge Delivery Services limits markup sources to only allow 100 images per document. If you have more than 100, you may run into errors when trying to preview.
  3. If your site has cross origin protections, you may need to use a browser extension to import your content. Please reach out to the DA team for assistance.
  4. There's a small difference in the HTML that Edge Delivery renders from markup sources. This manifests as an extra paragraph tag in lists. You may need to change your blocks to accommodate this difference.
  5. Query Indexes from markup sources are strongly typed. If you have arrays of content or rely on certain date formats, you may need to change your blocks to account for this difference.