1 files changed, 66 insertions, 0 deletions
diff --git a/docs/en/rst/installing/moving.rst b/docs/en/rst/installing/moving.rst
new file mode 100644
index 000000000..966acda07
--- /dev/null
+++ b/docs/en/rst/installing/moving.rst
@@ -0,0 +1,66 @@
+.. _moving:
+
+Moving Bugzilla Between Machines
+################################
+
+Sometimes it's necessary to take a working installation of Bugzilla and move
+it to new hardware. This page explains how to do that, assuming that you
+have Bugzilla's webserver and database on the same machine, and you are moving
+both of them.
+
+You are advised to install the same version of Bugzilla on the new
+machine as the old machine - any :ref:`upgrade <upgrading>` you also need to
+do can then be done as a separate step. But if you do install a newer version,
+things should still work.
+
+1. Shut down your Bugzilla by loading the front page, going to
+   :guilabel:`Administration` | :guilabel:`Parameters` | :guilabel:`General`
+   and putting some explanatory text into the :param:`shutdownhtml` parameter.
+
+2. Make a :ref:`backup <backups>` of the bugs database.
+
+3. On your new machine, install Bugzilla using the instructions at
+   :ref:`installing`. Look at the old machine if you need to know what values
+   you used for configuring e.g. MySQL.
+
+4. Copy the :file:`data` directory and the :file:`localconfig` file from the
+   old Bugzilla installation to the new one.
+
+5. If anything about your database configuration changed (location of the
+   server, username, password, etc.) as part of the move, update the
+   appropriate variables in :file:`localconfig`.
+
+6. If the new URL to your new Bugzilla installation is different from the old
+   one, update the :param:`urlbase` parameter in :file:`data/params.json`
+   using a text editor.
+
+7. Copy the database backup file from your old server to the new one.
+
+8. Create an empty ``bugs`` database on the new server. For MySQL, that would
+   look like this:
+
+   :command:`mysql -u root -p -e "CREATE DATABASE bugs DEFAULT CHARACTER SET utf8;"`
+
+9. Import your backup file into your new ``bugs`` database. Again, for MySQL:
+
+   :command:`mysql -u root -p bugs < $BACKUP_FILE_NAME`
+
+   If you get an error about "packet too large" or "MySQL server has gone
+   away", you need to adjust the ``max_allowed_packet`` setting in
+   your :file:`my.cnf` file (usually :file:`/etc/my.cnf`) file to match or
+   exceed the value configured in the same file in your old version of MySQL.
+
+   If there are *any* errors during this step, you have to work out what
+   went wrong, and then drop the database, create it again using the step
+   above, and run the import again.
+
+10. Run :file:`checksetup.pl` to make sure all is OK.
+    (Unless you are using a newer version of Bugzilla on your new server, this
+    should not make any changes.)
+
+    :command:`./checksetup.pl`
+
+11. Activate your new Bugzilla by loading the front page on the new server,
+    going to :guilabel:`Administration` | :guilabel:`Parameters` |
+    :guilabel:`General` and removing the text from the :param:`shutdownhtml`
+    parameter.