Upgrading from Craft 2 to Craft 3: A Fresh Install
Similar to Stage 2, I'll begin Stage 3 focusing on Craft 3 and Craft 3 alone.
Create a separate folder website.com-craft3/ and follow the Craft 3 Upgrade instructions: Upgrading from Craft 2. I won't go into them in detail here but at the top level you'll start by installing a fresh version of Craft.
I like to use the Barrel Strength Craft starter project:
composer create-project barrelstrength/craft-master <Path>
Whatever you choose as your default project, be sure to update your .gitignore to reflect any project-specific considerations in the new folder structure. The default .gitignore excludes the vendor/ folder, which is a change that may also require an update to your devops and deployment workflows, so if you're not ready or interested in changing those workflows, you may want to remove that line and include the vendor/ folder so you can track all of your changes in the repository.
The upgrade documentation details a solid list of files that you may want to copy over from your Craft 2 to your Craft 3 site. I've listed the key files mentioned in the docs in the table below:
| Craft 2 | Craft 3 | Notes |
|---|---|---|
| craft/config/general.php | config/general.php | |
| craft/config/license.key | config/license.key | |
| craft/config/redactor/ | config/redactor/ | Custom Redactor config files. See gotchas on syntax in the Craft 3 changes docs. |
| craft/storage/rebrand/ | storage/rebrand/ | Custom login page logo and site icon files |
| craft/storage/userphotos/ | storage/userphotos/ | Copy to new project’s directory. You can customize the location of this now in Assets. |
| craft/templates/ | templates/ | |
| public/index.php | web/index.php | Copy any changes you made |
| public/ | web/ | Copy any other custom web accessible files |
| / | / | Copy any other files above web root |
This is one of the stages where it's nice to have two folders. Pull up two file browsers side by side and copy the relevant files from the Craft 2 site to the Craft 3 site.
Update your repository to use Craft 3
At this point, you have two separate projects in two separate folders:
- Your upgraded Craft 2 website in your git repository
- Your freshly installed Craft 3 website where you've copied over all of your files and customizations
Time to bring it all together.
For the following updates, I prefer to branch off of the latest, updated master branch: feature/craft3-migration. This lets me easily trash the branch and start over if I get curious and experimental or if things blow up and also lets me maintain a standard project workflow if anything comes up on the current website during the migration process.
Instead of merging your Craft 3 changes into you Craft 2 master branch, consider bringing your two projects together in two, atomic commits. While git is great at tracking history and file changes what you are about to do is almost entirely meaningless as far as diffing and comparing files goes. You're changing the entire folder structure and the files that change are not going to be tracked in a way that you can easily compare them in your project history.
For the first upgrade commit delete all of the files from the Craft 2 site from the repository. Everything except the .git/ directory. For the second commit, copy in all of the files from the Craft 3 project you just created.
| Commit Message | Database Backup |
|---|---|
| Deleted Craft 2 website files | website.com-c2-pre-upgrade.sql |
| Added Craft 3 website files | website.com-c3-initial-upgrade.sql (after you run the update) |
This gives you two clear commits that you can revert back to in the project history if you need to re-run the Craft 2 upgrade or explore additional scenarios with your Craft 3 database after the upgrade.
Now that the repository is ready, we can move on to the database migration.
This article is part of a series:
- Evaluation, Setup, and Planning
- Update Everything on Craft 2
- A Fresh Craft 3 Install
- Database Migration (coming soon)
- Template Migration (coming soon)
- Custom Plugins & Modules (coming soon)
- Deploy & Maintain (coming soon)