This post is sponsored by SiteDash, the remote management dashboard for MODX.

Is it a good idea to run a production site on the first MODX3 release candidate? Not really.

And actually updating it in production directly? Definitely not.

But as a long-time core developer with full server access, I am able to diagnose and fix issues as they come up. I'm also impatient at times, and this is one of those sites that's a perfect playground:

• While MODX.today has some complexity to it, it's also fairly simple with mostly just content and simple, well-structured templates. 
• While MODX.today does gets decent traffic and people use the backend fairly regularly, it wouldn't be a big problem if the site is unavailable for an hour or two.
  

I had updated a couple of other sites to 3.0.0-rc1 as well (one of which I'd been keeping up-to-date with the nightlies and use for a sanity check before releases), but none of those sites have any real complexity or day-to-day use. MODX.today is the first substantial site I was looking at upgrading.

So I figured... why not? Let's go!

Before upgrading

If you're not comfortable debugging and fixing issues on production, do not ever upgrade production directly. Copy the site to a test environment so you can get help comfortably, instead of having to rush for a site being down.

The first thing I checked was the SiteDash MODX3 upgrade checks. That was just launched yesterday, and automatically checks for a bunch of potential incompatibilities. That looked quite promising, with the primary issues being Collections and MoreGallery.

A new Collections update (4.0.0-alpha2) was released today with 3.0 compatibility, so that was one down. As for MoreGallery; there's only one post from many years ago using that, so no harm if that isn't accessible until an update is ready.

For a number of other extras the compatibility was still unknown, but that didn't worry me too much as none of them have a critical function on the site.

I made a quick backup of the database and double checked that the host had recent backups available to do a complete restore if needed, and then decided to go for it.

Running the upgrade

At its core, upgrading MODX2 to MODX3 is just the same upgrade process as updating to a new patch release: replace files, and run the setup.

There are however incompatibilities to be aware off, and for some sites you'll have to move back the core directory or perform other manual steps before you can move forward.

It's worth updating all extras before updating the core, however not all extras will allow you to update to the MODX3-specific releases until you have actually updated MODX. This can cause a bit of a catch-22 where the older versions don't work once you've updated to MODX3 and cause fatal errors to occur, which can also affect the front-end.

Having full server access (filesystem and database access) is crucial in case you need to fix or disable certain features to get into the manager. 

As everything was looking good, I clicked a few buttons in SiteDash to start the upgrade.

The update was complete after 1 minute and 17 seconds. That's a fair bit longer than a usual patch release on this server, but still a lot quicker than manually uploading files. 

After the update

Upon logging in to the site, I was presented with a partially blank screen that was fixed by a force refresh in the browser (ctrl/cmd + r). If you use a CDN like CloudFlare, forcing that to clear caches is also useful.

The front-end was also broken due to Collections. That was expected, so I quickly went to the package manager to update to 4.0.0-alpha2. That failed on the first try and required manually removing the old version and fixing the resources' class_key, but hopefully that'll be sorted out with the next Collections release to make future upgrades smoother.

After that the homepage worked again, as did the manager, however the actual post page was not rendering as expected.

The post page was actually failing on some javascript, which got corrupted due to an issue in the template. The offending code was a three-level-deep nested conditional output filter that broke the parsing, so I'm not sure if that has unintentionally been made a bit more strict in MODX3. After simplifying that logic, the javascript error was fixed, and the posts were also showing up again.

Further testing also uncovered another issue trying to create new posts from Collections, which turns out to be a core issue, but everything else seems to be working as expecting.

Conclusion

From start to finish took me about 35 minutes (with less than 5 minutes of downtime), which is more than a simple patch release, but not as long as I was expecting. There will definitely be sites that take more time and require more manual intervention, but this one was pretty smooth.

The SiteDash compatibility checks (and new Collections release) definitely gave me additional confidence to just go for it, and being able to actually do the update in two clicks saved a lot of time. 

For most people I would definitely recommend taking the time to do it on a test or staging environment, especially if there's any complexity to the site with various extras, needing to move the core folder back, etc. It is still a major upgrade that will break some extras and sites, but that process will continue to get smoother as it gets more real-world usage and more information about "gotchas" and configurations to look out for becomes known.

Hope you enjoyed this little write up!