MODX Cloud is refreshing all servers with new Generation 2 (“Gen2”) platforms to boost speed, security, and scalability—and to bring enhanced functionality to every site (e.g., GeoIP headers and more). Any site on a legacy platform will be migrated to Gen2 servers.
We have created tools to make moving your sites to the Gen2 servers (a “migration”) simple, fast, and risk-free.
What Happens During a Migration
Migrating your sites to new platforms is designed to be as easy as possible. For most sites with Custom domains, the only thing most people will need to do is update DNS and turn off the proxy (which is part of the guided process). Dev sites won't require DNS changes or a proxy. All the add-ons, web rules, and custom domains will be assigned to the new Cloud. You won't have to do anything with them. If you had cron jobs (more below on cron jobs) or files outside of the www directory, you'll need to bring those over.
How to Migrate a Site
TL;DR … press the “Migrate…” button, to start moving your site to a newer, faster, better platform without downtime, risk, or hassle.
- Click the Migrate button—all but large sites usually take just a few minutes. The UI will update with the migration status as it happens in real time.
- Preview and review each site before a migration is completed—there's no risk of it breaking.
- Update your DNS. While your DNS updates happen, all the traffic can be forwarded from the old site to the new one.
- Help is at the ready. If you have any trouble, click the link in the blue status box to open a support ticket for assistance.
What to expect, and look out for, with migrations
Self-serve migrations can be done for virtually every site—even very large ones. If your site has transactions or user-generated content, you should put the site into maintenance mode. If you have cron tasks or files outside of the web root, those need to be manually migrated.
It’s best to refrain from making changes to a site during migrations. You can re-sync the files and database from the source site during migrations using a “re-sync my files and database” link in the blue migration status boxes, but any changes you make in the new location—except for manually migrated crontab entries or files outside of webroot—will need to be redone.
That said, most migrated sites should just work as long as your source site works on PHP 7.3, so you may want to upgrade to PHP 7.3 before starting a migration.
You can always open a ticket to request help from the MODX Support team for migrations.
How long do migrations take?
The longest part of a migration making a copy of the site on the new server, which for most sites takes just a few minutes. For large sites, expect it to take about as long as taking a manual backup, creating a new Cloud, then restoring that backup into the new Cloud (more happens, but that's a good proxy for timing).
The rest of the tasks to complete a migration should happen quickly, no more than a minute or two. The time it takes for you to review the site is the only variable. Since most sites should just work as long as they do so on PHP 7.3, you can possibly minimize your review time by upgrading to PHP 7.3 on your current site before starting a migration.
How can you migrate sites without downtime or extended content freezes?
First, your current site is live until you update the DNS. After you verify that your site is working on the new server, the migration system creates a proxy to the new server. This means that even before you update your DNS entries to point to the new location, all the visitor traffic is forwarded there and handled by the new site. Only after you click the button to complete the migration will the source site and proxy be removed. Even with the source site removed, you will still have a backup.
Can I migrate sites without custom domains (“dev” sites)?
Yes, you can. However, now would be a good time to purge old experiments or dev sites that haven't been touched in a while. The easiest way to do this is to archive it (make it an Archive Cloud). When you're ready to use it, you can restore the Archive Cloud on a Gen2 platform.
How does the migration process work?
All migrations begin with, and retain, a backup of the original site should it be needed.
Migrations are currently limited to instances on our legacy platforms. You trigger migrations from the MODX Cloud Dashboard by using the “Migrate” option in the gear icon (or right-click menu) on the grid view—or the “Migrate… (new)” option in the sidebar of the Cloud detail view. Migrations follow one of three workflows:
- Cloud with custom domains: A site copy will be created on a Gen2 platform using PHP 7.4. Once you verify the site’s integrity, you proceed to the next step, which places a proxy in front of the Cloud that forwards all traffic to the new site. The proxy allows time for the DNS changes to happen without incurring downtime. Once the DNS propagation is complete, the final step removes the proxy and original site. At this point, the migration is completed.
- Cloud without custom domains: This process is even more straightforward for Clouds without custom domains (“dev” Clouds) that are not associated with a live production site: there is no need for a proxy or switching DNS. Click to start it, and click to verify everything looks good. Done. Note: you will have a new URL that looks like khj1243jl3f.modx.dev going forward for dev Clouds.
- Support-assisted migrations: If you have problems with a migration that you cannot resolve with the tips below, then you can open a ticket from the MODX Dashboard for assistance from the Cloud Support team.
Application-specific troubleshooting for issues that may crop up is noted below.
For MODX CMS Websites
MODX Upgrades
Some older versions of MODX Revolution are not compatible with PHP 7.4, the minimum version supported on Gen2 platforms. For these older sites (typically pre-2.7.x), first, upgrade your site and its Extras (see below) to the latest MODX Revolution 2.8.x version. If you have any issues with the upgrade, please open a ticket from the Dashboard, and we’ll help you sort things out.
Please note: now is not the best time to also upgrade to MODX 3.0—tackle one thing at a time. Once your site runs successfully on the Gen2 platforms with PHP 7.4—which should just work for the vast majority of sites—you can then make a copy of your site and test upgrading to Revo 3.x and PHP 8.0.x or later.
Extras
The most common issue is needing to update Extras to their latest versions. You should install the Extra versions relevant to your installation as some of the more popular Extras now have versions specific to MODX Revolution 3. For users of the original TinyMCE, install TinyMCE RTE (the “RTE” bit is what’s important!) and uninstall the original TinyMCE Extra.
Hardcoded base URLs
MODX MODX sites use <base href="https://example.com"> tags in their site headers. Update them to use an uncached site_url system setting: <base href="[[!++site_url]]">. There is no performance penalty for doing this as that variable is maintained in memory for MODX websites.
Babel/Context Gateway plugins
If sites use Babel for multi-lingual websites, you need to make sure that you update your context settings to test the migrated site.
If you are migrating a site that has no custom domains and is using the default {http_host} in the site_url setting, then please update that to the URL provided for the migrated site. It can be changed back once the migration is complete.
MODX Cloud CDN/WAF add-ons
If you use our CDN/WAF add-on, then please contact us once you are happy to complete the migration. Instead of changing your DNS, we will point the origin in the CDN/WAF settings to the new IP address.
Image thumbnails not showing
Image thumbnails created using pThumb or phpThumb occasionally break on the front end after a migration. A manual cache clear from the MODX Manager resolves most of these cases.
For WordPress Installations
Database configuration (“Error establishing Database Connection”)
Migrations update the wp-config.php. Occasionally, you will need to manually update the configuration file with the new database credentials for the new site.
If you do not have a custom domain pointed at your Cloud, then there are two site settings you may need to change in the options table in the database.
siteurl: Set this to your newmodx.devURL.home: If you have this set, then as above, use themodx.devURL.
These settings can, preferably, be updated using the WordPress Admin or alternatively, directly in the database. An example query below would require replacing <site> with the modx.dev URL, you may also need to update the options table prefix:
UPDATE wp_options SET option_value = 'https://<site>' WHERE option_name IN ('siteurl', 'home');
For Custom Laravel Projects
Before you migrate, if you use .env instead of placing the database credentials in the configuration file, then retain a copy of that before migrating. The .env file will need to be put in place on the migrated site once it has been created.
Items Not Handled By the Migration Tool
File paths
Previously, absolute paths included the cloud instance ID and looked like the following:
/paas/c0987/www/
For new Gen2 platforms, the paths are more portable and simple to avoid changes when moving to other platforms. They would look like:
/www/
Crontab
If you have cron jobs for a site, this needs to be manually set up on the migrated site. You probably want to pause cron tasks during migrations so they don't double executions. There are some path differences on the Gen2 platforms (see above), so if there is a problem with executing on the new platforms, check that (or open a ticket).
Files Outside of Web Root (www)
Any sites outside of the /www/ directory will need to be copied manually to the migrated site.
HTTP Basic Authentication
If you are using HTTP basic auth and have a .htpasswd in place then this will need to be copied over to the migrated site once it has been created.