Updating WagtailCMS
May 22, 2023
Introduction
Wagtail is a popular content management system that allows users to create and manage websites easily. However, as with any software, it's important to keep it up-to-date to ensure security and performance. In this blog post, we'll discuss the steps involved in manually updating Wagtail hosted on a Red Hat based Linux server. We'll cover everything from preparing for the update to troubleshooting common issues that may arise. By the end of this post, you'll be equipped with the knowledge you need to update your Wagtail site with confidence.
Preparation
Before updating Wagtail, it's important to prepare for the update process.
- Read the release notes: It's important to read the release notes for the latest version of Wagtail to understand what changes have been made and if there are any compatibility issues that could affect your site. You can find the release notes on the official Wagtail Docs website.
- I highly recommend making all your changes on an identical development server, saving those changes to a git repository, and then pushing the changes to your production environment. This allows you to go through the update process and fix any issues without worrying about extended downtime for your site.
- Create a backup of your site: Creating a backup of your site is essential in case anything goes wrong during the update process. You can use a variety of backup methods, including using a backup plugin or manually backing up your site's files and database. It's important to store your backup files in a secure location.
Upgrade Steps
- SSH into your Linux host with a user that has sudo privilages.
- If you have a separate user that manages your Wagtail environment, switch into that user using this command, in my case I have a user named "wagtail".
$ sudo su - <user>
- NOTE: I like to use tmux with two terminals, one for the wagtail user and one for a user with sudo privileges. This helps with not having to constantly switch between users.
- Change into the root directory of your project. This will be the directory that has the manage.py file.
- Edit your requirements.txt file to reference the version you'd like to upgrade to.
- Example:
wagtail>=5.0,<5.1
- Example:
- After saving the file, upgrade Wagtail using the pip command.
$ pip install -r requirements.txt
- Once the upgrade process is complete, run the following commands to migrate any changes to the database.
$ python manage.py makemigrations
$ python manage.py migrate
- Fix any errors or warnings that pop up. If you fix errors, run the migration commands again.
- Run the collectstatic command to add all the new resources to your static folder.
$ python manage.py collectstatic --no-input
- Restart your web server (Gunicorn, uWSGI, etc...) and test your website to make sure everything works as expected.
Troubleshooting
If you encounter any issues during the Wagtail update process, try these troubleshooting steps:
- Check the release notes to make sure you followed all the necessary steps, and that any prerequisites are in place. Make sure you're updating to a version that's compatible with your current setup.
- If you're using third-party packages or plugins make sure they're compatible with the new version. Check the documentation or contact the package/plugin developer for guidance.
- Seek support: If you can't resolve the issue on your own, reach out to the Wagtail community or the support team for assistance. Provide as much detail as possible about the issue, including any error messages or log files.
- As a last resort you can always redeploy your site using the most recent backup to get back to a functional state while you look further into why the upgrade failed.
By following these troubleshooting steps, you should be able to resolve any issues that may arise during the update process. Remember to always backup your data before making any updates or changes to your site.
Conclusion
Updating Wagtail can seem like a daunting task, but it's an essential step to keep your site running smoothly and securely. By following the steps outlined in this blog post, you can successfully update Wagtail on both your development and production servers. Remember to always create a backup of your data before making any changes or updates, and to review the release notes and troubleshooting steps carefully to avoid any compatibility issues. If you encounter any issues, don't hesitate to seek support from the Wagtail community or the support team. With these tips, you can keep your Wagtail site up-to-date and running smoothly.
Additional Resources
- The Wagtail Documentation for Upgrading Wagtail
- Release Notes for all the past Wagtail releases.
- The Wagtail Slack community is a great place to go to ask questions.