Upgrading from Craft 2 to Craft 3: Setup & Planning

Technically possible? Budget approved? Great. You've made it through the first step (Upgrading from Craft 2 to Craft 3: Should I update?) and you're moving forward. Time to take a few steps so that you’re happier when something goes wrong during the migration.

Custom development and migrations #

In the case you will need to do any custom development or data migrations to get upgraded, you may want to jump ahead to step 6 and plan those out specifically. While, as far as complexity goes, I’ve placed the Custom Development section toward the end of these notes, practically speaking, that development is probably going to have to happen first so that it is ready when you are performing the upgrade process.

Create a few folders #

As a migration often involves troubleshooting where things were and where things are going, I recommend creating two folders alongside your main website folder so that you have a staging area and can reference your Craft 2 site and Craft 3 site side by side during the migration.

Folder Purpose
website.com/ your main site / git repository
website.com-craft3/ staging area for initial Craft 3 site
website.com-craft2/ a copy of the fully upgraded website.com Craft 2 site in case you need to reference anything after you overwrite website.com with website.com-craft3

These secondary folders don’t need to be in your repository, they’ll just be temporary until you’ve finished the migration. It is possible to refer to these updates by moving forward and backward in your git history though I find it easier to have the separate folders so I can easily copy files from the old Craft 2 site to the new Craft 3 site and reference anything that I may need to from each install along the way.

The content migration #

Take some time up front to determine how you expect to deploy the updated Craft 3 site.

On many sites, content editors will need to continue making updates through part of the time you spend on the migration and this will lead to the current production database and the new migrated database getting out of sync. Depending on the needs of your project, the workflow around the database updates can take several different forms:

  1. The Long Content Freeze
    For smaller sites, informational sites, and sites without user-created content, you can often agree (along with whoever else edits the site) to not make changes to the production database while you perform the Craft 3 updates. As these types of sites have less frequent changes, you can often agree to do this for a couple days or a week and give yourself plenty of room to perform the updates needed. Once you complete the migration you can upload the new database and replace the old one as you deploy your new files.
  2. The Short Content Freeze
    For sites that have more regular updates but where you also have access to the whole team making the changes (i.e. no user-generated content), it may be harder to ask people to stop making changes for a long period of time but as this is a major upgrade, you can likely agree to a 1-day window for the migration where no changes are made to the website. If a 1-day window during business hours doesn’t work, you may have to discuss what type of window could work outside of normal business hours. In these cases, you can perform your migration on a representative database in a local development environment to work through any issues you might run into along the way and re-run the migration on the live database during the content freeze. This process requires a bit more planning as any database changes you make during the initial migration process (take good notes!) will need to be made a second time when you run the final migration on the production database. We’ll discuss considerations on how to plan your workflow for this type of migration throughout this article.
  3. The Conditional Content Freeze
    For sites with frequent updates or user-generated content you may run into tricker scenarios where you'll be unable to coordinate directly with who is updating content. These cases will likely need to be dealt with on a case by case basis as businesses and communities can vary in their expectations. Some techniques for this scenario include making a public announcement about a maintenance window, disabling certain features on the site for a period of time so content isn’t updated when you don’t want it to be, and preparing programmatic migrations to ensure you can move quickly in the window of time you have to make updates.

Don't miss any Craft tips, tricks, and community updates