Upgrade MODX

NOTE: We are in the process of modifying the file structure and configuration for many Bitnami stacks. On account of these changes, the file paths stated in this guide may change depending on whether your Bitnami stack uses native Linux system packages (Approach A), or if it is a self-contained installation (Approach B). To identify your Bitnami installation type and what approach to follow, run the command below:

 $ test ! -f "/opt/bitnami/common/bin/openssl" && echo "Approach A: Using system packages." || echo "Approach B: Self-contained installation."

The output of the command indicates which approach (A or B) is used by the installation, and will allow you to identify the paths, configuration and commands to use in this guide. Refer to the FAQ for more information on these changes.

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.

Approach A: Bitnami installations using system packages

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

• Stop the servers:

    $ sudo /opt/bitnami/ctlscript.sh stop apache
    $ sudo /opt/bitnami/ctlscript.sh stop mysql
  

• Clear the contents of the MODX cache directory:

    $ rm -rf /opt/bitnami/modx-core/cache/*
  

• Install the rsync utility:

  • Debian:

      $ sudo apt-get install rsync
    

  • CentOS:

      $ sudo yum install rsync
    

• Download the latest version of MODX from the official website.

• Uncompress the downloaded archive to a temporary directory on your system:

    $ cd /tmp
    $ unzip modx-2.x.y.zip
  

• Merge (don’t overwrite) the new MODX files with the existing files using rsync and update their permissions. 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/ /opt/bitnami/modx/
    $ rsync -avuh /opt/bitnami/modx/core/ /opt/bitnami/apps/modx-core/
    $ rm -rf /opt/bitnami/modx/core/
    $ sudo find /opt/bitnami/modx/ -type d -exec chmod 775 {} \;
    $ sudo find /opt/bitnami/modx/ -type f -exec chmod 664 {} \;
    $ sudo find /opt/bitnami/modx-core/ -type d -exec chmod 775 {} \;
    $ sudo find /opt/bitnami/modx-core/ -type f -exec chmod 664 {} \;
  

• Ensure that the /opt/bitnami/modx/ and /opt/bitnami/modx-core/ directories are writable by the Web server user:

    $ sudo chown -R bitnami:daemon /opt/bitnami/modx/
    $ sudo chown -R bitnami:daemon /opt/bitnami/modx-core/
  

• Restart the servers:

    $ sudo /opt/bitnami/ctlscript.sh start apache
    $ sudo /opt/bitnami/ctlscript.sh start mysql
  

• Browse to http://SERVER-IP/setup.

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

  

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

  

  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.

  

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

  

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

Approach B: Self-contained Bitnami installations

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

• Stop the servers:

    $ sudo /opt/bitnami/ctlscript.sh stop apache
    $ sudo /opt/bitnami/ctlscript.sh stop mysql
  

• Clear the contents of the MODX cache directory:

    $ rm -rf /opt/bitnami/apps/modx/core/cache/*
  

• Install the rsync utility:

  • Debian:

      $ sudo apt-get install rsync
    

  • CentOS:

      $ sudo yum install rsync
    

• Download the latest version of MODX from the official website.

• Uncompress the downloaded archive to a temporary directory on your system:

    $ cd /tmp
    $ unzip modx-2.x.y.zip
  

• Merge (don’t overwrite) the new MODX files with the existing files using rsync and update their permissions. 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/ /opt/bitnami/apps/modx/htdocs/
    $ rsync -avuh /opt/bitnami/apps/modx//opt/bitnami/appscore/ /opt/bitnami/apps/modx/core/
    $ sudo find /opt/bitnami/apps/modx/core -type f -exec chmod 664 {} \;
    $ sudo find /opt/bitnami/apps/modx/core -type d -exec chmod 775 {} \;
    $ sudo find /opt/bitnami/apps/modx//opt/bitnami/apps -type d -exec chmod 775 {} \;
    $ sudo find /opt/bitnami/apps/modx//opt/bitnami/apps -type f -exec chmod 664 {} \;
  

• Ensure that the /opt/bitnami/apps/modx/htdocs/ directories are writable by the Web server user:

    $ sudo chown -R bitnami:daemon /opt/bitnami/apps/modx/htdocs/
    $ sudo chown -R bitnami:daemon /opt/bitnami/apps/modx/core
  

• Restart the servers:

    $ sudo /opt/bitnami/ctlscript.sh start apache
    $ sudo /opt/bitnami/ctlscript.sh start mysql
  

• Browse to http://SERVER-IP/setup.

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

  

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

  

  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.

  

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

  

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