Migrating or Importing a MODX Website from cPanel

Introduction

This guide walks you through the process of migrating your MODX Revolution site from a cPanel hosting environment to MODX Cloud. Following these steps will help ensure a smooth transition with minimal downtime.

Overview of Migration Steps

1. Check your current MODX version in Manager
2. Create a blank MODX Revolution site in MODX Cloud with matching version
3. Extract your site files and database from cPanel
4. Import your database to MODX Cloud
5. Upload your site files to MODX Cloud
6. Update configuration settings
7. Reinstall Product to clear the cache
8. Verify your site functionality and back it up
9. Upgrade to the latest MODX version (recommended)
10. Clean up temporary files and tools
11. Point your DNS to the MODX Cloud instance

Detailed Instructions

1. Check Your Current MODX Version

Before beginning the migration process, you need to identify the exact version of MODX Revolution you're currently running:

1. Log in to your MODX Manager on your source site
2. Look at the bottom-right corner of the screen where it displays "MODX Revolution x.x.x-pl"
3. Note this version number, as you'll need to match it exactly when creating your MODX Cloud instance
4. If you can't access the Manager, you can also check the core/docs/version.inc.php file for this information

2. Create a New MODX Cloud Instance

1. Log in to your MODX Cloud account
2. Click "Create New Cloud"
3. Important: From the right side of the New Cloud screen, click "Change Version" to select the same version of MODX Revolution you identified in step 1
4. Complete the setup by following the on-screen prompts

3. Extracting Your Site from cPanel

Exporting Your Database

1. Log in to your cPanel account
2. Navigate to the "Databases" section and open phpMyAdmin
3. Select your MODX database from the left sidebar
4. Click the "Export" tab at the top of the page
5. Choose "Custom" export method for more options
6. Ensure the following settings are selected:
   • Format: SQL
   • Include "DROP TABLE" statements (important)
   • Add CREATE DATABASE / USE statement
   • "Structure" and "Data" should both be selected
7. Click "Go" to download the SQL file to your computer

Downloading Your Site Files

Method 1: Using cPanel File Manager:

1. In cPanel, open "File Manager"
2. Navigate to your site's root directory
3. Select all necessary folders (typically public_html or www)
4. Click "Compress" and choose ZIP format
5. Once compression is complete, download the ZIP file to your computer

Method 2: Using FTP/SFTP:

1. Use an SFTP client like FileZilla, Cyberduck, or WinSCP
2. Connect to your cPanel server using your FTP credentials
3. Download the following directories:
   • Your entire assets folder
   • core/components/
   • core/packages/ (but do NOT include core.transport.zip)
   • Any custom files like favicon.ico or .htaccess files you need
4. Delete or rename the core/config/config.inc.php and config.core.php files as they will conflict with the ones in your new Cloud instance. 

4. Import Your Database to MODX Cloud

1. From the "Summary" tab under MySQL click "Show Details" to view your MySQL credentials
2. Click the "Open phpMyAdmin" button at the right of the MySQL section to launch it in a new tab
3. Log in using the MySQL credentials provided
4. Click on the database name in the left sidebar
5. Select the "Import" tab
6. Click "Choose File" and select your SQL export file
7. Click "Go" to begin the import process

5. Upload Your Files to MODX Cloud

1. From Cloud instance Edit View, go to the "Summary" tab to find your SFTP credentials
2. Connect to your MODX Cloud instance using an SFTP client
3. Upload the following directories from your downloaded site files:
   • All assets folders
   • core/components/
   • core/packages/ (WARNING: Do NOT overwrite core.transport.zip or core/packages/core/ folder)
   • Any custom files (favicons, etc.)

6. Reinstall Product

1. Return to your MODX Cloud Dashboard
2. Click the "Reinstall Product" button in the sidebar
3. This will clear your cache and ensure all MODX files are in the correct locations

7. Confirm Your Site Works and Take a Snapshot

1. Access your site using the temporary URL provided by MODX Cloud
2. Verify all pages, assets, and functionality work as expected
3. Take a (Complete) Snapshot from your MODX Cloud Dashboard (Recommended in case changes or the upgrade in step 8 breaks your site)
4. Name it something descriptive like "Successful Import from 2.x.x" (where 2.x.x is your source version)

8. Upgrade to the Latest Version (Recommended)

1. Use your Snapshot as a safety net
2. Consider creating a clone for testing the upgrade process
3. If upgrading from 2.2.x or earlier:
   • First upgrade to 2.3.x
   • Then to 2.4.x
   • Finally to the latest version
4. After upgrading, update all Extras using the Package Manager in the MODX Manager

10. Cleanup

1. Delete any SQL dump files from your server
2. Remove any temporary .htaccess files (MODX Cloud uses NGINX web rules)
3. Delete any test/clone instances once you're satisfied with the migration

11. Launch Your MODX Cloud Site

A. Add Custom Domain(s)

1. Go to the Cloud Edit Page and select the Domains & Config tab
2. Click Add Domain to open a dialog for entering details
3. Enter your domain name in the Name field
4. Click Add a Domain
5. Repeat for any additional domains you want to point to this Cloud

B. Activate Live Production Site

1. After adding all your Custom Domains, stay on the Domains & Config tab
2. Click the toggle at the top right of the tab to activate this site as a Live Production Site
3. Proceed through checkout if prompted (note: this may add to your subscription if you've already used your plan's included Live Sites)

C. Point Your Domain to MODX Cloud

1. From your MODX Cloud Dashboard, note the public IP address shown on the Summary tab
2. Log in to your domain registrar or DNS provider
3. Set the A record for @ (representing the root domain) to the IP address you copied
4. Depending on your TTL settings, DNS propagation may take from a few minutes to 24 hours

Read more about Adding Domains or Launching Your Website. 

Troubleshooting Common Issues

Database Connection Issues

• Verify your database name, user, and password in core/config/config.inc.php
• Check that all tables have the correct prefix (should be "modx_")

Missing Content or Broken Pages

• Ensure all assets were properly uploaded
• Check for any hardcoded paths in your templates or content
• Clear the site cache through the MODX Manager or by using "Reinstall Product"

File Permission Problems

• MODX Cloud handles file permissions automatically
• If you experience issues, contact MODX Cloud support

Need Help?

If you encounter difficulties during migration, we're here to help:

• Contact MODX Cloud support
• Remember that the MODX Cloud team can migrate your first site for free (some exceptions for complex sites)

For additional assistance, contact us using the Help button in the MODX Cloud Dashboard.