This article is meant to help you integrate Modxcloud to upgrade MODX Revo safely.

And more specifically, it is based on my experience running MODX in a (gulp) shared environment.

When upgrading MODX from one version to another there is always that sinking feeling that occurs right when you complete the upgrade process: what if anything will break and what will I have to fix?

Want to get rid of that pit in your stomach? Want a faster simpler workflow?

Great. This post is for you.

The old way to upgrade in a shared environment.

My old way to upgrade was less than perfect, but here it is.

• Create a backup of MODX database using phpmyadmin
• Create a backup of all site's files in event that site breaks after upgrade.
• Pick a low traffic time to make the upgrade in the hopes that I would create the least amount of downtime possible. (Can you feel my fear yet?)
• Upload newer version of modx into a subdirectory on preexisting install of MODX in remote directory. (I know I should have worked locally or use github, but this was the way that I had worked.)
• Extract the archive on remote server in subdomain.
• Install new version of MODX in subdomain.
• Copy all the relevent tables from MODX database and insert them into new database. This included the modx_site_content, modx_site_htmlsnippets, modx_site_plugins, modx_site_snippets, modx_site_templates, modx_site_tmplvars, modx_site_tmplvar_access, modx_site_tmplvar_contentvalues, modx_site_tmplvar_template tables

  Typically I would work with two instances of phpmyadmin open side by side so that I could compare the values of the ids of each row to make sure that there wouldn't be any duplicate values from old table and new table.

• Copy all relevant site assets from preexisting site, into subdirectory. This includes all image, css, and js files.

Moment of truth time

• Log into manager and test it to make sure that all the extras work inside manager.
• Preview site in front end to confirm all extras work. This has typically been the time to see what doesn't work. This is especially true if you are moving from an older version of MODX to any shiny new version of MODX that is 2.3+

  This is the case because the underpinnings of modx (the connectors etc) have been upgraded and so some extras work fine, some are mostly dead (thank you Princess Bride), and some are just plain DOA. Here is the current list of compatible extras for MODX 2.3

• If everything works fine, you are good to go, and then you can do an upgrade.
• Go into system settings and search for "Site Status". Change it from Yes to No. This will briefly take down website as you upgrade it.
• Remember that zip file of your new MODX version? It is time to extract it into the root directory of your site. Drag the setup folder into the root directory of your old MODX install.
• Overwrite the old MODX files. Drag and copy drop the following folders from your test install: connectors, core, and manager as well as the index.php file into the root directory of your MODX install.
• Clear your browser cache
• manually delete all files inside the core/cache folder
• go to your http://yourdomain.com/setup and follow upgrade steps.
• Log into manager
• View Site in front end
• Boat Drinks
• Delete all the files in the test subdirectory.
• Delete all files inside the folder created when the new version of MODX was extracted from the zip file.

Enough of that right? Want a simpler way?

Modxcloud has an ingenious tool called vapor that allows you to take a snapshot of all the files in your current modx install and save it into a zip file. They provide excellent directions on how to use the vapor tool too.

Download the Vapor zip

From their User Guide:

Import Sites with Vapor

Vapor is a special application that is used to package a MODX Revolution site into a Snapshot for import into MODX Cloud from another web host or development environment. Bringing a MODX site into MODX Cloud with Vapor is a straightforward process. Here are the basic steps to get a MODX Revolution site into MODX Cloud:

1. Upload or place the Vapor script alongside your MODX Revolution Site
2. Run Vapor from the command line or HTTP
3. Import the Vapor package into MODX Cloud
4. Inject the Snapshot into an existing Cloud or create a new Cloud from the Snapshot

Notes on Usage

• Vapor may not work on every MODX Revolution install; some unique environments may leave you with incomplete data.
• Vapor works best when run from the Command Line; running it from your browser via HTTP will generally work but increases the likelihood of an incomplete or missing snapshot.
• If you have trouble with zip files or package management on your server you may (but not necessarily) encounter issues.
• While you can package an Advanced install, Advanced installs are not yet available on MODX Cloud. Your site will work with the default core and Manager locations.
• We have not tested the import of 2.1.x sites. You're welcome to!
• There is a known issue that requires special attention for sites with Articles installed on Revo 2.2.0. See below for instructions.

Using Vapor at the Command Line (Recommended)

Running Vapor at the command line is recommended as it is the most reliable method for most sites on most servers. If you can access your server using a command line utility or SSH tool, use the following steps to run Vapor.

1. Open a command line utility such as Terminal on OSX, PuTTY on Windows or your favorite terminal in Linux.

2. Connect to the server of the site you wish to package via SSH (replacing user and the site URL with your own data) as follows:

   $ ssh user@ftp.yourmodxsite.com

3. Navigate to the directory containing your MODX Revolution site.

4. Create a new folder called vapor and then change to the vapor directory by running the following two commands:

   $ mkdir vapor

   $ cd vapor

5. Fetch the Vapor zip using the wget command (if available as follows):

   $ wget http://modx.s3.amazonaws.com/releases/vapor/1.0/vapor-1.0.0-pl.zip

6. Extract the file into the vapor directory you created in the last step, as follows:

   $ unzip vapor-1.0.0-pl.zip

7. While in the vapor directory, execute the following command:

   $ php vapor.php

8. Vapor will output the results to the command line; no displayed errors should mean your package is fine.

9. Change directories to /core/packages/ to to confirm the vapor package was created. It should be named something like yourmodxsite.com-120712.1932.27-2.2.1-dev.transport.zip.

10. You're now ready to import your Snapshot.

Using Vapor with FTP/HTTP

If you do not have SSH access but have (s)FTP access to your server you should be able to package smaller sites using this method. This method should work with sites without large databases or image/media directories.

1. Download the Vapor zip and unzip it.

2. Using your (s)FTP client (such as cyberduck, FileZilla or Transmit) login to your server and create a folder named vapor in the directory where your MODX site is installed (where your index.php file resides).

3. Upload the unzipped Vapor files into the newly created vapor directory.

4. Login to the site's MODX Manager as an Admin User so your browser has an active session to allow it to function correctly.

5. From your browser navigate to the vapor/vapor.php file which will start Vapor. If your site is at http://yourmodxsiite/ you'll want to go to http://yourmodxsite.com/vapor/vapor.php.

6. Vapor will output the results; no displayed errors should mean your package is fine.

7. Using your (s)FTP client, locate the package Vapor makes in /core/packages/and note the full URL or place in a publicly web accessible directory for importing. DO NOT RENAME or otherwise modify the file!

8. Follow the instructions to import your Snapshot.

Import Your Snapshot

Importing Snapshots is done from the MODX Cloud Dashboard.

1. Login to the Cloud Dashboard and navigate to your Vault.

2. click the Import Snapshots button at the top-left of the Snapshots tab.

3. In the pop-up dialog, choose a Category or create a new one.

4. Paste the publicly accessible URL of the Vapor Snapshot into the field.

5. Click Import Snapshot to start the import which, depending on the size and connection could take a few minutes. You'll receive an email upon completion of a successful import.

6. Your Snapshot is ready to be Injected into an existing Cloud or Create a new Cloud with it.

1. Take a break and grab a quick snack (I prefer chips and salsa) while you wait for the notification email that the snapshot has been successfully imported.
2. Once you receive the notification, go to the vaults section, find your newly imported snapshot and click "Create a new Cloud from Snapshot"
At next screen, Give the cloud a name, and choose the cloud location closest to you. Make sure development cloud is selected, and click "Complete Cloud Creation"

Pro Tip: This will create a cloud with the most recent version of MODX. This will force you to upgrade directly and skip other steps inside upgrade path. There is an alternate method which is to go to Clouds page, and click new "Cloud".



Notice the "Change Version" link. You can change that version to match the version of your snapshot. That will allow you to upgrade the product up the upgrade path in steps. Most of the time this is totally unnecessary.

3. We now get to wait for another notification email that the cloud has been created
4. Once we get it we will go to clouds section inside modxcloud and click on name of new cloud.

5. Once inside the selected cloud we need to Install phpmyadmin so that we will be able to export the database.

6. Using your favorite ftp program, create new connection using the settings found inside the "SSH/SFTP Connection Information" Section.

   Pro Tip: When setting up the the connection inside your FTP program remove the username from the front of hostname. If modxcloud says your hostname is cxxxx.paas2.tx.modxcloud.com, you would insert paas2.tx.modxcloud.com into the hostname field in the FTP program.

7. Connect to modxcloud site via sftp and manually remove all folders/files from the core/cache folder
8. Clear your Internet browser's cache.
9. Now that the background work is done, create a new admin user, and wait for notification that it is successfully installed.
10. While you are waiting for notification, click "View Site" and go through site page by page, noting anything that doesn't work as anticipated.
11. After checking site, you should have received notification that admin user is created. Log into manager using the credentials you created earlier
12. Go around manager taking note of anything that doesn't work as anticipated.
13. Remember that list of compatible extras? Well now is the time to look at your extras and compare them to the compatible list, and upgrade them to most recent versions while dealing with any issues that come up. This can take time.
14. Troubleshoot any other weirdnesses inside manager and in front end.
15. Once site works as anticipated in modxcloud, take a break and give yourself a high five, you deserve it.
16. Export database using phpmyadmin that we installed in step 5.
17. Put site status into inactive mode inside Site Settings.
18. Create Backup of old database.
19. Create Backup of all old site files

S%$t Happens, make the backups.

20. Connect to old site via sftp /ftp and manually remove all folders/files from the core/cache folder and then clear your browser's cache.
21. Connect via sftp to both your modxcloud site in one window and your old site, in another window. If your ftp program allows you to ftp from one remote domain to another, drag and drop the site files into root directory of target site. This will overwrite your old site files.

    PRO TIP: Take care not to overwrite, any of the config files in your old site. These are found in:

    • core/config/config.inc.php
    • /config.core.php
    • /connectors/config.core.php
    • and /manager/config.core.php
22. Browse around site and confirm that everything works as anticipated.
23. Once you are satisfied that everything is hunky-dory., put site status back into active status.

So now that we are done with tutorial, it is time to ask ourselves a couple questions.

Why not use Modxcloud for all your sites in the first place?

That is a great question Noah, and one that we should all consider. It is outside the scope of this quick post, but I will follow this post up with another one about doing just that.

Why is this a better workflow anyway?

The biggest reason that this is better, is that the troubleshooting process is much faster (as is everything else) inside the cloud. Another compelling reason is that your testing environment is wholly separate from your live environment. This allows you to make mistakes, and worst case scenario, easily delete the cloud and start over if need be. The opportunity to make backups along the way, allows you to easily revert to a backup as well.

This post was not meant to be the only way to utilize Modxcloud, it was just a reflection of a recent troubleshooting venture gone right.

I look forward to your feedback and will incorporate it into the post to make this more useful to other MODXers.

Back to Blog Home