Upgrading CMS Made Simple
Welcome to the official CMS Made Simple documentation pages. We make a continuous effort to keep the information here up to date! However, dear user, we highly value your assistance in the process.
We need your assistance to make the documentation accurate, user friendly and understandable. Therefore we welcome any tips or suggestions regarding documentation. Thank you in advance for your contribution.
However, we will not respond to technical support questions submitted using this form. If you are having difficulty with CMSMS and cannot find the solution on this website, please submit your question appropriately on our support forum at: http://forum.cmsmadesimple.org. Please remember to follow the forum rules when posting.
This page describes the steps to upgrade CMS Made Simple to the latest version. It is quite simple really, but please read the instructions carefully and in their entirety before starting.
These steps are generalized and do not provide specific steps for your host or your environment. Additionally, we expect that you have extensive knowledge of your website. How pages are organized, what addons you are using, where files are located, etc. We also expect that you have basic understanding of the features of your web host and how to perform basic system administration.
If you renamed your admin folder, please read this additional information before proceeding!
1. Carefully read the release notes. They are generally published in the CMSMS Blog, or used to generate the forum announcement. The release notes will give you insight as to what has changed and what may effect your installation of CMS Made Simple. Also, it may provide further upgrade and installation instructions. The changelog file will also give you relevant information, you find it in your CMSMS install: /docs/CHANGELOG.txt
2. Download the desired package for upgrading. There are some choices:
- The english package (i.e: cmsmadesimple-x.yy-english.tar.gz)
- The english package is a complete version of CMS Made Simple, with all of the functionality, but contains only the english language files. You may then add on additional desired language packs.
- The full package (i.e: cmsmadesimple-x.yy-full.tar.gz) The full package is a complete version of CMS Made Simple, with all of the functionality, and all of the translations (as of the time of release).
- A diff package (i.e: cmsmadesimple-diff-a.bb-x.yy.tar.gz) Diff packages are frequently distributed when CMSMS is released if there are no major changes in database structure between versions. The diff releases contain only the files that changed between the versions a.bb and x.yy.
3. Extract the downloaded package to a temporary location on your workstation.
4. Read the UPGRADE.txt document in the doc directory that is contained within the package (except for diff packages). It might overrule the information stated on this page!
5. Backup your database and all the files in your CMS Made Simple folder on the server. Download this backup to a known safe location.
6. Upgrade all applicable third party addons. For this you have to go into the Admin panel, and open Extentions >> Module Manager.
7. Upload the new files, overwriting all the files on your server.
If using FTP to transfer files make sure that you have a good FTP client (Filezilla is a known good client), and make sure you select to "overwrite" all files, and that you upload in "binary" mode.
It is important that you upload ONLY the files that were shipped in the package you downloaded. Some archiving tools (particularly on Macs) create extra files when extracting the package that are hidden from the file manager but are not invisible to the ftp client and may be uploaded accidentally.
If you are upgrading a diff package you need to clear the cache manualy and you can skip the next steps. But do check the admin "Modules" page if some module needs a manualy upgrade.
8. Navigate your browser to <cmsmadesimple folder>/install/upgrade.php
9. The first screen of the upgrade process may prompt you to select a language, this allows you to proceed through the installation process in a language other than english.
10. The next step asks you to perform a "system validation" this is a safety utility that allows you to ensure that all files have been uploaded correctly, and match the the ones shipped in the package. To do this you must upload the appropriate checksum.dat file that matches both the release of CMSMS and the package that you downloaded.
i.e: If you downloaded the cmsmadesimple-1.10-english.tar.gz package, extracted it, and uploaded it to your site, you should then download to your desktop, and upload for verification the cmsmadesimple-1.10-english-checksum.dat file.
If you are upgrading using a "diff" package you should chose the appropriate checksum.dat file for the install that you originally performed.
This is only a test, and you are expected to interpret the results of this test. On an upgrade situation it is entirely normal to have files in your installation that were not listed in the checksum file. You should be cautious when the checksum file reports that files are missing or do not match the expected checksum.
11. The next step of the upgrade process will perform various tests to ensure that your hosting environment meets the minimum requirements and settings for CMSMS and will give you the opportunity to adjust server settings (and/or .htaccess files) and retry the tests.
12. Proceed through the remaining steps of the upgrade wizard. It will ask for any necessary information and perform all necessary database changes, and will rewrite your config.php file.
Steps for after the upgrade is complete
1. Verify that everything is working as you would expect, keeping in mind the information you gathered from the release notes and other documents.
2. This will involve a test of your websites functionality both on the frontend and in the admin interface.
3. Upgrade all applicable third party addons.
The upgrade process should have upgraded all modules shipped with the CMSMS core. You will be responsible for upgrading the other third party modules your website uses.
4. Remove the install folder
5. Perform another full backup of your new "known good" environment and download this to a safe location.
If you have not kept up with installations of CMSMS and your site is now multiple versions behind, there is a procedure you can follow.
1. Ensure that you have a valid, and complete backup of your working system.
2. Complete the upgrade process described above in numerous steps. I.e: if your current version is version 1.6.7 and you wish to upgrade to 1.10.1, you should at a minimum upgrade to version 1.7, then to version 1.8, 1.9, and finally version 1.10.1
- Please be sure to read all of the release notes up to, and including your targeted release. As there may be additional steps to perform when upgrading to specific versions of CMSMS.
- The upgrade instructions for CMSMS 1.10.x stipulate that users upgrading from versions prior to 1.9.4 should upgrade to 22.214.171.124 first.
- When upgrading to CMSMS 1.10.x it is important to upgrade your modules to their latest version before upgrading CMSMS.
Though many experienced users have been able to upgrade directly from an old version of CMSMS to the most recent version it is not advised.
Using FTP is by far the slowest and most unreliable method to upload files to your server. We advise that you upload and extract files using the shell, ssh, or via your webhosts control panel.
Control panels on most modern webhosts provide file managers that allow uploading files, and extracting .tar.gz files. You could then upload your selected CMSMS package to the root of your CMSMS install (same location as the config.php file) and extract it from there. Once the package has been extracted you can safely remove it. This will save a considerable amount of time.