Moodle migration
There may be times when you need to move your Moodle site from one server to another. For example, moving a Moodle site from shared hosting service's server to a dedicated server.
Recommended method
This involves moving a whole site from one server to another. If you are changing the domain/IP address to the new server you need to do these steps:
Turn on maintenance mode
Place your current Moodle site into Maintenance mode via Site Administration > Server > Maintenance Mode to prevent any further additions to the Moodle database. Don't let administrators login during the migration as they are not affected by the maintenance mode setting.
Backup the Moodle database on the old server
The right way to back up your database depends on which database system you are using. The instructions below are one way to back up a MySQL database. Another option would be to use a tool like phpMyAdmin to manually make a backup. The documentation for your database will give more options. There are many ways to do such backups. Here is an outline of a little script you can run from command line on Unix to backup the database:
cd /my/backup/directory mv moodle-database.sql.gz moodle-database-old.sql.gz mysqldump -h example.com -u myusername -p'mypassword' -C -Q -e --create-options mydatabasename > moodle-database.sql
If you only write "-p" without your password, you will be prompted for it.
Restore the database backup to the new server
Copy the database back up files to the new server and restore into the new database server.
Once you have created the new database on the new server:
mysql -p new_database < moodle-database.sql
For other databases, follow their instructions for restoring a backup.
Copy moodledata from the old server to the new server
Copy the contents of your data directory (check for the value in $CFG->dataroot
) to the new server. This can be a lot of data, so consider using a good data copying tool like rsync. If using an FTP client, the transfer of the filedir
folder must be in BINARY mode or the files will get corrupted in the process.
NB: It is not necessary to copy the contents of these directories:
- /moodledata/cache
- /moodledata/localcache
- /moodledata/sessions
- /moodledata/temp
- /moodledata/trashdir
Omitting these files will reduce transfer time substantially.
Check the file permissions of the copied files. The web server needs read and write access.
Copy the Moodle code from the old server to the new server
You will need to copy the Moodle code itself to the new server (this is the Moodle folder found in your webroot folder e.g. /var/www or public_html).
Check the file permissions of the copied files. The web server needs read access.
Update config.php with the URL of the new server
If the migration will move Moodle to a new URL, then update $CFG->wwwroot in config.php to point to the new location.
Also check the other properties there. Is the path $CFG->moodledata still correct? Do the database connection settings need to be changed? While you're at it, potentially consider making a new config.php from the latest config-dist.php, to give you more config override options in the future, should you need them.
Test the copied site
You should now be able to log into the new site as admin, and verify that most things are working.
Update links containing wwwroot in the database
The one thing we have not fixed is any internal links stored in the database. To fix these use the Search and replace tool by going to {wwwroot}/admin/tool/replace/index.php.
Enter the url for your old server (https://oldserver.com/) and new server (https://newserver.com/) and it will fix any links stored in the database.
Take the site out of maintenance mode
Test the migration some more, then when you are satisfied, remember to take the site out of maintenance mode.
Quick and hacky method
If you have shell access on both servers, here is a quick command-line based method.
- Set up a new empty database on the new server.
- Place your existing Moodle site into maintenance mode.
- Login to shell on the old existing server.
- Use rsync to copy moodledata and public_html or moodle folders (or whatever directory your Moodle install is in) to the new server - execute (replacing caps with your details; SOURCE = the directory you want to copy) for each directory:
rsync -av -e ssh SOURCE/ USERNAME@NEW_SERVER.COM:/PATH/TO/DESTINATION/
- Dump existing database and move and import into database on new server by executing:
mysqldump --allow-keywords --opt -uMySQL_USERNAME -pPASSWORD DATABASE | ssh USER@DOMAIN "mysql -uMySQL_USERNAME -pPASSWORD DATABASE"
- Replace any links in the database that contain the full site URL:
#sed -e 's/oldserver.com/newserver.com/g' oldmysqldump.sql > newmysqldump.sql
- On the new server, update config.php with relevant details where applicable (e.g. database name and user details, the wwwroot and the dataroot).
- Check ownership and permissions are correct on both moodle code and moodleData directories.
- Make sure everything is working.
Takes about 15 minutes for a small site. However, transferring several Gigabytes of data for a larger site can take hours depending on your network connection and hard drive read/write speed.
When you are happy all has gone well, set up redirects/make DNS changes if required, take new site out of maintenance mode and "switch off" old site.
- If you are switching the IP address from the old server to the new one, you will need to turn off the old server before firing up the new one to avoid IP addressing conflicts and confusion!
Other considerations
Upgrade Moodle at the same time?
While doing the work of migrating Moodle, you might want to upgrade Moodle to the latest version at the same time. On the other hand, if you do that, and something breaks, you won't be sure which change caused the problem, so the more cautious approach is to change one thing at a time, and test in between to verify that all is well.
Also consider PHP Versions - if you're looking to upgrade PHP as part of the process on the new server, then you'll have to make sure the Moodle Version you're copying across supports both the PHP Versions.
DNS & masquerading changes
You may have had to change the DNS entries for the new Moodle site. If you have done so, it will take some time for the changes to replicate, so be patient. If your server is located behind a firewall, you may also have to change your firewall rules to allow access to the new server. See the masquerading docs.
Internal and external access
If you have a set up where your Moodle site can be accessed via a network and via the internet, ensure you check that the new site can be accessed internally and externally.
reCAPTCHA
If you migrate to a new domain and have setup Email-based self-registration, you need to create new API-Keys at google. You will find the explanation and links to google in Email-based self-registration.
Other Documentation
One other thing to consider is to have a look at all the installation documents for everything you're going to migrate to - e.g. Webserver (Apache/Nginx/OpenLiteSpeed), MariaDB/MySQL, Redis cache store, Microsoft 365 and also the initial Moodle Installation Guide as more specific setup steps are present within each, but it'll also give you an idea as to what you may need to (re)setup on your new server as well.
See also
Any questions?
Please post in the Installing and upgrading help forum on moodle.org