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 upgrade 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
   Administration | Parameters | General and putting some explanatory
   text into the shutdownhtml parameter.

2. Make a backup of the bugs database.

3. On your new machine, install Bugzilla using the instructions at
   Installation and Maintenance Guide. Look at the old machine if you
   need to know what values you used for configuring e.g. MySQL.

4. Copy the "data" directory and the "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 "localconfig".

6. If the new URL to your new Bugzilla installation is different
   from the old one, update the urlbase parameter in
   "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:

   **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:

   **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 "my.cnf" file (usually "/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 "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.)

    **./checksetup.pl**

11. Activate your new Bugzilla by loading the front page on the
    new server, going to Administration | Parameters | General and
    removing the text from the shutdownhtml parameter.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.