Difference between revisions of "Moodle migration"

Jump to: navigation, search

Note: You are currently viewing documentation for Moodle 3.3. Up-to-date documentation for the latest stable version of Moodle is probably available here: Moodle migration.

(Migrating a complete Moodle site - method 1: Search and replace tool)
Line 2: Line 2:
 
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.
 
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.
  
:''Tip:'' One common migration mistake is to forget to update the details in the migrated Moodle's ''[[Configuration file|config.php]]'' file.
+
==Recommended method==
  
==Migrating a complete Moodle site - method 1==
+
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]] 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.
  
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:
+
===Backup the Moodle database on the old sever===
* '''Maintenance mode'''. Place your current Moodle site into [[Maintenance mode]] 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 your current Moodle database'''. 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:
+
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:
<pre>cd /my/backup/directory
+
 
 +
<pre>
 +
cd /my/backup/directory
 
mv moodle-database.sql.gz moodle-database-old.sql.gz
 
mv moodle-database.sql.gz moodle-database-old.sql.gz
mysqldump -h example.com -u myusername --password=mypassword -C -Q -e --create-options mydatabasename > moodle-database.sql</pre>
+
mysqldump -h example.com -u myusername --password=mypassword -C -Q -e --create-options mydatabasename > moodle-database.sql
* '''Change your Moodle URL'''. If you have a new URL, you'll need to change this in the Moodle database to the new server. This is needed as links to pictures, files, etc are stored as absolute links and will reference the old <code>$CFG->wwwroot</code> value. So when loading a mysql backup dump of the Moodle server into mysql on another server the absolute referenced links will be broken. There are two methods of doing this:
+
</pre>
:(a) The first method changes the Moodle URL using the [[Search and replace tool]] while your site is currently running, backing up the Moodle database before and after.
 
  
:Enter the url for your old server (<nowiki>http://oldserver.com/</nowiki>) and new server (<nowiki>http://newserver.com/</nowiki>) and it will fix the mysql tables. You will also need to clear out any cached links by restarting your webserver. Now, take another backup of the Moodle database - this one will have the correct URLs.
+
=== Restore the database backup to the new server ===
  
:(b) The second method is to backup the Moodle database first, then use the search and replace feature of your text editor (or use a unix tool like sed) to replace the old URL with the new one in the mysql backup file. Here is an example sed command:
+
Copy the database back up files to the new server and restore into the new database server.
  
: <code>#sed -e 's/oldserver.com/newserver.com/g' oldmysqldump.sql > newmysqldump.sql</code>
+
Once you have created the new database on the new server:
  
:''NOTE:'' This second method will not replace text in blocks because they are stored base64 encoded in the database, so any links in blocks will not be fixed. Therefore you should consider using the replace tool after you migrate if you use this second method.
 
:''TIP:'' You may want to check the mysqldump file to see how the old server was referenced.
 
:After changing the URL, restore the mysql database
 
*'''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:
 
 
<pre>mysql -p new_database < moodle-database.sql</pre>
 
<pre>mysql -p new_database < moodle-database.sql</pre>
:For other databases, follow their instructions for restoring a backup.
 
* '''Copy the Moodle software'''. 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).  If you want you can upgrade the code to the latest version at this point by downloading the latest code from the Moodle site, copying over your config.php file and any plugins that you might have installed.  See [[Upgrading]].
 
* '''If you are changing the url or the new server has a different ip address, you will need to change <code>$CFG->wwwroot</code>'''. In your (possibly new) Moodle directory, change the <code>$CFG->wwwroot</code> variable in the ''config.php'' file for the new server.
 
* '''Copy data directory contents (moodledata)'''. Copy the contents of your data directory (check for the value in <code>$CFG->dataroot</code>) to the new server. If you'll use an FTP client, the transfer of the <code>filedir</code> folder must be in '''BINARY''' mode or the files will get corrupted in the process.
 
* '''Review moodledata permissions and ownership'''. Check also that ownership and permissions remain the same on the new dataroot folder and change the value if you have changed its location on the new server.  Do the same for the new moodle code folder.
 
* '''Test the migration'''. To test the new install, access Moodle using your browser and the new server's URL. When you have tested that a number of links in the courses work, take the new Moodle site out of maintenance mode.  If you have upgraded the Moodle code, you will go through the upgrade process when you first access the site.
 
'''See also''': Forum discussion on [http://moodle.org/mod/forum/discuss.php?d=85812 migrating Moodle's data directory on a Windows system].
 
  
==Migrating a complete Moodle site - method 2==
+
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 <code>$CFG->dataroot</code>) 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 <code>filedir</code> folder must be in '''BINARY''' mode or the files will get corrupted in the process.
 +
 
 +
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?
 +
 
 +
===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 databse===
 +
 
 +
The one thing we have not fixed is any internal links stored in the database. To fix these use the [[Search and replace tool]] buy going to {wwwroot}/admin/tool/replace/index.php.
 +
 
 +
Enter the url for your old server (<nowiki>http://oldserver.com/</nowiki>) and new server (<nowiki>http://newserver.com/</nowiki>) 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==
  
Do you have shell access on both servers? If so, the following method is a very quick and efficient method to migrate a Unix based site.
+
If you have shell access on both servers, here is a quick command-line based method.
  
It is also useful for creating snapshots or test sites.
 
 
*Set up a new empty database on the '''new''' server.
 
*Set up a new empty database on the '''new''' server.
 
*Place your existing Moodle site into maintenance mode.
 
*Place your existing Moodle site into maintenance mode.
Line 47: Line 73:
 
*Dump existing database and move and import into database on new server by executing:
 
*Dump existing database and move and import into database on new server by executing:
 
::<code>mysqldump --allow-keywords --opt -uMySQL_USERNAME -pPASSWORD DATABASE | ssh USER@DOMAIN "mysql -uMySQL_USERNAME -pPASSWORD DATABASE"</code>
 
::<code>mysqldump --allow-keywords --opt -uMySQL_USERNAME -pPASSWORD DATABASE | ssh USER@DOMAIN "mysql -uMySQL_USERNAME -pPASSWORD DATABASE"</code>
 +
*Replace any links in the database that contin the full site URL:
 +
::<code>#sed -e 's/oldserver.com/newserver.com/g' oldmysqldump.sql > newmysqldump.sql</code>
 
*On the '''new server''', update '''config.php''' with relevant details where applicable (e.g. database name and user details, the wwwroot and the dataroot).
 
*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.
 
*Check ownership and permissions are correct on both moodle code and moodledata directories.
*To fix any internal Moodle links, login to your "new" Moodle install on your new server and use the [[Search and replace]] admin tool to search and replace the old url for the new one in the database.
 
 
*Make sure everything is working.
 
*Make sure everything is working.
  
Line 58: Line 85:
 
*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!
 
*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 points to consider==
+
==Other considerations==
===Changed URL image links set to old site===
 
So you built your Moodle Server with a <nowiki>http//192.168.0.1/Moodle</nowiki> address. Then you changed the URL for your site to <nowiki>http://OurMoodle.org/Moodle</nowiki>. You changed the Moodle config file so the CFGs point to the new paths,  but your images still point to the old url. 
 
 
 
One simple, quick solution is to use the Replace script in Moodle to fix this. Login as admin and enter  <nowiki>http://OurMoodle.org/admin/tool/replace/index.php</nowiki> in your browser address bar (or  <nowiki>http://OurMoodle.com/admin/replace.php</nowiki> in older versions). Use the two form boxes to change <nowiki>http://192.168.0.1/</nowiki> to <nowiki>http://OurMoodle.org/</nowiki>.
 
 
 
This replace function is only supported on Moodle sites that run on MySQL or Postgres databases. See MDL-26597 and MDL-35099.
 
 
 
===Upgrade Moodle===
 
 
 
When migrating Moodle it is often a good idea to take the opportunity to upgrade Moodle to the latest version. If you manage your own server, follow the instructions in [[Upgrading | upgrading moodle]], otherwise check if your host can upgrade for you.
 
 
 
===Restoring a single course across servers===
 
  
You may need to restore a single course from an old site to a new one, especially if you are testing the migration. When restoring a Moodle backup file to Moodle on a different server than the one used to create the backup, the absolute referenced links to files maybe broken. To fix this problem open the ''backup-coursename.zip'' file and edit the ''moodle.xml'' file replacing links with <code>$@FILEPHP@$</code>.
+
===Upgrade Moodle at the same time?===
  
For example, replace <nowiki>http://yourserver.com/file.php/243/</nowiki> with <code>$@FILEPHP@$</code>
+
While doing the work of migrating Moodle, you might want to [[Upgrading | 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.
 
When the file is restored it will use the correct file path for the new course.
 
  
===DNS & Masquerading changes===
+
===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 | masquerading docs]].
 
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 | masquerading docs]].
Line 91: Line 104:
 
* [[Site restore]]
 
* [[Site restore]]
 
* [[Backup and restore FAQ]]
 
* [[Backup and restore FAQ]]
* [http://tracker.moodle.org/browse/MDL-35099 Convert hidden search/replace script into a proper core admin tool] Tracker issue
 
  
 
Using Moodle forum discussions:
 
Using Moodle forum discussions:
Line 100: Line 112:
 
* [http://moodle.org/mod/forum/discuss.php?d=111807 Migrated Moodle to New Server But Can't Login]
 
* [http://moodle.org/mod/forum/discuss.php?d=111807 Migrated Moodle to New Server But Can't Login]
 
* [http://moodle.org/mod/forum/discuss.php?d=228436 Replace script returns "Service Unavailable"]
 
* [http://moodle.org/mod/forum/discuss.php?d=228436 Replace script returns "Service Unavailable"]
 +
* [http://moodle.org/mod/forum/discuss.php?d=85812 migrating Moodle's data directory on a Windows system]
  
 
[[es:Migración de Moodle]]
 
[[es:Migración de Moodle]]

Revision as of 06:48, 15 September 2015

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 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 sever

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 --password=mypassword -C -Q -e --create-options mydatabasename > moodle-database.sql

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.

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?

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 databse

The one thing we have not fixed is any internal links stored in the database. To fix these use the Search and replace tool buy going to {wwwroot}/admin/tool/replace/index.php.

Enter the url for your old server (http://oldserver.com/) and new server (http://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 contin 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.

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.

See also

Using Moodle forum discussions: