Importing a MODX Site with Rsync

Rsync is a utility which makes syncing files between two servers straight forward. The added benefit is future syncs only require sending the changes rather than the whole set of data. This is why we highly recommend using it for migrating large sites to MODX Cloud.

The high-level process to migrate a site manually is covered in detail in the MODX documentation. This guide will discuss the steps our team uses when migrating a MODX site from another host into Cloud using Rsync. The paths mentioned will assume the host is based on cPanel and the you have SSH access.

Create a Clean Site in MODX Cloud

To start, create a fresh MODX instance in Cloud. The instance needs to be the same version as your current site. The current site's version can be found in one of 3 ways:

1. Log in to the MODX Manager and view the MODX Version from either the top left or top right of the Manager UI.

2. From the file tree inside MODX, find and preview either of the following files, core/docs/version.inc.php or core/docs/changelog.txt.

3. From the the File Manager of the hosting control panel, find and preview either of the following files, core/docs/version.inc.php or core/docs/changelog.txt.

Backup the Database

You will need a backup of the database in order to proceed. You can retrieve a backup from cPanel or phpMyAdmin, however we highly recommend grabbing it via SSH. If you are unsure of your database credentials, you can retrieve those by running head -15 core/config/config.inc.php

Once you have the credentials you will run the following command in the base location of the site. For a typical cPanel site, this would be in the directory /home/<sitename>/public_html/.

mysqldump --add-drop-table -u <user> -p <db_name> > db.sql

Make sure to substitute the values for <user> and <db_name> with those found in your config file.

Create an Rsync Filter

While still SSH'd into your platform you will create a file called `rsync.filter`. Assuming your core folder is also present in base location of the site, your `rsync.filter` will look like:

+ /assets/ 
+ /assets/* 
+ /core/ 
+ /core/components/
+ /core/packages/ 
- /core/* 
- /core/packages/core/
- /core/packages/config.core.php 
- /cgi-bin/ 
- /manager/
- /phpmyadmin/ 
- /phpMyAdmin/ 
- /setup/ 
- /index.php
- /config.core.php 
- /connectors/config.core.php
- /rsync.filter 
- /rsync.exclude

You may need to edit or alter it for your specific use case.

Create an Rsync Exlude List

In the same location, you will need to create a file called `rsync.exclude`. This will be used to skip potentially any potentially harmful files or other things you wish to not sync.

.*.ico 
*.suspected 
*.bck 
*.bak 
wp-*.php 
opn-post.php 
dbs.php 
123.php

If you’re transferring a WordPress site, remove the wp-*.php from the excludes.list file.

Push the Files to MODX Cloud

Next you will run the actual `rsync` command to transfer your files to the MODX instance you created on Cloud.

rsync -azvvP --no-p ./ cXXXX@xxxx.modx.dev:/www/ --filter=". rsync.filter" --exclude-from 'rsync.exclude'

For Custom Core Locations / Names

If there is a custom core location, you need to get the files from the Source into Cloud. Change to the core directory location, and create another rsync.filter file within it with the following contents:

+ /components/ 
+ /packages/ 
- /* 
- /packages/core/ 
- /packages/config.core.php

Then execute the following `rsync`  command to get the core folder moved into Cloud:

rsync -azvvP --no-p ./ cXXXX@xxxx.modx.dev:/www/core/ --filter=". rsync.filter"

In certain cases where the source database is using the latin1 charset, you can use https://ftfy.readthedocs.io/en/latest/ to alter any characters that don't look right such as â€™ and similar

Import the DB into the Cloud Installation

SSH to the new Cloud instance and import the DB which will be located in `/home/www/` with the following command:

mysql -u cXXXX -p instance_cXXXX < db.sql

Make sure to adjust the values above to match your instance.

Confirm the Clone

You should now be able to log into your site at `https://xxxx.modx.dev/manager` to test your site. If you notice irregularities, it is recommended to click the "Reinstall MODX" button on your the Cloud Dashboard.

If you run into any issues that you are unsure how to resolve, please reach out to our support!