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.
My old way to upgrade was less than perfect, but here it is.
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.
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
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
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:
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.
Open a command line utility such as Terminal on OSX, PuTTY on Windows or your favorite terminal in Linux.
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 firstname.lastname@example.org
Navigate to the directory containing your MODX Revolution site.
Create a new folder called vapor and then change to the vapor directory by running the following two commands:$ mkdir vapor$ cd vapor
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
Extract the file into the vapor directory you created in the last step, as follows:$ unzip vapor-1.0.0-pl.zip
While in the vapor directory, execute the following command:$ php vapor.php
Vapor will output the results to the command line; no displayed errors should mean your package is fine.
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.
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.
Download the Vapor zip and unzip it.
Using your (s)FTP client (such as cyberduck, FileZilla or Transmit) login to your server and create a folder named
vaporin the directory where your MODX site is installed (where your index.php file resides).
Upload the unzipped Vapor files into the newly created
Login to the site's MODX Manager as an Admin User so your browser has an active session to allow it to function correctly.
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.
Vapor will output the results; no displayed errors should mean your package is fine.
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!
Follow the instructions to import your Snapshot.
Import Your Snapshot
Importing Snapshots is done from the MODX Cloud Dashboard.
Login to the Cloud Dashboard and navigate to your Vault.
click the Import Snapshots button at the top-left of the Snapshots tab.
In the pop-up dialog, choose a Category or create a new one.
Paste the publicly accessible URL of the Vapor Snapshot into the field.
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.
Your Snapshot is ready to be Injected into an existing Cloud or Create a new Cloud with it.
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.
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.
S%$t Happens, make the backups.
PRO TIP: Take care not to overwrite, any of the config files in your old site. These are found in:
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.