duplicate-installation.rst 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270
  1. Duplicate Installation
  2. ######################
  3. .. contents:: Contents
  4. :local:
  5. :depth: 2
  6. Introduction
  7. ============
  8. Why Duplicate an Elgg Installation?
  9. -----------------------------------
  10. There are many reasons you may want to duplicate an Elgg installation: moving the site to another server, creating a test or development server, and creating functional backups are the most common. To create a successful duplicate of an Elgg site, 3 things need to be copied:
  11. - Database
  12. - Data from the data directory
  13. - Code
  14. Also at least 5 pieces of information must be changed from the copied installation:
  15. - ``engine/settings.php`` file
  16. - ``.htaccess`` file (Apache) or Nginx configuration depending on server used
  17. - database entry for your site entity
  18. - database entry for the installation path
  19. - database entry for the data path
  20. What Is Not Covered in This Tutorial
  21. ------------------------------------
  22. This tutorial expects a basic knowledge of Apache, MySQL, and Linux commands. As such, a few things will not be covered in this tutorial. These include:
  23. - How to backup and restore MySQL databases
  24. - How to configure Apache to work with Elgg
  25. - How to transfer files to and from your production server
  26. Before You Start
  27. ----------------
  28. Before you start, make sure the Elgg installation you want to duplicate is fully functional. You will also need the following items:
  29. - A backup of the live Elgg database
  30. - A place to copy the live database
  31. - A server suitable for installing duplicate Elgg site
  32. (This can be the same server as your production Elgg installation.)
  33. Backups of the database can be obtained various ways, including phpMyAdmin, the MySQL official GUI, and the command line. Talk to your host for information on how to backup and restore databases or use Google to find information on this.
  34. During this tutorial, we will make these assumptions about the production Elgg site:
  35. - The URL is ``http://www.myelgg.org/``
  36. - The installation path is ``/var/www/elgg/``
  37. - The data directory is ``/var/data/elgg/``
  38. - The database host is ``localhost``
  39. - The database name is ``production_elgg``
  40. - The database user is ``db_user``
  41. - The database password is ``db_password``
  42. - The database prefix is ``elgg``
  43. At the end of the tutorial, our test Elgg installation details will be:
  44. - The URL is ``http://test.myelgg.org/``
  45. - The installation path is ``/var/www/elgg_test/``
  46. - The data directory is ``/var/data/elgg_test/``
  47. - The database host is ``localhost``
  48. - The database name is ``test_elgg``
  49. - The database user is ``db_user``
  50. - The database password is ``db_password``
  51. - The database prefix is ``elgg``
  52. Copy Elgg Code to the Test Server
  53. =================================
  54. The very first step is to duplicate the production Elgg code. In our example, this is as simple as copying ``/var/www/elgg/`` to ``/var/www/elgg_test/``.
  55. .. code::
  56. cp -a /var/www/elgg/ /var/www/elgg_test/
  57. Copy Data to the Test Server
  58. ============================
  59. In this example, this is as simple as copying ``/var/data/elgg/`` to ``/var/data/elgg_test/``.
  60. .. code::
  61. cp -a /var/data/elgg/ /var/data/elgg_test/
  62. If you don't have shell access to your server and have to ftp the data, you may need to change ownership and permissions on the files.
  63. .. note::
  64. You also need to delete the views cache on the test server after the copy process. This is a directory called ``views_simplecache`` in your data directory and the directory called ``system_cache`` .
  65. Edit engine/settings.php
  66. ========================
  67. The ``engine/settings.php`` file contains the database configuration details. These need to be adjusted for your new test Elgg installation. In our example, we'll look in ``/var/www/elgg_test/engine/settings.php`` and find the lines that look like this:
  68. .. code:: php
  69. // Database username
  70. $CONFIG->dbuser = 'db_user';
  71. // Database password
  72. $CONFIG->dbpass = 'db_password';
  73. // Database name
  74. $CONFIG->dbname = 'elgg_production';
  75. // Database server
  76. // (For most configurations, you can leave this as 'localhost')
  77. $CONFIG->dbhost = 'localhost';
  78. // Database table prefix
  79. // If you're sharing a database with other applications, you will want to use this
  80. // to differentiate Elgg's tables.
  81. $CONFIG->dbprefix = 'elgg';
  82. We need to change these lines to match our new installation:
  83. .. code:: php
  84. // Database username
  85. $CONFIG->dbuser = 'db_user';
  86. // Database password
  87. $CONFIG->dbpass = 'db_password';
  88. // Database name
  89. $CONFIG->dbname = 'elgg_test';
  90. // Database server
  91. // (For most configurations, you can leave this as 'localhost')
  92. $CONFIG->dbhost = 'localhost';
  93. // Database table prefix
  94. // If you're sharing a database with other applications, you will want to use this
  95. // to differentiate Elgg's tables.
  96. $CONFIG->dbprefix = 'elgg';
  97. .. note::
  98. Notice the ``$CONFIG->dbname`` has changed to reflect our new database.
  99. Copy Elgg Database
  100. ==================
  101. Now the database must be copied from ``elgg_production`` to ``elgg_test``. See your favorite MySQL manager's documentation for how to make a duplicate database. You will generally export the current database tables to a file, create the new database, and then import the tables that you previously exported.
  102. You have two options on updating the values in the database. You could change the values in the export file or you could import the file and change the values with database queries. One advantage of modifying the dump file is that you can also change links that people have created to content within your site. For example, if people have bookmarked pages using the bookmark plugin, the bookmarks will point to the old site unless your update their URLs.
  103. Database Entries
  104. ================
  105. We must now change 4 entries in the database. This is easily accomplished with 4 simple SQL commands:
  106. Change the installation path
  107. ----------------------------
  108. .. code:: sql
  109. UPDATE `elgg_datalists` SET `value` = "/var/www/elgg_test/" WHERE `name` = "path";
  110. Change the data directory
  111. -------------------------
  112. .. code:: sql
  113. UPDATE `elgg_datalists` SET `value` = "/var/data/elgg_test/" WHERE `name` = "dataroot";
  114. Change the site URL
  115. -------------------
  116. .. code:: sql
  117. UPDATE `elgg_sites_entity` SET `url` = "http://test.myelgg.org/";
  118. Change the filestore data directory
  119. -----------------------------------
  120. .. code:: sql
  121. UPDATE elgg_metastrings SET string = '/var/data/elgg_test/'
  122. WHERE id = (
  123. SELECT value_id
  124. FROM elgg_metadata
  125. WHERE name_id = (
  126. SELECT *
  127. FROM (
  128. SELECT id
  129. FROM elgg_metastrings
  130. WHERE string = 'filestore::dir_root'
  131. ) as ms2
  132. )
  133. LIMIT 1
  134. );
  135. .. warning::
  136. Only change the first path here!!
  137. Check .htaccess
  138. ===============
  139. If you have made changes to .htaccess that modify any paths, make sure you update them in the test installation.
  140. Update Webserver Config
  141. =======================
  142. For this example, you must edit the Apache config to enable a subdomain with a document root of ``/var/www/elgg_test/``. If you plan to install into a subdirectory of your document root, this step is unnecessary.
  143. If you're using Nginx, you need to update server config to match new paths based on ``install/config/nginx.dist``.
  144. Run upgrade.php
  145. ===============
  146. To regenerate cached data, make sure to run ``http://test.myelgg.org/upgrade.php``
  147. Tips
  148. ====
  149. It is a good idea to keep a test server around to experiment with installing new mods and doing development work. If you automate restorations to the ``elgg_test`` database, changing the ``$CONFIG`` values and adding the follow lines to the end of the ``elgg_test/engine/settings.php`` file will allow seamless re-writing of the MySQL database entries.
  150. .. code:: php
  151. $con = mysql_connect($CONFIG->dbhost, $CONFIG->dbuser, $CONFIG->dbpass);
  152. mysql_select_db($CONFIG->dbname, $con);
  153. $sql = "UPDATE {$CONFIG->dbprefix}datalists
  154. SET value = '/var/www/test_elgg/'
  155. WHERE name = 'path'";
  156. mysql_query($sql);
  157. print mysql_error();
  158. $sql = "UPDATE {$CONFIG->dbprefix}datalists
  159. SET value = '/var/data/test_elgg/'
  160. WHERE name = 'dataroot'";
  161. mysql_query($sql);
  162. print mysql_error();
  163. $sql = "UPDATE {$CONFIG->dbprefix}sites_entity
  164. SET url = 'http://test.myelgg.org/'";
  165. mysql_query($sql);
  166. $sql = "UPDATE {$CONFIG->dbprefix}metastrings
  167. SET string = '/var/data/elgg_test/'
  168. WHERE id = (
  169. SELECT value_id
  170. FROM {$CONFIG->dbprefix}metadata
  171. WHERE name_id = (
  172. SELECT *
  173. FROM (
  174. SELECT id
  175. FROM {$CONFIG->dbprefix}metastrings
  176. WHERE string = 'filestore::dir_root'
  177. ) as ms2
  178. )
  179. LIMIT 1
  180. )";
  181. mysql_query($sql);
  182. print mysql_error();
  183. Related
  184. =======
  185. .. seealso::
  186. :doc:`backup-restore`