backup-restore.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272
  1. Backup and Restore
  2. ##################
  3. .. contents:: Contents
  4. :local:
  5. :depth: 2
  6. Introduction
  7. ============
  8. Why
  9. ---
  10. Shared hosting providers typically don't provide an automated way to backup your Elgg installation. This article will address a method of accomplishing this task.
  11. In IT there are often many ways to accomplish the same thing. Keep that in mind. This article will explain one method to backup and restore your Elgg installation on a shared hosting provider that uses the CPanel application. However, the ideas presented here can be tailored to other applications as well. The following are typical situations that might require a procedure such as this:
  12. - Disaster Recovery
  13. - Moving your Elgg site to a new host
  14. - Duplicating an installation
  15. What
  16. ----
  17. Topics covered:
  18. - Full backups of the Elgg directories and MySQL databases are performed daily (automated)
  19. - The backups are sent to an off-site location via FTP (automated)
  20. - The local backups are deleted after successful transfer to the off-site location (automatic)
  21. - Five days of backups will be maintained (automated)
  22. - Restoration of data to the new host (manual)
  23. This process was composed with assistance from previous articles in the Elgg documentation wiki.
  24. Assumptions
  25. -----------
  26. The following assumptions have been made:
  27. - The Elgg program directory is ``/home/userx/public_html``
  28. - The Elgg data directory is ``/home/userx/elggdata``
  29. - You've created a local directory for your backups at ``/home/userx/sitebackups``
  30. - You have an off-site FTP server to send the backup files to
  31. - The directory that you will be saving the off-site backups to is ``/home/usery/sitebackups/``
  32. - You will be restoring the site to a second shared hosting provider in the ``/home/usery/public_html`` directory
  33. .. important::
  34. Be sure to replace ``userx``, ``usery``, ``http://mynewdomain.com`` and all passwords with values that reflect your actual installation!
  35. Creating a usable backup - automatically
  36. ========================================
  37. Customize the backup script
  38. ---------------------------
  39. The script that you will use can be found :doc:`here <backup/ftp-backup-script>` .
  40. Just copy the script to a text file and name the file with a .pl extension. You can use any text editor to update the file.
  41. Change the following to reflect your directory structure:
  42. .. code:: perl
  43. # ENTER THE PATH TO THE DIRECTORY YOU WANT TO BACKUP, NO TRAILING SLASH
  44. $directory_to_backup = '/home/userx/public_html';
  45. $directory_to_backup2 = '/home/userx/elggdata';
  46. # ENTER THE PATH TO THE DIRECTORY YOU WISH TO SAVE THE BACKUP FILE TO, NO TRAILING SLASH
  47. $backup_dest_dir = '/home/userx/sitebackups';
  48. Change the following to reflect your database parameters:
  49. .. code:: perl
  50. # MYSQL BACKUP PARAMETERS
  51. $dbhost = 'localhost';
  52. $dbuser = 'userx_elgg';
  53. $dbpwd = 'dbpassword';
  54. # ENTER DATABASE NAME
  55. $database_names_elgg = 'userx_elgg';
  56. Change the following to reflect your off-site FTP server parameters:
  57. .. code:: perl
  58. # FTP PARAMETERS
  59. $ftp_host = "FTP HOSTNAME/IP";
  60. $ftp_user = "ftpuser";
  61. $ftp_pwd = "ftppassword";
  62. $ftp_dir = "/";
  63. Save the file with the ``.pl`` extension (for the purposes of this article we will name the file: ``elgg-ftp-backup-script.pl``) and upload it to the following directory ``/home/userx/sitebackups``
  64. Be aware that you can turn off FTP and flip a bit in the script so that it does not delete the local backup file in the event that you don't want to use off-site storage for your backups.
  65. Configure the backup Cron job
  66. -----------------------------
  67. Login to your CPanel application and click on the "Cron Jobs" link. In the Common Settings dropdown choose "Once a day" and type the following in the command field ``/usr/bin/perl /home/userx/sitebackups/elgg-ftp-backup-script.pl``
  68. Click on the "Add New Cron Job" button. Daily full backups are now scheduled and will be transferred off-site.
  69. Configure the cleanup Cron job
  70. ------------------------------
  71. If you are sending your backups, via FTP, to another shared hosting provider that uses the CPanel application or you've turned off FTP altogether you can configure your data retention as follows.
  72. Login to your CPanel application for your FTP site, or locally if you're not using FTP, and click on the "Cron Jobs" link. In the Common Settings dropdown choose "Once a day" and type the following in the command field ``find /home/usery/sitebackups/full_* -mtime +4 -exec rm {} \;``
  73. The ``-mtime X`` parameter will set the number of days to retain backups. All files older than ``x`` number of days will be deleted. Click on the "Add New Cron Job" button. You have now configured your backup retention time.
  74. Restoring from backup
  75. =====================
  76. Prepare your backup files
  77. -------------------------
  78. The assumption is that you're restoring your site to another shared hosting provider with CPanel.
  79. When the script backed the files up the original directory structure was maintained in the zip file. We need to do a little cleanup. Perform the following:
  80. - Download the backup file that you wish to restore from
  81. - Extract the contents of the backup file
  82. - Drill down and you will find your site backup and SQL backup. Extract both of these. You will then have:
  83. - a MySQL dump file with a ``.sql`` extension
  84. - another directory structure with the contents of:
  85. - ``/home/userx/public_html``
  86. - ``/home/userx/elggdata``
  87. - Repackage the contents of the ``/home/userx/public_html`` directory as a zip file so that the files are in the root of the zip file
  88. - The reason for doing this is simple. It's much more efficient to upload one zip file than it is to ftp the contents of the ``/home/userx/public_html`` directory to your new host.
  89. - Repackage the contents of the /home/userx/elggdata directory as a zip file so that the files are in the root of the zip file
  90. You should now have the following files:
  91. - the ``.sql`` file
  92. - the zip file with the contents of ``/home/userx/public_html`` in the root
  93. - the zip file with the contents of ``/home/userx/elggdata`` in the root
  94. Restore the files
  95. -----------------
  96. This is written with the assumption that you're restoring to a different host but maintaining the original directory structure. Perform the following:
  97. - Login to the CPanel application on the host that you wish to restore the site to and open the File Manager.
  98. - Navigate to ``/home/usery/public_html``
  99. - Upload the zip file that contains the ``/home/userx/public_html`` files
  100. - Extract the zip file
  101. You should now see all of the files in ``/home/usery/public_html``
  102. - Delete the zip file
  103. - Navigate to ``/home/usery/elggdata``
  104. - Upload the zip file that contains the ``/home/userx/elggdata`` files
  105. - Extract the zip file
  106. You should now see all of the files in /home/usery/elggdata
  107. - Delete the zip file
  108. Program and data file restoration is complete
  109. Restore the MySQL Database
  110. --------------------------
  111. .. note::
  112. Again, the assumption here is that you're restoring your Elgg installation to a second shared hosting provider. Each shared hosting provider prepends the account holder's name to the databases associated with that account. For example, the username for our primary host is ``userx`` so the host will prepend ``userx_`` to give us a database name of ``userx_elgg``. When we restore to our second shared hosting provider we're doing so with a username of ``usery`` so our database name will be ``usery_elgg``. The hosting providers don't allow you to modify this behavior. So the process here isn't as simple as just restoring the database from backup to the usery account. However, having said that, it's not terribly difficult either.
  113. Edit the MySQL backup
  114. ---------------------
  115. Open the ``.sql`` file that you extracted from your backup in your favorite text editor. Comment out the following lines with a hash mark:
  116. .. code:: mysql
  117. #CREATE DATABASE /*!32312 IF NOT EXISTS*/ `userx_elgg` /*!40100 DEFAULT CHARACTER SET latin1 */;
  118. #USE `userx_elgg`;
  119. Save the file.
  120. Create the new database
  121. -----------------------
  122. Perform the following:
  123. - Login to the CPanel application on the new host and click on the "MySQL Databases" icon
  124. - Fill in the database name and click the "create" button. For our example we are going to stick with ``elgg`` which will give us a database name of ``usery_elgg``
  125. - You can associate an existing user with the new database, but to create a new user you will need to:
  126. - Go to the "Add New User" section of the "MySQL Databases" page
  127. - Enter the username and password. For our example we're going to keep it simple and use ``elgg`` once again. This will give us a username of ``usery_elgg``
  128. - Associate the new user with the new database
  129. - Go to the "Add User To Database" section of the "MySQL Databases" page. Add the ``usery_elgg`` user to the ``usery_elgg`` database
  130. - Select "All Privileges" and click the "Make Changes" button
  131. Restore the production database
  132. -------------------------------
  133. Now it's time to restore the MySQL backup file by importing it into our new database named "usery_elgg".
  134. - Login to the CPanel application on the new host and click on the "phpMyAdmin icon
  135. - Choose the ``usery_elgg`` database in the left hand column
  136. - Click on the "import" tab at the top of the page
  137. - Browse to the ``.sql`` backup on your local computer and select it
  138. - Click the "Go" button on the bottom right side of the page
  139. You should now see a message stating that the operation was successful
  140. Bringing it all together
  141. ------------------------
  142. The restored elgg installation knows **nothing** about the new database name, database username, directory structure, etc. That's what we're going to address here.
  143. Edit ``/public_html/engine/settings.php`` on the new hosting provider to reflect the database information for the database that you just created.
  144. .. code:: php
  145. // Database username
  146. $CONFIG->dbuser = 'usery_elgg';
  147. // Database password
  148. $CONFIG->dbpass = 'dbpassword';
  149. // Database name
  150. $CONFIG->dbname = 'usery_elgg';
  151. // Database server
  152. // (For most configurations, you can leave this as 'localhost')
  153. $CONFIG->dbhost = 'localhost';
  154. Upload the ``settings.php`` file back to the new host - overwriting the existing file.
  155. Open the phpMyAdmin tool on the new host from the CPanel. Select the ``usery_elgg`` database on the left and click the SQL tab on the top of the page. Run the following SQL queries against the ``usery_elgg`` database:
  156. Change the installation path
  157. .. code:: sql
  158. UPDATE `elgg_datalists` SET `value` = "/home/usery/public_html/grid/" WHERE `name` = "path";
  159. Change the data directory
  160. .. code:: sql
  161. UPDATE `elgg_datalists` SET `value` = "/home/usery/elggdata/" WHERE `name` = "dataroot";
  162. Change the site URL (if this has changed)
  163. .. code:: sql
  164. UPDATE `elgg_sites_entity` SET `url` = "http://mynewdomain.com";
  165. Change the filestore data directory
  166. .. code:: sql
  167. UPDATE elgg_metastrings set string = '/home/usery/elggdata/' WHERE id = (SELECT value_id from elgg_metadata where name_id = (SELECT * FROM (SELECT id FROM elgg_metastrings WHERE string = 'filestore::dir_root') as ms2) LIMIT 1);
  168. Finalizing the new installation
  169. -------------------------------
  170. Run the upgrade script by visiting the following URL: ``http://mynewdomain.com/upgrade.php`` . Do this step twice - back to back.
  171. Update your DNS records so that your host name resolves to the new host's IP address if this is a permanent move.
  172. Congratulations!
  173. ================
  174. If you followed the steps outlined here you should now have a fully functional copy of your primary Elgg installation.
  175. Related
  176. =======
  177. .. toctree::
  178. backup/ftp-backup-script
  179. duplicate-installation