Migrating Your MODX Site

This tutorial explains the best practices to maintain data portability in MODX and how to migrate a site from server to server.

By YJ Tso  |  Updated: April 27, 2016  |  8 min read
Migrating Your MODX Site

MODX was architected from the beginning to be easily transportable between different environments, especially if the implementer follows a few simple guidelines (more on that later).

However, the official documentation on the topic can be overwhelming, partly because it attempts to cover every possible environment in detail. Yet some of the steps described aren’t even needed in the vast majority of cases.

The Straight Goods

In this post, we'll explore the basic principles behind MODX data portability. Anyone, having read this, will hopefully be able to perform MODX migrations with confidence, regardless of the server environment. Only if a migration fails, should you need to reference the official documentation.

For those who want a quick summary:

  1. Install MODX on the new server.
  2. Copy all files over. Exclude the folders: connectors, manager, and core. Include subfolders core/components and core/packages. Exclude files: index.php and config.core.php.
  3. Export the full DB and inject into new install.

Now let's take a deeper dive into the "why" as well as the "how".

Requirements

At an absolute minimum, you require the following 3 things, in order to move a MODX site:

1. Database

You must have either the ability to export the entire MODX database, or a previously exported DB file (as long as it’s up-to-date with the data you want to migrate).

The export should include "drop table" statements, as well as the structure and data of every MODX table, with the possible exception of the modx_session table. In many cases you don't need/want to move this table. If it exists in your import—don't worry. The migration should still work ok, only that users may have stale or invalid sessions on the migrated site, in which case you should flush the sessions once the migration is complete.

2. Files

You need access to retrieve the site-specific files, on the current server. Preferably, you have privileges to archive (e.g. zip or tar) these files, which will save you all kinds of headaches during the move—but if not, then (S)FTP access is minimally acceptable.

Imagine what it would be like to move your home, but without any boxes. The relative convenience of boxes, in this case, is approximately the same as that of file archives, in moving a website around.

On the new server, however, you will need the ability to extract archives, and setup databases, etc...because of the third requirement.

3. A New MODX Install

You need a MODX install on the destination server, of the same version as the one from which you’re moving. For example, attempting to migrate a 2.2.16 site to a 2.4.0 site could cause problems.

“Why can’t I just move all the MODX core files, along with the site-specific files, from the old server to the new?” ~ What Everyone Is Probably Thinking

Well, you can, but you’ll experience problems far less frequently if you move only the site-specific data and not the core files. This is due to the aforementioned principles of data portability in MODX.

This “Data Portability” Thing—Best Practice Guidelines for MODX Development

Essentially what it boils down to, is the fact that when building a MODX site, you should never modify the core—known as “hacking the core”. MODX is very flexible, and architected for extendability, so that you can build anything, with zero core hacks.

Thus, the line where MODX core files stop, and site-specific files begin, is very clear and predictable. If you install MODX on two different servers, it will be configured with different environment variables, but otherwise they will be identical, and more importantly they're agnostic to your site-specific data.

So the idea is: move the data, and leave the MODX software alone. To continue the analogy, moving the contents of your house to a new house, is easier than moving the house itself.

The Four Folders

MODX installs with the following folders:

  1. core/
  2. assets/
  3. manager/
  4. connectors/

Note: the names and locations of these folders may be customized, but there will always be 4 folders performing these functions, except for the rare case when the `manager/` folder has been deployed in a separate environment for security.

If your MODX site follows convention, then all your site-specific assets, such as CSS, JS, and images, will be inside your assets/ folder, so naturally you’ll want to migrate this folder.

If you have assets, images, or what-have-you, in other locations, such as images/ or template/ then you’ll want to move those as well. The take-away here, is that you don’t need to move any of the other 4 folders that are installed with MODX, with the following exceptions:

  1. core/components/
  2. core/packages/

These are subfolders inside your core/ folder. You do not want the entire core/ folder, only these two subfolders therein. These 2 subfolders hold the logic for your installed Extras—additional components that extend the functionality of the MODX core software.

Due to the fact that a given MODX site can have an arbitrary combination of installed Extras, it follows that these two subfolders are site-specific and should be migrated.

The Two Files

Not infrequently, the document root of a MODX site gets populated with site-specific files as users upload images and such. While contrary to best practices, it's a common issue.

This isn't a critical problem—simply migrate all files in the web root except:

  1. config.core.php
  2. index.php

These are core files that, if overwritten in your new "target" install, will almost certainly cause problems—especially the first one.

Also, watch for server config files like .htaccess. These might migrate ok but depending on the situation they may also cause issues. Server configuration is beyond the scope of this article.

Review

Let's review again the principles above:

  1. Start with a new "target" install on the destination server, ensuring its the same version as your existing.
  2. Move the contents of the house, not the house itself. In MODX that means all files except the core folders as described above, and the 2 core files.
  3. Export the MODX database and import to the database of the "target" install.

In the vast majority of cases, this works without issues.

The method you use to package files matters not. You could use git, and add the files and folders mentioned above, into your .gitignore.

MODX Cloud has a "Snapshot" feature that migrates a MODX site from one virtual server to another, and the above is exactly what the packaging technology does. Snapshots have been used successfully, many thousands of times.

Snapshot technology is also available via an open source, command-line tool called Teleport. You can use that, on any server that meets Teleport's minimum requirements.

I've personally migrated MODX sites hundreds of times, manually picking and choosing the files to package, using the above principles. I rarely run into problems. Others on the MODX core team do the same.

The principles work, regardless of the method. Notwithstanding, there are edge cases that require troubleshooting.

Troubleshooting

Database Prefix

If, after performing the migration, you login to the target install and it still looks like a fresh, new MODX, check that the imported database tables use the same prefix as the target install.

You do this by connecting to the database using a client like phpMyAdmin or Sequel Pro. If there are two sets of MODX tables, each using a different prefix, then you need to configure your new install to use the prefix of your imported tables.

You can do this by editing the main MODX config file, found in a subfolder of your core folder at: core/config/config.inc.php.

Note: if the "config key" was customized during installation, the file will be named differently: core/config/{$config_key}.inc.php. It's also possible that the name and location of the core/ folder may be customized.

In the config file there's a PHP variable for the database prefix. Change the value of the variable to the prefix on your imported tables and save the file. At that point clearing the MODX cache should also clear the problem.

Paths

If you installed MODX from scratch on the destination server before migrating, you shouldn't run into any issues with paths. In rare cases, an Extra may have an invalid path configuration. If that Extra includes a critical Plugin, your site may seem quite broken.

Another case may be that the site has been upgraded from a very old version of MODX, or worse is still on a very old version (2.1.x or older). There's a hard coded path in the database, in these old versions.

In any of these cases, search the database, in the system_settings table, and workspaces table, for hard coded paths, and modify them for your new environment.

If your site is still on a very old version of MODX, it cannot be overstated how critically important it is for you to upgrade immediately. As software ages—any software, made by any vendor—it becomes vulnerable. By running old software you're sending an open invite to malicious hackers.

Core Hacks

On the rare occasion, you may be attempting to migrate a MODX site that has modifications to the core files.

There's three types of these scenarios:

  1. The site uses a custom manager theme. This can be remedied by migrating any non-default subfolders of the folders manager/templates/ and manager/controllers/.
  2. An installed Extra deploys files in one of the core folders, for example inside manager/. This can be fixed relatively easily, by reinstalling the Extra, using the Extras Installer inside the MODX Manager. However in this case please alert the author of the Extra that his/her deployment affects data portability, or let us know and we'll try to reach out to them.
  3. The original implementer didn't understand MODX's architecture and extendability, and therefore modified some core files, needlessly breaking data portability as well as the upgrade path. Fixing such a site is beyond the scope of this article, but if this is your case, the MODX team can help.

Wrapping Up

The principles described here are tried and true—battle-tested and used almost daily by the MODX Core Team. We know it works.

That said, rarely is there only one "right" way to do things. If you have any tips or advice on how to migrate a MODX site, please share in the comments.