How To Upgrade Craft CMS

Upgrading Craft CMS

Overview of Craft CMS

Craft CMS is a flexible, user-friendly content management system that developers use to build custom sites and web applications. Unlike other content management systems, Craft gives developers complete control over the front and back end code.

Some of the key features of Craft CMS include:

• Intuitive control panel - The control panel provides a clean, simple interface for managing content and site settings.

• Flexible content modeling - Craft allows you to create custom content types and fields to match your content strategy. You're not limited to pre-defined content models.

• Native GUIs for managing content - Craft uses native drag and drop interfaces for organizing content like entries, assets, and users. This is more intuitive than managing content in a database.

• Developer-friendly templating - Craft uses Twig templating which is easy for developers to work with and extend. It's much more powerful than restrictive WYSIWYG editors.

• Robust plugin ecosystem - Craft has hundreds of free and paid plugins that add advanced functionality like ecommerce, SEO, social media integration and more that can be accessed from the Craft Plugin store.

• Headless CMS capabilities - Craft can be configured as a headless CMS to output structured content for use in different platforms.

Craft provides the flexibility and customization options developers need to build fully custom sites, while maintaining a user-friendly interface.

Importance of Upgrading Craft CMS

It is important to keep your Craft CMS core, site and plugins up-to-date in order to get the latest features, security patches, and performance improvements.

Here are some of the key benefits of upgrading:

• Access to new features - Upgrading your Craft install gives you access to handy new features that improve the authoring experience in the control panel. For example, the Live Preview editor added the ability to preview draft entry changes.

• Performance enhancements - Upgrades often include under-the-hood performance tweaks that can make your site load faster for users. Things like caching improvements and optimised database queries.

• Security patches - Core Craft updates frequently patch vulnerabilities that could put your site at risk if left unpatched. Keeping your site updated is critical.

• Bug fixes - Bug fix updates resolve issues that may be causing glitches or problems on your site. Upgrading eliminates any bugs.

• Continued support - To get help from the Craft community and developers, you need to stay updated. Fall too far behind and you lose access to support.

Neglecting to upgrade your Craft install means you miss out on all of these ongoing improvements over time.

Risks of Outdated Craft CMS

Running outdated versions of Craft CMS can introduce security risks, lead to site issues, and cause you to lose access to support and plugins:

• Security vulnerabilities - Every Craft release contains security patches for vulnerabilities that were discovered. If you don't upgrade, that leaves holes hackers could exploit to compromise your site.

• Site performance problems - Outdated Craft versions may have performance issues that slow down your site for users. Missing optimisations and caching improvements can degrade site speed over time.

• Buggy behaviour and glitches - Bugs that were fixed in later versions will persist on your site if not upgraded. This can introduce all sorts of glitches and problems on the front and backend.

• Loss of access to support - The Craft community and developers only provide support for current and recent Craft versions. If you fall too far behind, you're on your own.

• Plugin incompatibility - Great plugins stop supporting older Craft versions. If you don't upgrade Craft, you'll lose access to newer plugin versions with useful features.

• Limited control panel functionality - New control panel and CMS features only work on updated Craft installs. Your content team will miss out on helpful functionality.

The risks of an outdated install pile up over time. Small glitches turn into major headaches. The safety net of support disappears. Running the latest version of Craft CMS avoids these pitfalls and keeps your site in top shape.

Preparing for a Craft CMS Upgrade

Backing Up Your Site

Before attempting any Craft CMS upgrade, it is absolutely critical that you properly back up your entire site. A failed upgrade can corrupt your database, so having a full backup allows you to restore everything if needed.

At a minimum, you should perform a manual database backup through phpMyAdmin or a similar tool. Export the full database so you have all Craft CMS data like entries, assets, users, fields, etc. Back up any custom tables or data sources as well.

You'll also want to back up your actual Craft CMS files and templates. Use Git or another version control system to commit your code changes. Or manually zip your /craft files and /templates folders for safekeeping. This covers all plugins and template customisations.

For added protection, enable Craft's built-in database backups that run on a schedule. Then if the upgrade goes sideways, you can restore today's backup rather than a stale manual one.

Perform a manual FTP/SFTP backup of all uploaded assets too.

Having redundant backups through both automated systems and manual exports gives you maximum assurance. Test restoring from backups to confirm the process works smoothly.

Testing Upgrades in Staging

Never upgrade Craft CMS directly in your live production environment. The safest approach is to create a staging clone of your site and test the upgrade there first.

Use a Git branch, separate subdirectory, or a service like ServerPilot to easily clone your production site. Ensure staging is an exact 1:1 copy before upgrading.

In staging, walk through the full Craft upgrade process step-by-step:

• Update core Craft CMS via the control panel or Composer

• Run all database migrations and rebuild search indexes

• Update plugins one-by-one, performing a Git commit after each

• Test front-end and back-end site functionality is intact

• Identify any breaking changes or compatibility issues

This staging testing process lets you resolve any upgrade issues in an isolated environment.

Once everything is confirmed working properly, you can safely upgrade production and be confident the same outcome.

Testing upgrades without affecting the live site is a best practice for major version bumps like Craft 2 to 3. But smaller incremental upgrades should go through staging as well.

Checking Plugin Compatibility

With any Craft CMS upgrade, be sure to check that your installed plugins are compatible with the new Craft version. Otherwise, you may break your site's functionality.

Many plugins will indicate Craft CMS compatibility in the plugin documentation or readme file. But always check the latest plugin release notes for the most up-to-date compatibility info.

For paid plugins, the developer will indicate which Craft versions are supported. If needed, contact their support team regarding compatibility or timelines for supporting the new Craft release.

For free open source plugins, you may need to test compatibility yourself in your staging environment. Upgrade Craft core first, then incrementally update each plugin while verifying nothing breaks after each one.

In some cases, you may need to wait for the plugin developer to officially support the Craft version before upgrading. Pinning to the last compatible release lets you safely upgrade Craft core and other plugins in the meantime.

Planning ahead and checking plugin compatibility helps avoid suddenly losing important site functionality after a Craft upgrade. Always have a rollback plan in case an upgrade does not go smoothly right away. With proper staging testing and backups, Craft CMS upgrades can deploy seamlessly.

Downloading and Uploading New Craft CMS Version

Determining Current and Target Versions

Before downloading and upgrading Craft CMS, you need to determine both your current Craft version and the target version you want to upgrade to.

The easiest way to check your current version is by logging into the Craft control panel and looking at the footer. It will explicitly state the installed version number.

You can also look at the /craft/app/Info.php file and check the 'version' value near the top. Or view the /vendor/craftcms/cms/composer.json file to see the Craft version constraint.

For the target upgrade version, review Craft's changelog to decide which incremental version to jump to. Avoid skipping multiple minor point releases to reduce compatibility issues.

Craft 3.1 to Craft 3.2 is a minor upgrade. Craft 3.0 to Craft 3.3 would be a riskier major upgrade spanning multiple versions.

Check the compatibility table in the Craft docs to pick a target version that matches your needs. Identify plugins that require a certain minimum Craft version and factor that in as well.

Downloading Latest Craft CMS

Once you've decided on the new Craft CMS version, head to your Craft account dashboard to download it.

Go to the "My Downloads" section and find the Craft version you want under CMS installs. Use your license key to unlock the download options.

For a simple upgrade, the .zip file is recommended. Expand this on your local machine then transfer and replace the files on your server.

Alternatively, you can grab the .tar.gz tarball file if you prefer that format. There are also links for downloading via CLI tools like Curl and Wget if you have command line access.

Be sure to download the complete Craft installation files, not just the updater zip. The full install contains all the core files needed to replace your current version.

Save the download somewhere easily accessible until you're ready to replace the CMS files on your server.

Replacing Craft CMS System Files

Once you've downloaded the latest Craft CMS version, it's time to replace the system files on your server.

First, use FTP/SFTP to upload the new Craft /app, /config, and /vendor folders from the download, overwriting your existing files. Adjust ownership and permissions on these replaced files accordingly.

For non-breaking updates, you can optionally just replace the /app folder to save time. But major version upgrades should replace all core Craft files.

If uploaded via zip, extract the archives locally then upload the expanded files/folders. Don't just upload the .zip to your web root.

Double check the new Craft version number displayed in the control panel footer or Info.php file to confirm the files updated successfully.

With the core system files replaced, you're ready to update the database through the control panel and complete the Craft CMS upgrade. Take your time and take backups before proceeding!

Updating Database and Configurations

Running Database Migrations

After replacing the Craft CMS system files, you need to run database migrations to update the database schema.

From the command line, run:

./craft migrate/all

This will run all new migrations needed to sync the database with the upgraded Craft codebase.

Review the logs for any errors or issues. Database migrations can sometimes fail if custom plugins have introduced inconsistent schemas. Adjust plugin code or run individual migrations if needed.

For major version upgrades like Craft 2 to Craft 3, the migration process can take a while to fully update the database structure. Be patient and take backups in case you need to roll back.

On a production site, temporarily put the site in maintenance mode if needed to prevent activity during long migrations.

Database migrations are essential to avoid inconsistencies and errors after a Craft CMS upgrade. Don't skip this step!

Reviewing Config Settings

Upgrades often add new config settings or change how existing settings work. So review your Craft config files after upgrading.

Check for any new config settings related to new features and make sure they are set as needed. For example, Craft 3.1 added the 'optimizeImages' and 'transformGif' image handling settings.

Ensure credentials and environment variables like database connections are still valid. Craft upgrades can sometimes change the expected config format.

Review email settings, queues, caching configuration, file system paths, and logging settings as well. Update any settings impacted by deprecated options or functionality.

For config stored in the database, review settings in the control panel like users, fields, sections, and categories.

An upgrade is a good time for a full audit of config and credentials. Update anything outdated or incompatible with the latest Craft release.

Adjusting File Permissions

The upgraded Craft CMS files may have different permission requirements than your previous version.

Review the recommended permission guidelines in the Craft docs. Common folders like /storage, /vendor, and /config typically need to be writable.

Update the ownership and permissions using chown and chmod as needed. For example:

chown -R www-data:www-data /path/to/craft

find /path/to/craft -type f -exec chmod 664 {} \;

find /path/to/craft -type d -exec chmod 775 {} \;

Test front-end and control panel functionality after adjusting permissions. Logged out users should still be able to view pages.

Set the most restrictive permissions possible that don't break functionality. Tight permissions enhance security on your upgraded Craft install.

With the new Craft CMS version installed, migrations and configurations complete, take one final backup before enabling the site live. Upgrade plugins and test rigorously before launch.

Updating Plugins and Frontend

Updating Compatible Plugins

Once Craft CMS core is upgraded, the next step is updating any compatible plugins to their latest versions.

In the control panel, visit Settings → Plugins and click "Update all plugins". This will automatically update plugins with full compatibility to the new Craft version.

Review plugin release notes first to catch any compatibility caveats like required config changes. For paid plugins, reach out to the developer for upgrade advice.

For plugins not set to auto-update, manually download the latest version that supports your Craft CMS version. Unzip and replace the plugin files on the server.

Stagger plugin updates if needed rather than updating everything simultaneously. Test functionality after each one to pinpoint any problem plugins.

Enable auto-updates for low-risk plugins to simplify maintenance going forward. But disable auto-updates for critical plugins until compatibility is proven.

Keeping your plugins updated along with Craft core is key for avoiding issues. Subscribe to plugin developer newsletters for upgrade announcements.

Fixing Incompatible Plugins

Some plugins may not yet support the new Craft CMS version you've upgraded to. There are a few solutions for this:

• If it's a critical plugin, roll back Craft core to the last compatible version until the plugin releases an update.

• For paid plugins, ask the developer if they offer a pre-release beta version with support for the Craft upgrade.

• Check if there is a suitable alternative plugin that already supports the Craft version.

• For open source plugins, you may be able to patch compatibility issues yourself if you're comfortable with development.

• In some cases, unused plugins can simply be disabled rather than fixing or replacing them.

Refer to the plugin documentation and Craft's developer docs for help troubleshooting and patching plugins during upgrades.

Clearing Caches and Assets

After updating Craft and plugins, be sure to clear all caches to avoid stale data:

In the control panel, go to Utilities → Clear Caches and clear all caches. Click "Clear it" to purge memcache, redis etc.

Clear your Craft-specific plugin caches like SEOmatic, Sprout Caching, etc.

Clear opcode caches like APCu or Redis via CLI or hosting control panel.

Clear your frontend caches like Varnish or Fastly as the final step. Purge all cached pages/assets to show updated content.

For asset volumes like S3, also clear out any old generated asset transforms, image versions, and thumbnails. They may not be compatible with the upgraded Image service in Craft.

Hard refreshing the front-end and control panel will bypass any lingering browser caches as well.

With fresh caches and assets, test the site thoroughly to catch any lingering upgrade issues before re-indexing and going live.

Testing and Securing the Upgraded Site

Verifying Frontend and Backend

Before launching your Craft CMS upgrade, thoroughly test all frontend and backend functionality to catch any lingering issues.

From the front-end, check:

• Site pages render and display correctly across all templates

• Site content, entries, and assets pull in properly

• Forms submit successfully and emails send

• Site performance and page speeds are acceptable

In the control panel, verify:

• Can log in and access all different user roles

• Entries, assets, etc are editable and savable

• Plugins are running without errors

• Automated tasks like queue jobs function properly

• New Craft features work as expected

Click around all site pages, test workflows, and ensure things look and work as intended.

Spot check previous functionality that may have been impacted by the upgrade. Try breaking things to test error handling.

Securing Access During Upgrade

To reduce risk of issues during the upgrade process, take steps to limit access and activity:

• Enable maintenance mode to prevent public access to the front-end as you test.

• Temporarily disable new user registration so new accounts aren't created mid-upgrade.

• Avoid CMS changes via API or Live Preview to reduce conflicts.

• Schedule the upgrade during periods of low site traffic and activity.

• For big upgrades, clone the site to a staging or dev environment and upgrade there first.

• Backup the site right before beginning the upgrade steps.

• Clear all caches ahead of time and after finishing the upgrade.

With less moving pieces in play, it's easier to isolate and resolve any upgrade problems. Take it slow, do changes incrementally, and avoid rushing.

Reindexing Search Indexes

After fully upgrading, rebuilding Craft's search indexes will sync them to the new data structure:

In the control panel, go to Utilities → Rebuild Search Indexes. Check all indexes then click Submit.

For large indexes, opt to queue the reindexing jobs to run in the background and avoid timeouts.

Monitor the status of the indexing either via the control panel or queue log files. Indexing can take a while for big sites.

After indexes finish rebuilding, test front-end and control panel searches. Verify keywords surface the expected entries and content.

Tweak search settings or update queries if certain content is no longer found. Relevant results rely on fresh indexes.

With core functionality tested and no major issues, the upgraded Craft site should be ready for launch! Update sitemaps, clear public caches again, and inform users of changes.

Troubleshooting Upgrade Issues

Debugging and Fixing Errors

Despite best efforts, you may encounter problems after upgrading Craft CMS - but there are solutions for debugging and fixing common errors:

• Review logs like craft.log, phperrors.log, queue logs to pinpoint the source of any PHP errors, exceptions, or migration failures.

• For migration issues, try running individual failed migrations manually. Adjust plugin code causing schema conflicts.

• If a plugin is causing errors, disable it to isolate the problem. Revert the plugin update if needed.

• For major upgrade issues, be ready to revert the full Craft upgrade by restoring backups of files and database from right before upgrading.

• Search Craft's GitHub issues and Stack Exchange for similar upgrade errors. Chances are someone else already solved it.

• As a last resort, reach out to the Craft CMS support team if core Craft is the issue. For plugins, contact the developer support.

Following errors down the stack trace while methodically eliminating variables is key. Restore backups incrementally until the problem is resolved.

Investigating Frontend Issues

Frontend display issues and CSS/JS problems after a Craft upgrade can be tricky to pin down:

• Clear all caches first and hard refresh pages to fix any stale browser caching.

• Open the browser console to look for JS errors on the page that may be breaking functionality.

• Do primary CSS/JS assets load correctly? Verify compilation completed successfully.

• Did an updated plugin make frontend changes? Roll back updates to test.

• Compare templates before and after upgrading to spot changed output affecting the page.

• For display issues, check that templates, CSS/JS packages, and component settings remain intact.

• Test different frontend routes - is one page broken or the entire site? Isolate the scope.

• If only anonymous users affected, double check template permissions weren't changed inadvertently.

Check every part of the frontend stack - CMS, plugins, assets, caching, templates, configurations - to uncover the source of the problems.

Getting Developer Support

If you're still stuck debugging upgrade issues:

• Ask on Craft's Stack Exchange forum to tap into the community's expertise.

• For plugins, check their documentation for upgrade troubleshooting tips, or contact the plugin developer's support.

• Hire a freelance developer experienced with Craft CMS and upgrades to help troubleshoot and resolve lingering problems.

• For complex custom sites, work with your original development agency for upgrade assistance.

• As a last result to get a site back up and running, roll back the Craft upgrade completely and investigate alternatives.

With Craft CMS, you have resources like official docs, Stack Exchange, blog posts, and experienced developers available to help solve upgrade issues. Don't hesitate to utilize them when you get stuck!

Finalizing the Upgrade

Improving SEO

After upgrading Craft CMS, complete some technical SEO tasks to ensure a smooth transition:

• Submit new XML sitemaps to Google/Bing to index new URLs and content changes.

• Create 301 redirects for any changed or removed pages to avoid dead links and lost authority.

• Adjust titles, meta descriptions, and social media tags updated for new templates.

• Confirm structured data like JSON-LD is still populated correctly.

• Check for any mixed content warnings or broken links caused by the upgrade.

• Look for new SEO-related features in the upgraded version to implement like image alt text.

• Re-crawl the site in tools like Search Console to identify any major indexing issues to address.

Staying on top of SEO details ensures the upgrades don't negatively impact performance in search.

Using Version Control

Leverage version control systems like Git when upgrading Craft:

• Commit code changes during each step of the upgrade process to document the incremental updates.

• When fully upgraded, tag a new release in version control so you can easily roll back if needed.

• Branch off of the upgraded release to continue new development rather than directly editing the upgraded code.

• For major version bumps, maintain separate version-specific branches for older versions still in development/support.

• Down the road when upgrading again, merge in the latest release branch to bring along all version upgrades.

Version control gives a safety net when upgrading, and eases maintenance of multiple Craft versions simultaneously.

Automating Testing

For smoother future upgrades, implement automated tests and pipelines:

• Write integration tests covering critical site functionality using Codeception or PHPUnit.

• Build a CI/CD workflow that runs regression test suites against a staging environment after upgrades.

• Use services like Travis CI and GitHub Actions to automate testing Craft upgrades prior to launch.

• Monitor performance metrics like page speed before and after upgrades.

• Automate browser testing across environments with tools like Selenium.

With automated tests, you can catch upgrade issues immediately and continue regression testing after launching new versions.

Investing in test automation and CI/CD improves development workflows long-term. Upgrades become lower risk and less disruptive over time.