Upgrade MODX

Before running the commands shown on this page, you should load the Bitnami stack environment by executing the installdir/use_APPNAME script (Linux and MacOS) or by clicking the shortcut in the Start Menu under “Start -> Bitnami APPNAME Stack -> Application console” (Windows). On OS X VMs, the installation directory is /opt/bitnami and OS X VM users can click the “Open Terminal” button to run commands. Learn more about the Bitnami stack environment and about OS X VMs.

It is strongly recommended to create a backup before starting the update process. If you have important data, create and try to restore a backup to ensure that everything works properly.

To upgrade to the latest version of MODX, follow these steps:

NOTE: The steps below are only applicable to MODX 2.x.

  • Log out of the MODX Web-based administration panel if you are currently logged in.

  • Stop the servers using the commands below (on Linux and Mac OS X) or the graphical manager (on all platforms):

      $ sudo installdir/ stop apache
      $ sudo installdir/ stop mysql
  • Clear the contents of the MODX cache directory:

      $ rm -rf installdir/apps/modx/core/cache/*
  • Install the rsync utility (Linux and Mac OS X) or an FTP/file copy utility that supports directory merging (Windows). Read more about this requirement in the MODX documentation.

      $ sudo apt-get install rsync (Linux)
      $ brew install rsync (Mac OS X)
  • Download the latest version of MODX from the official website.

  • Uncompress the downloaded archive to a temporary directory on your system. Use the unzip command (Linux and Mac OS X) or an equivalent file compression utility (on Windows).

      $ cd /tmp
      $ unzip
  • Merge (don’t overwrite) the new MODX files with the existing files using rsync or your chosen file copy utility. Note that the core/ directory is to be placed in a different location in the Bitnami MODX stack and is therefore copied separately.

      $ rsync -avuh /tmp/modx-2.x.y/ installdir/apps/modx/htdocs/
      $ rsync -avuh installdir/apps/modx/htdocs/core/ installdir/apps/modx/core/
      $ rm -rf installdir/apps/modx/htdocs/core
  • Ensure that the installdir/apps/modx/htdocs/setup/ directory is writable by the user that the stack was installed as.

  • Restart the servers using the commands below (on Linux and Mac OS X) or the graphical manager (on all platforms):

      $ sudo installdir/ start apache
      $ sudo installdir/ start mysql
  • Browse to http://localhost/modx/setup.

  • You should see a warning screen like the one below. Set the MODX_CORE_PATH variable to installdir/apps/modx/core and submit the new value.

    MODX upgrade

  • Proceed through the upgrade process. Remember to select the “Upgrade Existing Install” option on the “Install Options” page.

    MODX upgrade

    NOTE: If the “Upgrade Existing Install” option is not available, refer to the MODX upgrade troubleshooting instructions. Avoid selecting “New Installation” on this page as doing so will overwrite all your existing MODX data.

  • On the “Installation Summary” page, ensure that all checks are passed. In case of errors, refer to the MODX upgrade troubleshooting instructions. If all checks pass, click “Install” to proceed.

    MODX upgrade

  • Once installation is complete, check the box to delete the setup/ directory and log in to MODX again to access the upgraded version.

    MODX upgrade

    NOTE: It is important to verify that the setup/ directory has been deleted. If not, delete it manually.

Last modification August 31, 2018