MODX Revolution keeps your content and configuration split across the database and a set of files, with core paths defined in core/config/config.inc.php and the small pointer files config.core.php, connectors/config.core.php, and manager/config.core.php. That architecture makes upgrades reliable, but only if you protect both halves before you touch anything. This guide walks through a zero-downtime upgrade workflow: clone the site to a staging subdomain, snapshot the database and files, run the upgrade there, then promote it live and automate future backups from your control panel.

Why You Should Never Upgrade the Live Site Directly

Running setup/ directly on production means any failed migration, incompatible Extra, or PHP mismatch happens in front of your visitors. A staging copy on a subdomain lets you validate the new MODX version and all your packages before flipping the switch. The rule is simple: verify every Extra is up to date and working before you upgrade the core, then test the whole thing on a clone.

Before starting, confirm which PHP version your MODX version supports. MODX 2.8.x runs well on PHP 8.0/8.1, while MODX 3.x is happy on PHP 8.2, 8.3, and 8.4. Never mix a legacy MODX build with a much newer PHP branch.

Step 1: Take a Database Snapshot

Find your database credentials inside core/config/config.inc.php (the $database_dbname, $database_user, and $table_prefix values). Export a full dump before anything else.

  • DirectAdmin: Log in → Account Manager → MySQL Management → click your database → use phpMyAdmin → Export tab → choose Quick and SQL format → Go. You can also grab a full account snapshot via Account Manager → Create/Restore Backups.
  • cPanel: Log in → Databases → phpMyAdmin → select the database → Export → Quick → SQL → Go. For a one-file archive of files + DB together, use Files → Backup → Download a Full Account Backup.

If you have SSH access on our Cloud VPS, a dump is even faster:

mysqldump -u db_user -p db_name > ~/modx-preupgrade-$(date +%F).sql

Step 2: Snapshot the MODX Files

Clear the cache first so you archive a clean tree. In the MODX Manager, go to the top menu → Manage → Clear Cache (in MODX 3 this is the wrench/site menu → Clear Cache). Then archive the whole document root.

  • DirectAdmin: Account Manager → File Manager → navigate to public_html → select all MODX folders → Compress to a .tar.gz.
  • cPanel: Files → File Manager → open public_html → Select All → Compress → Gzipped Tar Archive.

Keep both the SQL dump and the file archive off-server (download them). These two files are your rollback point.

Step 3: Build a Staging Subdomain

Create a subdomain like staging.yourdomain.com, copy the files into it, import the database, and repoint MODX's config.

  1. Create the subdomain
    • DirectAdmin: Account Manager → Subdomain Management → add staging.
    • cPanel: Domains → Domains / Subdomains → Create A New Domain → enter staging.yourdomain.com.
  2. Create a fresh database for staging (DirectAdmin: MySQL Management → Create Database; cPanel: Databases → MySQL Databases), then import your dump into it via phpMyAdmin.
  3. Copy the files from public_html into the staging document root using File Manager's Copy function.
  4. Update the config in the staging copy. Edit core/config/config.inc.php and change the site URL, path, and database name/user to the staging values. Also correct the paths inside config.core.php, connectors/config.core.php, and manager/config.core.php so they point to the staging core directory.
  5. Clear the staging cache by deleting everything inside core/cache/, then load staging.yourdomain.com/manager to confirm the clone works.

Step 4: Update Extras, Then the Core on Staging

Always update packages before the core. In the staging Manager go to Extras → Installer (in MODX 3, Applications → Installer). Open the Updates view and update each Extra, then test the site.

For the core upgrade, the cleanest route is the UpgradeMODX Extra, which shows available versions right on your dashboard. Install it from the Installer, then use its dashboard widget to download and apply the target version. If you prefer the manual method:

  1. Download the matching MODX distribution and merge (do not delete-and-replace) the core, manager, connectors, and setup folders into the staging site.
  2. Set the setup directory permissions correctly:
find setup/ -type d -exec chmod 755 {} \;
find setup/ -type f -exec chmod 644 {} \;

Then browse to staging.yourdomain.com/setup and run the wizard. Confirm core/config/config.inc.php ends up at CHMOD 644. When finished, use the wizard's final option to remove the setup directory so nobody can re-run it. Clear your browser cache and re-check the front end and Manager.

If you manage plugins across multiple platforms, the same discipline applies everywhere — the golden rule of plugin management (update on staging, verify, then promote) maps perfectly onto MODX Extras.

Step 5: Promote Staging to Production

Once staging passes testing, promote it during a low-traffic window:

  1. Put the live site into maintenance briefly (System Setting site_status set to 0, or a holding page).
  2. Take one final fresh dump of the live database in case editors added content since your first snapshot.
  3. Copy the upgraded staging files over the live document root, then export the staging database and import it into the live database.
  4. Restore the live config values (site URL, paths, live DB credentials) in config.inc.php and the three config.core.php pointer files.
  5. Delete everything in core/cache/, set site_status back to 1, and clear the cache from the Manager.

Because visitors never saw the upgrade run, there's effectively no downtime beyond the short cut-over. On our LiteSpeed stack with native Redis object caching, flush LSCache/Redis after the cut-over so old fragments don't linger.

Step 6: Automate Ongoing Backups with Cron

Snapshots are only useful if they happen regularly. Schedule a nightly backup with a cron job.

  • DirectAdmin: Advanced Features → Cron Jobs → set the schedule → paste your command → Add.
  • cPanel: Advanced → Cron Jobs → choose Common Settings (e.g. Once Per Day) → paste the command → Add New Cron Job.

A simple daily backup command that dumps the database and archives the files, keeping the last seven days:

0 3 * * * cd ~ && mysqldump -u db_user -p'db_pass' db_name | gzip > ~/backups/modx-db-$(date +\%F).sql.gz && tar -czf ~/backups/modx-files-$(date +\%F).tar.gz -C ~/public_html . && find ~/backups -type f -mtime +7 -delete

Create the ~/backups folder first via File Manager. For anything beyond a small brochure site, store copies off-server (a remote bucket or a second host) so a single-server failure can't take your backups with it. Sites with heavier editorial workflows on Shared Hosting benefit from pairing this cron with the panel's built-in account backup for redundancy.

Troubleshooting the Upgrade

  • Blank or broken Manager after upgrade: usually permissions on JS files. Set chmod 755 on manager/index.php, connectors/index.php, connectors/modx.config.js.php, and connectors/lang.js.php, then clear cache.
  • Setup won't write config: make sure core/config/ and core/cache/ are writable by PHP before running setup/.
  • White screen on the front end: delete everything in core/cache/ and check the install log at core/cache/logs/.
  • PHP fatal errors after upgrade: confirm your PHP branch matches the MODX version in the PHP Selector.

FAQs

Do I need SSH to upgrade MODX safely?

No. You can complete the entire workflow through phpMyAdmin, File Manager, and the setup wizard in both DirectAdmin and cPanel. SSH just makes dumps and file copies faster on larger sites.

Which PHP version should I run for MODX 3?

MODX 3.x runs cleanly on PHP 8.2, 8.3, and 8.4. Set it in DirectAdmin under Extra Features → Select PHP Version, or in cPanel under Software → Select PHP Version. Test on staging before changing the live version.

How often should automated backups run?

Daily is the baseline for a content site; for busy stores or frequently edited sites, run database dumps more often and keep at least a week of rolling copies stored off-server.