The dotCMS upgrade process for customers self hosting dotCMS provides fine-grained control over the upgrade steps and little downtime, and enables a quick rollback to the prior version if needed.
Preparation Steps
1. Review the Changelogs.
The change log contains specific information on both the changes that have been made in the new version and how this may affect your individual dotCMS installation. Keep an eye out on Breaking Changes, which will require change in your system for the new version to work, this is noted at the top of the changelog for that particular release. Importantly, the change log for the new version may suggest additional variables that might need to be set or upgrade steps you need to take, based on your individual dotCMS configuration.
Note:
- The changes are cumulative, so you should review all changes between the older version you are running and the targeted version you are upgrading to.
2. Take Backups
You should have good backups of your shared/assets folder and database. During the upgrade process, dotCMS will make SQL changes to the underlying database schema and data to bring it up to date with the target version. While dotCMS should upgrade cleanly, it is always best practices to ensure you have good backups of your database and shared assets folder before attempting an upgrade. For more information on how to perform any of these steps, please see the Backup and Restore documentation.
Version 21.06 is the last version of dotCMS to support Oracle and MySQL. If you use MySQL, this tool can simplify the migration from MySQL to PostgreSQL. It is believed to work in most cases, though it has not been tested with significantly old versions of the software — one more reason backups are vital.
3. Prepare a Parallel Instance
It is highly recommended that all major version upgrades be performed on a parallel instance for the purposes of testing. This is dotCMS's standard operating procedure when performing major updates for a customer, as well.
Once you've established your parallel instance, follow the steps below first on it. If satisfied with the results, replicate accordingly on your production environment.
Performing the Upgrade
1. Implement a content freeze.
Alert dotCMS users that they must not edit any content until the upgrade window is complete or their changes may be lost.
Note: If running PostgreSQL RDS, you need to either grant the rds_superuser role to the dotCMS database user or use the superuser (typically postgres) until the upgrade procedure has completed. Afterward, you can revoke the rds_superuser role from the dotCMS database user or switch to using the intended database user instead of the superuser (e.g. postgres).
2. Scale to 1 node before upgrading.
When upgrading dotCMS, we suggest scaling your dotCMS environment to a single node before attempting the upgrade. While rolling upgrades are generally possible, we do not test them and advise against attempting them.
3. Update the dotCMS container image tag.
You should update your configuration and or .ymls to reflect the targeted upgrade version. If possible, you should use a unique docker image tag as uniquely tagged images will never change and insure a repeatable deployment process. Make sure that your dotCMS configuration variables are correct based on the targeted dotCMS version and that your database and shared asset files are mapped in appropriately.
4. Start the Upgraded Version
Apply the changes made to your .yml or container orchestrator.
- Always tail the console logs for any errors during upgrade.
- Always start up a single server in a cluster first, before starting up any of the other cluster nodes.
- Any modifications needed to upgrade the database to the new version will be performed during this startup.
- Once the database upgrade has been completed, the database might no longer work against the old dotCMS version. If you need to roll back, you will need to restore the database from a prior backup.
- The upgrade is complete once you see
INFO: Server startup in xxxxx msin the log. - Login and test the administrative functionality.
5. Scale up your nodes
Once you are able to login to the admin screen on the initial server, you can scale up the remaining servers in the cluster, and they will automatically synchronize with the initial server to receive the upgraded content.
Verify and Finalize the Upgrade
1. Test functionality
Test functionality on both the frontend and backend, to ensure everything works as intended.
2. Lift the content freeze
Allow dotCMS users to access the system backend to edit content again.
3. Start a full reindex (Optional)
This is a maintenance step that normally only needs to be done in case of content inconsistencies. While not ususally required, some version upgrades require that a full reindex is run after the upgrade is complete. It can also be helpful to reindex in order to ensure that the index is 100% accurate and to make sure the reindex process runs reliably before a reindex is actually needed. In rare circumstances, unexpected data can keep the reindex process from completing and it is good to identity and fix this proactively.
