CMSMS upgrade 1.9.4.3 to 1.11.* report

I have recently tried to upgrade CMS Made Simple 1.9.4.3 to 1.11.4. It took four weeks. Here is the full story.

First lesson for my reader (which I have learned a long time ago): Never believe when you are told that the CMSMS upgrade process is quick, simple, painless, and can be done by a novice in a few minutes. That is never true. Every time I have upgraded, it always broke something, or did not work on the first try.

And I am not using a large number of non-core modules. Third-party modules may have gone inactive, and might not work any longer with an upgraded core without code tweaks.

 

The second lesson for my reader is to never work on any original files, and to never work without a backup.

As my first backup, I create several versions of a database backup. See this article: Create a proper database dump. I create three versions: One default .sql, another compressed version of same, and third with the forced latin1 encoding of the database. Only this can give me some assurance that my database backup will actually be recoverable from.

I then create a full FTP backup by downloading the whole website to my computer.

Then, I create an archived backup of website. From the parent directory of the installed website, I issue this command over FTP:

tar -zcf backup.tar foldername/*

 

I never work with originals. Put in other words, I do not upgrade a live, "production" website. I always upgrade a "development" website first, and see what breaks (something always does).

 

So, I create another database, and after the proper adjustments, import the dump file of the original database into the new one.

Then, I copy the installation folder. In SSH,

cp -rf sourcedirectory destinationdirectory

 

Then, I open the config.php of the new installation (we just created by copying), and modify its paths, because the domain name points to the sourcedirectory production website, and we cannot access our destinationdirectory development server by typing in a domain name into a browser. We can access it, however, by typing in its full URL (like hostnames.yourhost.com/somenumber/htdocs/destinationdirectory), but config.php paths must be modified first before the website will work.

You must also change which database the development installation points to. It must point to the copy of the database you created. Verify this is so to the nth degree before proceeding. Original database must not be used by the development installation.

Note: sometimes mod_rewrite breaks when you switch from a domain name reference to a full one like this. If you can't fix the htaccess path, you can just turn off mod_rewrite by setting that option to 'none' for now.

 

Once you can navigate to your development copy, and view it as being functional, you can work on upgrading it.

You will thank me a thousand times over when something breaks. This way, if something breaks drastically, you can just create another copy off the original, and start over.

 

The first part of the upgrade process is to upgrade all of your modules. Go to the module manager, and see which modules it lists are due for upgrade.

If upgrading thru the upgrade manager single-click process fails (out of memory, timeout, etc), then you will need to use the manual .xml method I have documented on my website. Go to the CMSMS Forge, and get the .xml installation file for that module of the exact version that Module Manager wanted to upgrade to, not the latest version available in the Forge! The latest version in the Forge is for the up-to-date CMSMS installation, something that you do not yet have.

 

If you renamed the admin directory for security purposes (a good idea), rename it back to "admin", and change the relevant config.php setting.

 

We can now download installation file. Go to the CMSMS website, pick the latest version of the installation file, right-click, and copy the link location.

Then, SSH change to your development installation location, and from within that location say:

wget location_of_link

This will download the installation file right on your server. Doing it the long way, by downloading the link off the CMSMS website to your computer only to FTP it back to your server is illogical, error-prone, and very slow.

Then,

tar -zxf cmsmadesimple-version-edition.tar.gz

This should extract the new install on top of your existing files.

Now, set config.php permissions to 666 (writeable).

 

Then, run

hostnames.yourhost.com/somenumber/htdocs/destinationdirectory/install/upgrade.php

(NOT install.php!)

And see how many things break.

 

If your installation stops at the step of "Building static route database...", then it is one of the modules that causes this. With FTP or SSH, go to the modules directory, and rename the modules one by one, or in blocks, and restart the upgrade process after the renames. See which module is the culprit.

 

Any nasty errors on top of the page after the upgrade are usually PHP version mismatch (to the version of CMSMS installed) errors, or outdated module errors. If they are outdated modules, and the module in question is not a core module, CGExtensions, or other critical module, you can temporarily disable it by renaming its modules/ directory.

 

After this, I did manage to have the upgrade finish. However, first thing I noticed was that my database encoding appeared to be incorrect. Cyrillic characters were garbage. Â character was sprinkled throughout my pages. That was the part that took three weeks to be appropriately repaired. I wrote a series of articles on the topic: Working with MySQL, encoding, and upgrade issues

Somehow, the 1.9.4.3 installation allowed MySQL to transparently trans-code the actual UTF-8 stored in the table, to the Latin1 called out by the table encoding and collation, and back into UTF-8 to be displayed properly in the browser. 1.11.* changed either this, or the PHP version of its calls, and this trans-coding no longer works. I suggest that the problem is very widespread, even if few are aware of it. As the linked article explains, all MySQL version 4 databases, or version 5 databases with Latin1 encoding and / or collation have UTF-8 improperly stored in the database, because the WYSIWYG editor is browser-based, and the browser is most likely set for UTF-8 encoding.

Now is the perfect time for you to verify and repair this once and for all. UTF-8 is the path to the future, Latin1 is a dinosaur of the past.

Is your database MySQL version 5? Are your tables all UTF-8 encoding and utf8_general_ci collation? Are all fields not of Latin1 collation or encoding? Does the Operations tab of PHPMyAdmin lists collation (for future database operations) as utf_general_ci?

Does setting

$config['default_encoding'] = 'utf-8';

Not break anything in your website looks or functionality? (Look for character  appearing).

 

If you answered "No" to any of the questions above, it is time to convert to UTF-8. I provide absolutely all of the details at: Working with MySQL, encoding, and upgrade issues.


The second thing that broke were my custom UDTs. If it is a UDT, or a module call that breaks, it is easy to tell: page formatting or styling is usually lost, and content stops at some point down the page (not the whole contents of the page template and content area are rendered).

Examine your template in this case, and look around the area where page output stops. Comment out the offending code.

In my case, the UDT called the database in an obsolete way. The new way is along the lines of:

$db = cmsms()->GetDB();

 

Then, I had to replace {stylesheet} with {cms_stylesheet} in every one of my content templates.

 

The third thing was broke was that when trying to edit a page, the editing page would be completely blank. Not just the editor would be missing, but everything else as well, including the buttons. It appears that any parsing errors in the template will break the page edit function. In other words, not only must the template have the {content} tag, but the rest of the template cannot have errors. Also, all CSS must now be called in a new way. Replace:

{stylesheet}

with

{cms_stylesheet} in all of your templates and the editor will appear.

I had several problems with the template. One was the before-mentioned obsolete UDT and module code. I had to comment out those calls. Second problem was the double-encoding of the database. I have missed the templates table on my first pass. After converting the template as well, I had to manually look thru the template and remove any residual strange characters.

A third problem with the template were the smart quotes which somehow sneaked in in four places. They got converted to garbled characters as the result of the encoding change. I manually converted the strange characters to double quotes.

After a lot of editor enable-disable, cache-clear, Ctrl-F5, and other usual tools of the trade, my templates and page editing started working fully.

 

The fourth thing that broke was my Simple Feedback contact form. The error message is:

Fatal error: Call to a member function Execute() on a non-object in /*/htdocs/*/modules/SimpleFeedback/action.default.php on line 10

Still trying to figure this one out. TODO.

 

The fifth thing that broke was that my edit session started to time out. Before, I could leave the editor open for days and there were no time-outs. This time, I could come back to editing content, only to be redirected to the login screen, with my changes lost. This is why I never open the editor in a browser which does not have the Firefox extension TextArea Cache installed. The extension saves everything you type in. If anything happens, your work isn't lost. Still trying to figure this one out. TODO.

 

The sixth thing that broke was that the list of Tags returns a blank page. This was due to an old copy of OldPrint file residing in the Plugins directory of CMSMS core. After deleting the offending file, the list started to show.

 

The seventh thing that broke was that the header image (specified in the CSS) no longer showed. Other images specified in the CSS did not show either. Solution: In your CSS file, replace:

background-image:url(/uploads/folder/filename.gif); style links with:

background-image:url([[root_url]]/uploads/folder/filename.gif);

 

The eighths thing that broke was OldPrint. For CMSMS version 1.10+, CMSPrinting must be used instead. Call it like so in the template:

{cms_module module='CMSPrinting' text="Print Version" script="true" showbutton="true" popup="true"}

 

Lesson learned? TEST TEST TEST your development upgrade before declaring it fit to be for production.

If your upgrade works as it should, DO NOT touch the original install. Simply move your domain DNS setting to point to the upgraded installation copy. As soon as the DNS change takes effect, up have upgraded your website with zero risk of damage to the original installation!

Keep the old installation and the database for some time, in case problems come up with the upgrade.

 

Backup the upgraded installation as described before (database in three ways, installation in three ways).

Rename old installation folder to make sure you have disabled it.



˅˅˅ Additional valuable information is available at one of the links below: ˅˅˅

 

Did you like the article? Let Google Search know by clicking this button: . Please link to content that you find useful on this website on your own website, forum or blog! You can also comment on this page below, or contact me to ask a question or suggest a topic for me to research. There is a user-editable Wiki available on my website, as well as a Forum that you can contribute to. Site Map.

Page last modified 06-Jan-13 22:29:59 EST
Comments on this page:


Add a comment to this page
Comment Title:
Your Name:
Your Email Address:
Notify me of new comments to this item:
Additional Comments:
This is a captcha-picture. It is used to prevent mass-access by robots. (see: www.captcha.net)