Upgrading Guide

From MODx Wiki
Jump to: navigation, search

To upgrade MODx you follow almost exactly the same steps as in the Installation Guide. With one big exception. You do not erase or overwrite the config.inc.php file on your server. Here are the steps.

  1. If you have modified any of the default snippets or plugins, either rename them in the resource manager or be sure to uncheck them when you get to the step in the installation wizard which asks you which snippets and plugins to install. The upgrade process overwrites all the default snippets to ensure you have the latest versions. (If you modify any of the core distribution snippets, it is recommended you save them with a new name to prevent this from happening.)
  2. Backup everything. Download all your files with your FTP client to your hard drive. Use phpMyAdmin or whatever database utility you have to "dump" your entire database to your hard drive.
  3. Make sure everything is backed up! No kidding!
  4. Download and unzip the newer version of MODx.
  5. Upload the contents of the extracted folder to your server. Simply overwrite all the old files. MODx archive should not contain the config.inc.php file in /manager/includes/ directory, so it won't be overwritten. But it's still good to check before uploading that it's not there, and that you have a backup of your current config.inc.php. (Did you remember to backup the files before doing this?)
  6. Note that some FTP programs will not reliably overwrite existing files. This can leave you with a mixed MODx install and some very odd problems. Often, it's better to just rename the manager directory to manager-old, create a new manager directory, copy the old manager/includes/config.inc.php file to the new manager directory, and then upload the manager files from the new version of MODx.
  7. Now fire up your web browser and load the index.php file found in the /install/ directory. In other words, type http://your_modx_site.com/install into the browser's address line.
  8. Follow the online steps. This time, right after you accept the license agreement, be sure to select the Upgrade radio button.
    • NOTE: If your MySQL version is older than 4.1, select the Advanced Upgrade and use cp1251_koi8 as the Connection character set because the the only allowable value for charset_name is cp1251_koi8 before MySQL 4.1. It is possible to add new character set mappings by editing the sql/convert.cc file in the MySQL source distribution though, so you might be possible to use other charsets too.
  9. If you deleted and your old files instead of overwriting them, you may have to CHMOD the files and folders that are described in Installation Guide to make them writable by the server, but the upgrade wizard will tell you if you need to.
  10. Remember to uncheck any resources in the installation that you have modified yourself, if you have not changed their names.
  11. Once you get to a screen that has a checkbox offering to remove install directory, make sure it's checked (This prevents people from running the installation/upgrading process again and doing a hostile take over of your site).
  12. After the you have finished the upgrading wizard, go back to your FTP program and make sure that the /install/ folder is deleted. If it's not, delete it manually.
  13. Finally, change the permissions of your config.inc.php file in /manager/includes folder back to read only. If you had written it down before, use that same CHMOD setting now, or try setting to 0444 (r--r--r--). This is really important, and will help to prevent your site from being hacked.
  14. Finish the upgrading wizard.
  15. Once things are up and running again go to MODx manager and clean up your plugin and snippet names if you changed anything in step 1.
  16. That’s it, you're done. You’ve just upgraded MODx.

Alternate Method

Uploading a new version of MODx over the top of an old one will leave you with old files that are no longer used.

MODx team members each have different ways that they like to upgrade, but here's a method that will have the least downtime:

  1. Download everything from your site.
  2. Make a copy of your database.
  3. Basically, make sure you have all the old files backed up so that you can restore the old version if you need to.
  4. Create a new local directory called MODxNew (or whatever you prefer).
  5. Extract the new MODx files to that directory.
  6. From your backup, *copy* the config.inc.php file to manager/includes
  7. Copy any snippets, modules, plugins, etc., that you need or have modified into the appropriate parts of MODxNew.
  8. Copy any images, css, template files, documents, etc., into the appropriate parts of MODxNew.
  9. Rename the new folders/files to "index.php-new", "manager-new", "assets-new". Don't rename "install". Upload these folders (including the "install" folder) and the "index.php-new" file. This takes a while.
  10. Switch the names of the existing folders/files to "index.php-old", "manager-old", "assets-old".
  11. From this point, your site is not working.
  12. Change the names of the newfolders/files to "index.php", "manager", "assets".
  13. Run yoursite.com/install in your browser, being sure to select Upgrade. See Installation Guide for more information.
    • NOTE: If your MySQL version is older than 4.1, select the Advanced Upgrade and use cp1251_koi8 as the Connection character set because the the only allowable value for charset_name is cp1251_koi8 before MySQL 4.1. It is possible to add new character set mappings by editing the sql/convert.cc file in the MySQL source distribution though, so you might be possible to use other charsets too.
  14. From this point, your site should be working again. If it isn't, switch the folder names back!
  15. You should then be able to delete all the -old directories.
  16. You should also, as a result, have a local backup of the old site, and a local backup of the new site.

Visitor Stats

MODx version 0.9.2.x and earier included very nice "Visitor Stats" report under the "Site" menu, which is not available out of the box in version 0.9.5.x. However, there are several alternatives, including plugins and external services (See Visitor Stats)

Error Messages

Please refer to Installer Error Messages page.

Personal tools