Bug 1067416 - reorganize and update Bugzilla docs

32 files changed, 2523 insertions, 0 deletions

diff --git a/docs/en/rst/installing/apache-windows.rst b/docs/en/rst/installing/apache-windows.rst
new file mode 100644
index 000000000..5e8ac8928
--- /dev/null
+++ b/docs/en/rst/installing/apache-windows.rst
@@ -0,0 +1,128 @@
+.. _apache-windows:
+
+Apache
+######
+
+These instructions require editing the Apache configuration file, which is
+at :file:`C:\\Program Files\\Apache Group\\Apache2\\conf\\httpd.conf`.
+
+Installing
+==========
+
+Download the Apache HTTP Server, version 2.2.x or higher, from
+`the Apache website <http://httpd.apache.org/download.cgi>`_.
+
+Apache uses a standard Windows installer. Just follow the prompts, making sure
+you "Install for All Users". Be aware the Apache will always install itself
+into an :file:`Apache2` directory under what ever path you specify. The
+default install path will be displayed as
+:file:`C:\\Program Files\\Apache Group`, which will result in Apache being
+installed to :file:`C:\\Program Files\\Apache Group\\Apache2`.
+
+If you are already running IIS on your machine, you must configure Apache to
+run on a port other than 80, which IIS is using. However you aren't asked the
+port to listen on at install time. Choose "All Users" (which says port 80),
+and we'll change the port later.
+
+The remainder of this document assumes you have installed Apache into
+the default location, :file:`C:\\Program Files\\Apache Group\\Apache2`.
+
+Apache Account Permissions
+==========================
+
+By default Apache installs itself to run as the SYSTEM account. For security
+reasons it's better the reconfigure the service to run as an Apache user.
+Create a new Windows user that is a member of **no** groups, and reconfigure
+the Apache2 service to run as that account.
+
+Whichever account you are running Apache as, SYSTEM or otherwise, needs write
+and modify access to the following directories and all their subdirectories.
+Depending on your version of Windows, this access may already be granted.
+
+* :file:`C:\\Bugzilla\\data`
+* :file:`C:\\Program Files\\Apache Group\\Apache2\\logs`
+* :file:`C:\\Temp`
+* :file:`C:\\Windows\\Temp`
+
+Note that :file:`C:\\Bugzilla\\data` is created the first time you run
+:file:`checksetup.pl`.
+
+Port and DocumentRoot
+=====================
+
+Edit the Apache configuration file (see above).
+
+If you need to change the port that Apache runs on (listens on, or binds to),
+for example because another web server such as IIS is running on the same
+machine, edit the ``Listen`` option and change the value after the colon.
+
+Change the ``DocumentRoot`` setting to point to :file:`C:/Bugzilla`. There
+are two locations in :file:`httpd.conf` that need to be updated (search for
+``DocumentRoot``). You need to use ``/`` instead of ``\`` as a path separator.
+
+Enable CGI Support
+==================
+
+Edit the Apache configuration file (see above).
+
+To enable CGI support in Apache, you need to enable the CGI handler, by
+uncommenting the ``AddHandler cgi-script .cgi`` line.
+
+Teach Apache About Bugzilla
+===========================
+
+Edit the Apache configuration file (see above).
+
+Add the following stanza:
+
+.. code-block:: apache
+
+   <Directory "C:/Bugzilla">
+       ScriptInterpreterSource Registry-Strict
+       Options +ExecCGI +FollowSymLinks
+       DirectoryIndex index.cgi index.html
+       AllowOverride Limit FileInfo Indexes Options
+   </Directory>
+
+In order for ``ScriptInterpreterSource Registry-Strict`` to work, you also
+need to add an entry to the Registry so Apache will use Perl to execute .cgi
+files.
+
+Create a key ``HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command`` with the
+default value of the full path of :file:`perl.exe` with a ``-T`` parameter.
+For example :file:`C:\\Perl\\bin\\perl.exe -T`.
+
+Logging
+=======
+
+Unless you want to keep statistics on how many hits your Bugzilla install is
+getting, it's a good idea to disable logging by commenting out the
+``CustomLog`` directive in the Apache config file.
+
+If you don't disable logging, you should at least disable logging of "query
+strings". When external systems interact with Bugzilla via webservices
+(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL
+(in the query string). Therefore, to avoid storing passwords in clear text
+on the server we recommend configuring Apache to not include the query string
+in its log files.
+
+#. Find the following line in the Apache config file, which defines the
+   logging format for ``vhost_combined``:
+
+   .. code-block:: apache
+
+      LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined
+
+#. Replace ``%r`` with ``%m %U``.
+
+(If you have configured Apache differently, a different log line might apply.
+Adjust these instructions accordingly.)
+
+Restart Apache
+==============
+
+Finally, restart Apache to get it pick up the changes:
+
+:command:`net stop apache2`
+
+:command:`net start apache2`
diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst
new file mode 100644
index 000000000..fe734b222
--- /dev/null
+++ b/docs/en/rst/installing/apache.rst
@@ -0,0 +1,137 @@
+.. This document is shared among all non-Windows OSes.
+
+.. _apache:
+
+Apache
+######
+
+You have two options for running Bugzilla under Apache - mod_cgi (the
+default) and mod_perl. mod_perl is faster but takes more resources. You
+should probably only consider mod_perl if your Bugzilla is going to be heavily
+used.
+
+These instructions require editing the Apache configuration file, which is:
+
+* Fedora/Red Hat: :file:`/etc/httpd/conf/httpd.conf`
+* Debian/Ubuntu: :file:`/etc/apache2/apache2.conf`
+* Mac OS X: :file:`/etc/apache2/httpd.conf`
+
+Alternatively, on Debian or Ubuntu, you can instead put the below code into a
+separate file in the directory :file:`/etc/apache2/sites-enabled/`.
+
+In these instructions, when asked to restart Apache, the command is:
+
+:command:`sudo apachectl start`
+
+(or run it as root if your OS installation does not use sudo).
+
+Securing Apache
+===============
+
+When external systems interact with Bugzilla via webservices
+(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL
+(in the "query string"). Therefore, to avoid storing passwords in clear text
+on the server we recommend configuring Apache to not include the query string
+in its log files.
+
+#. Edit the Apache configuration file (see above).
+
+#. Find the following line in the above mentioned file, which defines the
+   logging format for ``vhost_combined``:
+
+   .. code-block:: apache
+
+      LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined
+
+#. Replace ``%r`` with ``%m %U``.
+
+#. Restart Apache.
+
+.. _apache-mod_cgi:
+
+Apache with mod_cgi
+===================
+
+To configure your Apache web server to work with Bugzilla while using
+mod_cgi, do the following:
+
+#. Edit the Apache configuration file (see above).
+
+#. Create a ``<Directory>`` directive that applies to the location
+   of your Bugzilla installation. In this example, Bugzilla has
+   been installed at :file:`/var/www/html/bugzilla`. On Mac OS X, use
+   :file:`/Library/WebServer/Documents/bugzilla`.
+
+.. code-block:: apache
+
+   <Directory /var/www/html/bugzilla>
+     AddHandler cgi-script .cgi
+     Options +ExecCGI +FollowSymLinks
+     DirectoryIndex index.cgi index.html
+     AllowOverride Limit FileInfo Indexes Options
+   </Directory>
+
+These instructions allow Apache to run .cgi files found within the Bugzilla
+directory; instructs the server to look for a file called :file:`index.cgi`
+or, if not found, :file:`index.html` if someone only types the directory name
+into the browser; and allows Bugzilla's :file:`.htaccess` files to override
+some global permissions.
+
+.. _apache-mod_perl:
+
+Apache with mod_perl
+====================
+
+Some configuration is required to make Bugzilla work with Apache
+and mod_perl.
+
+.. note:: It is not known whether anyone has even tried mod_perl on Mac OS X.
+
+#. Edit the Apache configuration file (see above).
+
+#. Add the following information, substituting where appropriate with your
+   own local paths.
+
+   .. code-block:: apache
+
+       PerlSwitches -w -T
+       PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
+
+   .. note:: This should be used instead of the <Directory> block
+      shown above. This should also be above any other ``mod_perl``
+      directives within the :file:`httpd.conf` and the directives must be
+      specified in the order above.
+
+   .. warning:: You should also ensure that you have disabled ``KeepAlive``
+      support in your Apache install when utilizing Bugzilla under mod_perl
+      or you may suffer a
+      `performance penalty <http://modperlbook.org/html/11-4-KeepAlive.html>`_.
+
+On restarting Apache, Bugzilla should now be running within the
+mod_perl environment.
+
+Please bear the following points in mind when considering using Bugzilla
+under mod_perl:
+
+* mod_perl support in Bugzilla can take up a HUGE amount of RAM - easily
+  30MB per httpd child. The more RAM you can get, the better. mod_perl is
+  basically trading RAM for speed. At least 2GB total system RAM is
+  recommended for running Bugzilla under mod_perl.
+  
+* Under mod_perl, you have to restart Apache if you make any manual change to
+  any Bugzilla file. You can't just reload--you have to actually
+  *restart* the server (as in make sure it stops and starts
+  again). You *can* change :file:`localconfig` and the :file:`params` file
+  manually, if you want, because those are re-read every time you load a page.
+
+* You must run in Apache's Prefork MPM (this is the default). The Worker MPM
+  may not work -- we haven't tested Bugzilla's mod_perl support under threads.
+  (And, in fact, we're fairly sure it *won't* work.)
+
+* Bugzilla generally expects to be the only mod_perl application running on
+  your entire server. It may or may not work if there are other applications also
+  running under mod_perl. It does try its best to play nice with other mod_perl
+  applications, but it still may have conflicts.
+
+* It is recommended that you have one Bugzilla instance running under mod_perl
+  on your server. Bugzilla has not been tested with more than one instance running.
diff --git a/docs/en/rst/installing/backups.rst b/docs/en/rst/installing/backups.rst
new file mode 100644
index 000000000..f20b3021a
--- /dev/null
+++ b/docs/en/rst/installing/backups.rst
@@ -0,0 +1,38 @@
+.. _backups:
+
+Backups
+#######
+
+Database
+========
+
+Here are some sample commands you could use to backup
+your database, depending on what database system you're
+using. You may have to modify these commands for your
+particular setup. Replace the $VARIABLEs with appropriate values for your
+setup.
+
+MySQL
+-----
+
+:command:`mysqldump --opt -u $USERNAME -p $DATABASENAME > backup.sql`
+
+See the
+`mysqldump documentation <http://dev.mysql.com/doc/mysql/en/mysqldump.html>`_
+for more information on :file:`mysqldump`.
+
+.. todo:: Mention max_allowed_packet? Convert this item to a bug on checkin.
+
+PostgreSQL
+----------
+
+:command:`pg_dump --no-privileges --no-owner -h localhost -U $USERNAME > bugs.sql`
+
+Bugzilla
+========
+
+The Bugzilla directory contains some data files and configuration files which
+you would want to retain. A simple recursive copy will do the job here.
+
+:command:`cp -rp $BUGZILLA_HOME /var/backups/bugzilla`
+
diff --git a/docs/en/rst/installing/essential-post-install-config.rst b/docs/en/rst/installing/essential-post-install-config.rst
new file mode 100644
index 000000000..c5e9c0bc1
--- /dev/null
+++ b/docs/en/rst/installing/essential-post-install-config.rst
@@ -0,0 +1,172 @@
+.. _essential-post-install-config:
+
+Essential Post-Installation Configuration
+#########################################
+
+Bugzilla is configured in the Administration Parameters. Log in with the
+administrator account you defined in the last :file:`checksetup.pl` run,
+then click :guilabel:`Administration` in the header, and then
+:guilabel:`Parameters`. You will see the different parameter sections
+down the left hand side of the page.
+
+.. _config-essential-params:
+
+Parameters
+==========
+
+There are a few parameters which it is very important to define (or
+explicitly decide not to change).
+
+The first set of these are in the :guilabel:`Required Settings` section.
+
+* :param:`urlbase`: this is the URL by which people should access
+  Bugzilla's front page.
+* :param:`sslbase`: if you have configured SSL on your Bugzilla server,
+  this is the SSL URL by which people should access Bugzilla's front page.
+* :param:`ssl_redirect`: Set this if you want everyone to be redirected
+  to use the SSL version. Recommended if you have set up SSL.
+* :param:`cookiebase`: Bugzilla uses cookies to remember who each user is.
+  In order to set those cookies in the correct scope, you may need to set a
+  cookiebase. If your Bugzilla is at the root of your domain, you don't need
+  to change the default value.
+
+You may want to put your email address in the :param:`maintainer`
+parameter in the :guilabel:`General` section. This will then let people
+know who to contact if they see problems or hit errors.
+
+If you don't want just anyone able to read your Bugzilla, set the
+:param:`requirelogin` parameter in the :guilabel:`User Authentication`
+section, and change or clear the :param:`createemailregexp` parameter.
+
+.. _email:
+
+Email
+=====
+
+Bugzilla requires the ability to set up email. You have a number of choices
+here. The simplest is to get Gmail or some other email provider to do the
+work for you, but you can also hand the mail off to a local email server,
+or run one yourself on the Bugzilla machine.
+
+Bugzilla's approach to email is configured in the :guilabel:`Email` section
+of the Parameters.
+
+.. _install-MTA:
+
+Use Another Mail Server
+-----------------------
+
+This section corresponds to choosing a :param:`mail_delivery_method` of
+:paramval:`SMTP`.
+
+This method passes the email off to an existing mail server. Your
+organization may well already have one running for their internal email, and
+may prefer to use it for confidentiality reasons. If so, you need the
+following information about it:
+
+* The domain name of the server (Parameter: :param:`smtpserver`)
+* The username and password to use (Parameters: :param:`smtp_username` and 
+  :param:`smtp_password`)
+* Whether the server uses SSL (Parameter: :param:`smtp_ssl`)
+* The address you should be sending mail 'From' (Parameter:
+  :param:`mailfrom`)
+
+If your organization does not run its own mail server, you can use the
+services of one of any number of popular email providers.
+
+Gmail
+'''''
+
+Visit https://gmail.com and create a new Gmail account for your Bugzilla to
+use. Then, set the following parameter values in the "Email" section:
+
+* :param:`mail_delivery_method`: :paramval:`SMTP`
+* :param:`mailfrom`: :paramval:`new_gmail_address@gmail.com`
+* :param:`smtpserver`: :paramval:`smtp.gmail.com:465`
+* :param:`smtp_username`: :paramval:`new_gmail_address@gmail.com`
+* :param:`smtp_password`: :paramval:`new_gmail_password`
+* :param:`smtp_ssl`: :paramval:`On`
+
+Run Your Own Mail Server
+------------------------
+
+This section corresponds to choosing a :param:`mail_delivery_method` of
+:paramval:`Sendmail`.
+
+Unless you know what you are doing, and can deal with the possible problems
+of spam, bounces and blacklists, it is probably unwise to set up your own
+mail server just for Bugzilla. However, if you wish to do so, some guidance
+follows.
+
+On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will
+suffice.  Sendmail, Postfix, qmail and Exim are examples of common
+MTAs. Sendmail is the original Unix MTA, but the others are easier to
+configure, and therefore many people replace Sendmail with Postfix or
+Exim. They are drop-in replacements, so Bugzilla will not
+distinguish between them.
+
+If you are using Sendmail, version 8.7 or higher is required. If you are
+using a Sendmail-compatible MTA, it must be compatible with at least version
+8.7 of Sendmail.
+
+On Mac OS X 10.3 and later, `Postfix <http://www.postfix.org/>`_
+is used as the built-in email server.  Postfix provides an executable
+that mimics sendmail enough to satisfy Bugzilla.
+
+On Windows, if you find yourself unable to use Bugzilla's built-in SMTP
+support (e.g. because the necessary Perl modules are not available), you can
+use :paramval:`Sendmail` with a little application called
+`sendmail.exe <http://glob.com.au/sendmail/>`_, which provides
+sendmail-compatible calling conventions and encapsulates the SMTP
+communication to another mail server. Like Bugzilla, :command:`sendmail.exe`
+can be configured to log SMTP communication to a file in case of problems.
+
+Detailed information on configuring an MTA is outside the scope of this
+document. Consult the manual for the specific MTA you choose for detailed
+installation instructions. Each of these programs will have their own
+configuration files where you must configure certain parameters to
+ensure that the mail is delivered properly. They are implemented
+as services, and you should ensure that the MTA is in the auto-start
+list of services for the machine.
+
+If a simple mail sent with the command-line :file:`mail` program
+succeeds, then Bugzilla should also be fine.
+
+Troubleshooting
+---------------
+
+If you are having trouble, check that any configured SMTP server can be
+reached from your Bugzilla server and that any given authentication
+credentials are valid. If these things seem correct and your mails are still
+not sending, check if your OS uses SELinux or AppArmor. Either of these
+may prevent your web server from sending email. The SELinux boolean
+`httpd_can_sendmail <http://selinuxproject.org/page/ApacheRecipes#Allow_the_Apache_HTTP_Server_to_send_mail>`_
+may need to be set to True.
+   
+If all those things don't help, activate the :param:`smtp_debug` parameter
+and check your webserver logs.
+
+.. _config-products:
+
+Products, Components, Versions and Milestones
+=============================================
+
+Bugs in Bugzilla are categorised into Products and, inside those Products,
+Components (and, optionally, if you turn on the :param:`useclassifications`
+parameter, Classifications as a level above Products).
+
+Bugzilla comes with a single Product, called "TestProduct", which contains a
+single component, imaginatively called "TestComponent". You will want to
+create your own Products and their Components. It's OK to have just one
+Component inside a Product. Products have Versions (which represents the
+version of the software in which a bug was found) and Target Milestones
+(which represent the future version of the product in which the bug is
+hopefully to be fixed - or, for RESOLVED bugs, was fixed. You may also want
+to add some of those.
+
+Once you've created your own, you will want to delete TestProduct (which
+will delete TestComponent automatically). Note that if you've filed a bug in
+TestProduct to try Bugzilla out, you'll need to move it elsewhere before it's
+possible to delete TestProduct.
+
+Now, you may want to do some of the :ref:`optional-post-install-config`.
diff --git a/docs/en/rst/installing/iis.rst b/docs/en/rst/installing/iis.rst
new file mode 100644
index 000000000..d65aef9de
--- /dev/null
+++ b/docs/en/rst/installing/iis.rst
@@ -0,0 +1,115 @@
+.. _iis:
+
+Microsoft IIS
+#############
+
+Bugzilla works with IIS as a normal CGI application. These instructions assume
+that you are using Windows 7 Ultimate x64. Procedures for other versions are
+probably similar.
+
+Begin by starting Internet Information Services (IIS) Manager.
+:guilabel:`Start` --> :guilabel:`Administrators Tools` -->
+:guilabel:`Internet Information Services (IIS) Manager`. Or run the command:
+
+:command:`inetmgr`
+
+Create a New Application
+========================
+
+Expand your :guilabel:`Server` until the :guilabel:`Default Web Site` shows
+its children.
+
+Right-click :guilabel:`Default Web Site` and select
+:guilabel:`Add Application` from the menu.
+
+Unde :guilabel:`Alias`, enter the alias for the website. This is the path
+below the domain where you want Bugzilla to appear.
+
+Under :guilabel:`Physical Path`, enter the path to Bugzilla,
+:file:`C:\\Bugzilla`.
+
+When finished, click :guilabel:`OK`.
+
+Configure the Default Document
+==============================
+
+Click on the Application that you just created. Double-click on
+:guilabel:`Default Document`, and click :guilabel:`Add` underneath the
+Actions menu.
+
+Under :guilabel:`Name`, enter ``index.cgi``.
+
+All other default documents can be removed for this application.
+
+.. warning:: Do not delete the default document from the
+   :guilabel:`Default Website`.
+
+Add Handler Mappings
+====================
+
+Ensure that you are at the Default Website. Under :guilabel:`IIS`,
+double-click :guilabel:`Handler Mappings`. Under :guilabel:`Actions`, click
+:guilabel:`Add Script Map`. You need to do this twice.
+
+For the first one, set the following values (replacing paths if necessary):
+
+* :guilabel:`Request Path`: ``*.pl``
+* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe "%s% %s%``
+* :guilabel:`Name`: ``Perl Script Map``
+
+At the prompt select :guilabel:`No`.
+
+.. note:: The ActiveState Perl installer may have already created an entry for
+   .pl files that is limited to ``GET,HEAD,POST``. If so, this mapping should
+   be removed, as Bugzilla's .pl files are not designed to be run via a web
+   server.
+
+.. todo:: My `source <https://wiki.mozilla.org/Installing_under_IIS_7.5>`_ says
+   to add a mapping for .pl, but that's sort of contradicted by the note above
+   from a different source. Which is right?
+
+For the second one, set the following values (replacing paths if necessary):
+
+* :guilabel:`Request Path`: ``*.cgi``
+* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe "%s% %s%``
+* :guilabel:`Name`: ``CGI Script Map``
+
+At the prompt select :guilabel:`No`.
+
+Bugzilla Application
+====================
+
+Ensure that you are at the Bugzilla Application. Under :guilabel:`IIS`,
+double-click :guilabel:`Handler Mappings`. Under :guilabel:`Actions`, click
+:guilabel:`Add Script Map`.
+
+Set the following values (replacing paths if necessary):
+
+* :guilabel:`Request Path`: ``*.cgi``
+* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe -x"C:\Bugzilla" -wT "%s" %s``
+* :guilabel:`Name`: ``Bugzilla``
+
+At the prompt select :guilabel:`No`.
+
+.. todo:: The Executable lines in the three things above are weirdly
+   inconsistent. Is this intentional? My source is `this page <https://wiki.mozilla.org/Installing_under_IIS_7.5>`_.
+
+.. todo:: `LpSolit <http://lpsolit.wordpress.com/2010/10/22/make-bugzilla-work-with-iis7-easy/>`_
+   suggests there's a step to do with authorizing CGI modules. Where does that fit?
+
+Common Problems
+===============
+
+Bugzilla runs but it's not possible to log in
+  You've probably configured IIS to use ActiveState's ISAPI DLL -- in other
+  words you're using PerlEx, or the executable IIS is configured to use is
+  :file:`PerlS.dll` or :file:`Perl30.dll`.
+
+  Reconfigure IIS to use :file:`perl.exe`.
+
+IIS returns HTTP 502 errors
+  You probably forgot the ``-T`` argument to :file:`perl` when configuring the
+  executable in IIS.
+
+XMLRPC interface not working with IIS
+  This is a known issue. See :bug:`708252`.
diff --git a/docs/en/rst/installing/index.rst b/docs/en/rst/installing/index.rst
new file mode 100644
index 000000000..91a81bede
--- /dev/null
+++ b/docs/en/rst/installing/index.rst
@@ -0,0 +1,36 @@
+.. highlight:: console
+
+.. _installing:
+
+==================================
+Installation and Maintenance Guide
+==================================
+
+.. note:: If you just want to *use* Bugzilla,
+   you do not need to install it. None of this chapter is relevant to
+   you. Ask your Bugzilla administrator for the URL to access it from
+   your web browser. You may want to read the :ref:`using`.
+
+Bugzilla can be installed under Linux, Windows, Mac OS X, and perhaps other
+operating systems. However, if you are setting it up on a dedicated machine
+and you have control of the operating system to use, the Bugzilla team
+wholeheartedly recommends Linux as an extremely versatile, stable, and robust
+operating system that provides an ideal environment for Bugzilla. In that
+case, you may want to read the :ref:`Quick Start instructions <quick-start>`.
+
+.. toctree::
+   :maxdepth: 1
+
+   quick-start
+   linux
+   windows
+   mac-os-x
+   essential-post-install-config
+   optional-post-install-config
+   migrating
+   moving
+   upgrading
+   backups
+   sanity-check
+   merging-accounts
+   multiple-bugzillas
diff --git a/docs/en/rst/installing/installing-end.inc.rst b/docs/en/rst/installing/installing-end.inc.rst
new file mode 100644
index 000000000..6e34395ac
--- /dev/null
+++ b/docs/en/rst/installing/installing-end.inc.rst
@@ -0,0 +1,66 @@
+localconfig
+===========
+
+You should now change into the Bugzilla directory and run
+:file:`checksetup.pl`, without any parameters:
+
+|checksetupcommand|
+
+:file:`checksetup.pl` will write out a file called :file:`localconfig`.
+This file contains the default settings for a number of
+Bugzilla parameters, the most important of which are the group your web
+server runs as, and information on how to connect to your database.
+
+Load this file in your editor. You will need to check/change ``$db_driver``
+and ``$db_pass``, which are respectively the type of the database you are
+using and the password for the ``bugs`` database user you have created.
+``$db_driver`` can be either ``mysql``, ``Pg`` (PostgreSQL), ``Oracle`` or
+``Sqlite``. All values are case sensitive.
+
+Set the value of ``$webservergroup`` to the group your web server runs as.
+
+* Fedora/Red Hat: ``apache``
+* Debian/Ubuntu: ``www-data``
+* Mac OS X: ``_www``
+* Windows: ignore this setting; it does nothing
+
+The other options in the :file:`localconfig` file are documented by their
+accompanying comments. If you have a non-standard database setup, you may
+need to change one or more of the other ``$db_*`` parameters.
+
+.. note:: If you are using Oracle, ``$db_name`` should be set to
+   the SID name of your database (e.g. ``XE`` if you are using Oracle XE).
+
+checksetup.pl
+=============
+
+Next, run :file:`checksetup.pl` an additional time:
+
+|checksetupcommand|
+
+It reconfirms that all the modules are present, and notices the altered
+localconfig file, which it assumes you have edited to your
+satisfaction. It compiles the UI templates,
+connects to the database using the ``bugs``
+user you created and the password you defined, and creates the
+``bugs`` database and the tables therein.
+
+After that, it asks for details of an administrator account. Bugzilla
+can have multiple administrators - you can create more later - but
+it needs one to start off with.
+Enter the email address of an administrator, his or her full name,
+and a suitable Bugzilla password.
+
+:file:`checksetup.pl` will then finish. You may rerun
+:file:`checksetup.pl` at any time if you wish.
+
+Success
+=======
+
+Your Bugzilla should now be working. Check by running:
+
+|testservercommand|
+
+If that passes, access ``http://<your-bugzilla-server>/`` in your browser -
+you should see the Bugzilla front page. Of course, if you installed Bugzilla
+in a subdirectory, make sure that's in the URL.
diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst
new file mode 100644
index 000000000..97192fac3
--- /dev/null
+++ b/docs/en/rst/installing/linux.rst
@@ -0,0 +1,215 @@
+.. _linux:
+
+Linux
+#####
+
+Some Linux distributions include Bugzilla and its dependencies in their
+package management systems. If you have root access, installing Bugzilla on
+any Linux system could be as simple as finding the Bugzilla package in the
+package management application and installing it. There may be a small bit
+of additional configuration required.
+
+If you are installing your machine from scratch, :ref:`quick-start` may be
+the best instructions for you.
+
+.. _linux-install-packages:
+
+Install Packages
+================
+
+Use your distribution's package manager to install Perl, your preferred
+database engine (MySQL if in doubt), and a webserver (Apache if in doubt).
+Some distributions even have a Bugzilla package, although that will vary
+in age.
+
+The commands below will install those things and some of Bugzilla's other
+prerequisites as well. If you find a package doesn't install or the name
+is not found, just remove it from the list and reissue the command. If you
+want to use a different database or webserver, substitute the package
+names as appropriate.
+
+Fedora and Red Hat
+------------------
+
+The following command will install Red Hat's packaged version of Bugzilla:
+
+:command:`yum install bugzilla httpd mysql-server`
+
+However, if you go this route, you need to read :bug:`415605`, which details
+some problems with the Email::Send package. Then, you can skip to
+:ref:`configuring your database <linux-config-database>`. It may be useful to
+know that Fedora stores the Bugzilla files in :file:`/usr/share/bugzilla`, so
+that's where you'll run :file:`checksetup.pl`.
+
+If you want to install a version of Bugzilla from the Bugzilla project, you
+will instead need:
+
+:command:`yum install httpd mysql-server mod_perl mod_perl-devel httpd-devel
+graphviz patchutils gcc 'perl(Apache2::SizeLimit)' 'perl(Authen::Radius)'
+'perl(Authen::SASL)' 'perl(Cache::Memcached)' 'perl(CGI)' 'perl(Chart::Lines)'
+'perl(Daemon::Generic)' 'perl(Date::Format)' 'perl(DateTime)'
+'perl(DateTime::TimeZone)' 'perl(DBI)' 'perl(Digest::SHA)' 'perl(Email::MIME)'
+'perl(Email::MIME::Attachment::Stripper)' 'perl(Email::Reply)'
+'perl(Email::Sender)' 'perl(Encode)' 'perl(Encode::Detect)'
+'perl(File::MimeInfo::Magic)' 'perl(File::Slurp)' 'perl(GD)' 'perl(GD::Graph)'
+'perl(GD::Text)' 'perl(HTML::FormatText::WithLinks)' 'perl(HTML::Parser)'
+'perl(HTML::Scrubber)' 'perl(IO::Scalar)' 'perl(JSON::RPC)' 'perl(JSON::XS)'
+'perl(List::MoreUtils)' 'perl(LWP::UserAgent)' 'perl(Math::Random::ISAAC)'
+'perl(MIME::Parser)' 'perl(mod_perl2)' 'perl(Net::LDAP)' 'perl(Net::SMTP::SSL)'
+'perl(PatchReader)' 'perl(SOAP::Lite)' 'perl(Template)'
+'perl(Template::Plugin::GD::Image)' 'perl(Test::Taint)' 'perl(TheSchwartz)'
+'perl(URI)' 'perl(XMLRPC::Lite)' 'perl(XML::Twig)'`
+
+If you are running RHEL6, you will have to enable the "RHEL Server Optional"
+channel in RHN to get some of those packages. 
+
+If you plan to use SQlite as your database, you will need to also install
+the appropriate packages for that.
+
+Ubuntu and Debian
+-----------------
+
+:command:`apt-get install git nano`
+
+:command:`apt-get install apache2 mysql-server libappconfig-perl
+libdate-calc-perl libtemplate-perl libmime-perl build-essential
+libdatetime-timezone-perl libdatetime-perl libemail-sender-perl
+libemail-mime-perl libemail-mime-modifier-perl libdbi-perl libdbd-mysql-perl
+libcgi-pm-perl libmath-random-isaac-perl libmath-random-isaac-xs-perl
+apache2-mpm-prefork libapache2-mod-perl2 libapache2-mod-perl2-dev
+libchart-perl libxml-perl libxml-twig-perl perlmagick libgd-graph-perl
+libtemplate-plugin-gd-perl libsoap-lite-perl libhtml-scrubber-perl
+libjson-rpc-perl libdaemon-generic-perl libtheschwartz-perl
+libtest-taint-perl libauthen-radius-perl libfile-slurp-perl
+libencode-detect-perl libmodule-build-perl libnet-ldap-perl
+libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl
+libhtml-formattext-withlinks-perl libgd-dev lynx-cur graphviz`
+
+If you plan to use SQlite as your database, you will need to also install
+the appropriate packages for that.
+
+Gentoo
+------
+
+:command:`emerge -av bugzilla`
+
+will install Bugzilla and all its dependencies. If you don't have the vhosts
+USE flag enabled, Bugzilla will end up in :file:`/var/www/localhost/bugzilla`.
+
+Then, you can skip to :ref:`configuring your database
+<linux-config-database>`.
+
+.. _linux-install-perl:
+
+Perl
+====
+
+Test which version of Perl you have installed with:
+::
+
+    $ perl -v
+
+Bugzilla requires at least Perl |min-perl-ver|.
+
+.. _linux-install-bzfiles:
+
+Bugzilla
+========
+
+The best way to get Bugzilla is to check it out from git:
+
+:command:`git clone --branch bugzilla-X.X-stable https://git.mozilla.org/bugzilla/bugzilla`
+
+Run the above command in your home directory, replacing "X.X" with the 2-digit
+version number of the stable release of Bugzilla that you want - e.g. "4.4".
+
+If that's not possible, you can
+`download a tarball of Bugzilla <http://www.bugzilla.org/download/>`_.
+
+Place Bugzilla in a suitable directory, accessible by the default web server
+user (probably ``apache`` or ``www-data``).
+Good locations are either directly in the web server's document directory
+(often :file:`/var/www/html`) or in :file:`/usr/local`, either with a
+symbolic link to the web server's document directory or an alias in the web
+server's configuration.
+
+.. warning:: The default Bugzilla distribution is NOT designed to be placed
+   in a :file:`cgi-bin` directory. This
+   includes any directory which is configured using the
+   ``ScriptAlias`` directive of Apache.
+
+.. _linux-install-perl-modules:
+
+Perl Modules
+============
+
+Bugzilla requires a number of Perl modules. You can install these globally
+using your system's package manager, or install Bugzilla-only copies. At
+times, Bugzilla may require a version of a Perl module newer than the one
+your distribution packages, in which case you will need to install a
+Bugzilla-only copy of the newer version.
+
+At this point you probably need to become ``root``, e.g. by using
+:command:`su`. You should remain as root until the end of the install. This
+can be avoided in some circumstances if you are a member of your webserver's
+group, but being root is easier and will always work.
+
+To check whether you have all the required modules, run:
+
+:command:`./checksetup.pl --check-modules`
+
+You can run this command as many times as necessary.
+
+If you have not already installed the necessary modules, and want to do it
+system-wide, invoke your package manager appropriately at this point.
+Alternatively, you can install all missing modules locally (i.e. just for
+Bugzilla) like this:
+
+:command:`./install-module.pl --all`
+
+Or, you can pass an individual module name:
+
+:command:`./install-module.pl <modulename>`
+
+.. note:: If you are using a package-based distribution, and attempting to
+   install the Perl modules from CPAN (e.g. by using
+   :file:`install-module.pl`), you may need to install the "development"
+   packages for MySQL and GD before attempting to install the related Perl
+   modules. The names of these packages will vary depending on the specific
+   distribution you are using, but are often called
+   :file:`<packagename>-devel`.
+
+   .. todo:: Give examples for Debian/Ubuntu and RedHat.
+             Convert this item to a bug after checkin.
+
+.. _linux-config-webserver:
+
+Web Server
+==========
+
+Any web server that is capable of running CGI scripts can be made to work.
+We have specific configuration instructions for the following:
+
+* :ref:`apache`
+
+.. _linux-config-database:
+
+Database Engine
+===============
+
+Bugzilla supports MySQL, PostgreSQL, Oracle and SQLite as database servers.
+You only require one of these systems to make use of Bugzilla. MySQL is
+most commonly used. SQLite is good for trial installations as it requires no
+setup. Configure your server according to the instructions below:
+
+* :ref:`mysql`
+* :ref:`postgresql`
+* :ref:`oracle`
+* :ref:`sqlite`
+
+.. |checksetupcommand| replace:: :command:`./checksetup.pl`
+.. |testservercommand| replace:: :command:`./testserver.pl http://<your-bugzilla-server>/`
+
+.. include:: installing-end.inc.rst
+
+Next, do the :ref:`essential-post-install-config`.
diff --git a/docs/en/rst/installing/mac-os-x.rst b/docs/en/rst/installing/mac-os-x.rst
new file mode 100644
index 000000000..545d2fa27
--- /dev/null
+++ b/docs/en/rst/installing/mac-os-x.rst
@@ -0,0 +1,130 @@
+.. _mac-os-x:
+
+Mac OS X
+########
+
+.. _macosx-install-packages:
+
+.. note:: The Bugzilla team has very little Mac expertise and we've not been
+          able to do a successful install of the latest version. We got
+          close, though. If you've managed it, tell us how and we can update
+          these docs!
+
+Install Packages
+================
+
+OS X 10.7 provides Perl 5.12 and Apache 2.2. Install the following additional
+packages:
+
+* git: Download an installer from
+  `the git website <http://www.git-scm.com/downloads>`_. 
+* MySQL: Download an installer from
+  `the MySQL website <http://dev.mysql.com/downloads/mysql/>`_.
+
+.. _macosx-install-bzfiles:
+
+Bugzilla
+========
+
+The best way to get Bugzilla is to check it out from git:
+
+:command:`git clone --branch bugzilla-X.X-stable https://git.mozilla.org/bugzilla/bugzilla`
+
+Run the above command in your home directory, replacing "X.X" with the 2-digit
+version number of the stable release of Bugzilla that you want - e.g. "4.4".
+This will place Bugzilla in the directory :file:`$HOME/bugzilla`.
+
+If that's not possible, you can
+`download a tarball of Bugzilla <http://www.bugzilla.org/download/>`_.
+
+.. _macosx-libraries:
+
+Additional System Libraries
+===========================
+
+Apple does not include the GD library with Mac OS X. Bugzilla needs this if
+you want to display bug graphs, and you need to install it before you try
+installing the GD Perl module.
+
+You can use `MacPorts <http://www.macports.org/>`_, `Homebrew <http://brew.sh/>`_ or
+`Fink <http://sourceforge.net/projects/fink/>`_, all of which can install common
+Unix programs on Mac OS X.
+
+If you don't have one of the above installed already, pick one and follow the
+instructions for setting it up. Then, use it to install the :file:`gd2` package
+(MacPorts/Fink) or the :file:`gd` package (Brew).
+
+The package manager may prompt you to install a number of dependencies; you
+will need to agree to this.
+
+.. note:: To prevent creating conflicts with the software that Apple
+   installs by default, Fink creates its own directory tree at :file:`/sw`
+   where it installs most of
+   the software that it installs. This means your libraries and headers
+   will be at :file:`/sw/lib` and :file:`/sw/include` instead
+   of :file:`/usr/lib` and :file:`/usr/include`. When the
+   Perl module config script for the GD module asks where your :file:`libgd`
+   is, be sure to tell it :file:`/sw/lib`.
+
+.. _macosx-install-perl-modules:
+
+Perl Modules
+============
+
+Bugzilla requires a number of Perl modules. On Mac OS X, the easiest thing to
+do is to install local copies (rather than system-wide copies) of any ones
+that you don't already have. However, if you do want to install them
+system-wide, run the below commands as root with the :command:`--global`
+option.
+
+To check whether you have all the required modules and what is still missing,
+run:
+
+:command:`perl checksetup.pl --check-modules`
+
+You can run this command as many times as necessary.
+
+Install all missing modules locally like this:
+
+:command:`perl install-module.pl --all`
+
+.. _macosx-config-webserver:
+
+Web Server
+==========
+
+Any web server that is capable of running CGI scripts can be made to work.
+We have specific configuration instructions for the following:
+
+* :ref:`apache`
+
+You'll need to create a symbolic link so the webserver can see Bugzilla:
+
+:command:`cd /Library/WebServer/Documents`
+
+:command:`sudo ln -s $HOME/bugzilla bugzilla`
+
+In :guilabel:`System Preferences` --> :guilabel:`Sharing`, enable the
+:guilabel:`Web Sharing` checkbox to start Apache. 
+
+.. _macosx-config-database:
+
+Database Engine
+===============
+
+Bugzilla supports MySQL, PostgreSQL, Oracle and SQLite as database servers.
+You only require one of these systems to make use of Bugzilla. MySQL is
+most commonly used on Mac OS X. (In fact, we have no reports of anyone using
+anything else.) Configure your server according to the instructions below:
+
+* :ref:`mysql`
+* :ref:`postgresql`
+* :ref:`oracle`
+* :ref:`sqlite`
+
+.. |checksetupcommand| replace:: :command:`perl checksetup.pl`
+.. |testservercommand| replace:: :command:`perl testserver.pl http://<your-bugzilla-server>/`
+
+.. include:: installing-end.inc.rst
+
+Next, do the :ref:`essential-post-install-config`.
diff --git a/docs/en/rst/installing/merging-accounts.rst b/docs/en/rst/installing/merging-accounts.rst
new file mode 100644
index 000000000..4dbdb807f
--- /dev/null
+++ b/docs/en/rst/installing/merging-accounts.rst
@@ -0,0 +1,14 @@
+Merging Accounts
+################
+
+Sometimes, users create a second account, perhaps because they don't realise
+they can change the email address associated with their original account.
+And then, once they discover this, they don't want to abandon the history
+associated with either account.
+
+The best way forward in this case would be to merge one of their accounts
+into the other one, so it looked like the target account had done all the
+actions of both. In Bugzilla's :file:`contrib` directory, there is a script
+called :file:`merge-users.pl`. While code in this directory is not officially
+supported by the Bugzilla team, this script may be useful to you in
+solving the above problem.
diff --git a/docs/en/rst/installing/migrating-from-1.inc.rst b/docs/en/rst/installing/migrating-from-1.inc.rst
new file mode 100644
index 000000000..d834a8605
--- /dev/null
+++ b/docs/en/rst/installing/migrating-from-1.inc.rst
@@ -0,0 +1,7 @@
+.. This file is included in multiple places, so can't have labels as they
+   appear as duplicates.
+   
+The procedure to migrate to Git is as follows. The idea is to switch version
+control systems without changing the version of Bugzilla you are using,
+to minimise the risk of conflict or problems. Any upgrade can then
+happen as a separate step.
diff --git a/docs/en/rst/installing/migrating-from-2.inc.rst b/docs/en/rst/installing/migrating-from-2.inc.rst
new file mode 100644
index 000000000..873a9c87d
--- /dev/null
+++ b/docs/en/rst/installing/migrating-from-2.inc.rst
@@ -0,0 +1,149 @@
+.. This file is included in multiple places, so can't have labels as they
+   appear as duplicates.
+
+Download Code from Git
+======================
+
+First, you need to find what version of Bugzilla you are using. It should be
+in the top right corner of the front page but, if not, open the file
+:file:`Bugzilla/Constants.pm` in your Bugzilla directory and search for
+:code:`BUGZILLA_VERSION`.
+
+Then, you need to download an additional copy of your *current* version of
+Bugzilla from the git repository, and place it in a separate directory
+alongside your existing Bugzilla installation (which we will assume is in a
+directory called :file:`bugzilla`).
+
+To do this, you will need a copy of the :command:`git` program. All Linux
+distributions have it; search your package manager for "git". On Windows or
+Mac OS X, you can
+`download the official build <http://www.git-scm.com/downloads>`_.
+
+Once git is installed, run these commands to pull a copy of Bugzilla:
+
+:command:`git clone https://git.mozilla.org/bugzilla/bugzilla bugzilla-new`
+
+:command:`cd bugzilla-new`
+
+:command:`git checkout release-$VERSION`
+
+Replace $VERSION with the three-digit version number of your current Bugzilla,
+e.g. "4.2.2". (If the the final digit would have been a 0, omit it - so use
+"4.4" for the first release in the 4.4 series.)
+
+You will get a message about a 'detached HEAD'. Don't worry; your head is
+still firmly attached to your shoulders.
+
+Save Any Local Customizations
+=============================
+
+Go into your original Bugzilla directory and run this command:
+
+|diffcommand|
+
+If you have made customizations to your Bugzilla, and you made them by
+changing the Bugzilla code itself (rather than using the Extension system),
+then :file:`patch.diff` will have significant content. You will want to keep a copy
+of those changes by keeping a copy of this file and any files referenced in it
+by "Only in" lines. If the file has zero size or only insignificant content,
+you haven't made any local customizations of this sort.
+
+Shut Down Bugzilla
+==================
+
+At this point, you should shut down Bugzilla to make sure nothing changes
+while you make the switch. Go into the administrative interface and put an
+appropriate message into the :param:`shutdownhtml` parameter, which is in the
+"General" section of the administration parameters. As the name implies, HTML
+is allowed.
+
+This would be a good time to make :ref:`backups`. We shouldn't be affecting
+the database, but you can't be too careful.
+
+Copy Across Data and Modules
+============================
+
+Copy the contents of the following directories from your current installation
+of Bugzilla into the corresponding directory in :file:`bugzilla-new/`:
+
+.. code-block:: none
+
+  lib/
+  data/
+  template/en/custom (may or may not exist)
+
+You also need to copy any extensions you have written or installed, which are
+in the :file:`extensions/` directory. |extstatusinfo|
+
+Lastly, copy the following file from your current installation of Bugzilla
+into the corresponding place in :file:`bugzilla-new/`:
+
+.. code-block:: none
+
+  localconfig
+
+This file contains your database password and access details. Because your
+two versions of Bugzilla are the same, this should all work fine.
+
+Reapply Local Customizations
+============================
+
+If your :file:`patch.diff` file was zero sized, you can
+jump to the next step. Otherwise, you have to apply the patch to your new
+installation. If you are on Windows and you don’t have the :command:`patch`
+program, you can download it from
+`GNUWin <http://gnuwin32.sourceforge.net/packages/patch.htm>`_. Once
+downloaded, you must copy patch.exe into the Windows directory. 
+
+Copy :file:`patch.diff` into the :file:`bugzilla-new` directory and then do:
+
+:command:`patch -p0 --dry-run < patch.diff`
+
+The patch should apply cleanly because you have exactly the same version of
+Bugzilla in both directories. If it does, remove the :command:`--dry-run` and
+rerun the command to apply it for real. If it does not apply cleanly, it is
+likely that you have managed to get a Bugzilla version mismatch between the
+two directories.
+
+Swap The New Version In
+=======================
+
+Now we swap the directories over, and run checksetup.pl to confirm that all
+is well. From the directory containing the :file:`bugzilla` and
+:file:`bugzilla-new` directories, run:
+
+:command:`mv bugzilla bugzilla-old`
+
+:command:`mv bugzilla-new bugzilla`
+
+:command:`cd bugzilla`
+
+:command:`./checksetup.pl`
+
+Running :file:`checksetup.pl` should not result in any changes to your database at
+the end of the run. If it does, then it's most likely that the two versions
+of Bugzilla you have are not, in fact, the same.
+
+Re-enable Bugzilla
+==================
+
+Go into the administrative interface and clear the contents of the
+:param:`shutdownhtml` parameter.
+
+Test Bugzilla
+=============
+
+Use your Bugzilla for several days to check that the switch has had no
+detrimental effects. Then, if necessary, follow the instructions in
+:ref:`upgrading-with-git` to upgrade to the latest version of Bugzilla.
+
+Rolling Back
+============
+
+If something goes wrong at any stage of the switching process (e.g. your
+patch doesn't apply, or checksetup doesn't complete), you can always just
+switch the directories back (if you've got that far) and re-enable Bugzilla
+(if you disabled it) and then seek help. Even if you have re-enabled Bugzilla,
+and find a problem a little while down the road, you are still using the same
+version so there would be few side effects to switching the directories back
+a day or three later.
diff --git a/docs/en/rst/installing/migrating-from-a-tarball.rst b/docs/en/rst/installing/migrating-from-a-tarball.rst
new file mode 100644
index 000000000..852cb8dbe
--- /dev/null
+++ b/docs/en/rst/installing/migrating-from-a-tarball.rst
@@ -0,0 +1,15 @@
+.. _migrating-from-a-tarball:
+
+Migrating from a Tarball
+########################
+
+.. |diffcommand|   replace:: :command:`diff -ru -x data -x lib -x docs -x .git -x CVS -x .cvsignore -x .bzr -x .bzrignore -x .bzrrev ../bugzilla-new . > ../patch.diff`
+
+.. |extstatusinfo| replace:: Copy across any subdirectories which do not exist
+                             in your new install.
+
+The procedure to migrate to Git is as follows. The idea is to switch without
+changing the version of Bugzilla you are using, to minimise the risk of
+conflict or problems. Any upgrade can then happen as a separate step. 
+
+.. include:: migrating-from-2.inc.rst
diff --git a/docs/en/rst/installing/migrating-from-bzr.rst b/docs/en/rst/installing/migrating-from-bzr.rst
new file mode 100644
index 000000000..da6809a01
--- /dev/null
+++ b/docs/en/rst/installing/migrating-from-bzr.rst
@@ -0,0 +1,11 @@
+.. _migrating-from-bazaar:
+
+Migrating from Bazaar
+#####################
+
+.. |updatecommand| replace:: :command:`bzr up -r tag:bugzilla-$VERSION`
+.. |diffcommand|   replace:: :command:`bzr diff > patch.diff`
+.. |extstatusinfo| replace:: The command :command:`bzr status extensions/` should help you work out what you added, if anything.
+
+.. include:: migrating-from-1.inc.rst
+.. include:: migrating-from-2.inc.rst
diff --git a/docs/en/rst/installing/migrating-from-cvs.rst b/docs/en/rst/installing/migrating-from-cvs.rst
new file mode 100644
index 000000000..76f6253f2
--- /dev/null
+++ b/docs/en/rst/installing/migrating-from-cvs.rst
@@ -0,0 +1,13 @@
+.. _migrating-from-cvs:
+
+Migrating from CVS
+##################
+
+.. |updatecommand| replace:: :command:`cvs update -rBUGZILLA-$VERSION-STABLE -dP`
+.. |diffcommand|   replace:: :command:`cvs diff -puN > patch.diff`
+.. |extstatusinfo| replace:: The command :command:`cvs status extensions/` should help you work out what you added, if anything.
+
+.. include:: migrating-from-1.inc.rst
+.. include:: migrating-from-2.inc.rst
+
+
diff --git a/docs/en/rst/installing/migrating.rst b/docs/en/rst/installing/migrating.rst
new file mode 100644
index 000000000..5b842dd3d
--- /dev/null
+++ b/docs/en/rst/installing/migrating.rst
@@ -0,0 +1,23 @@
+.. _migrating-from-other-btses:
+
+Migrating From Other Bug-Tracking Systems
+#########################################
+
+Bugzilla has a framework you can use for migrating from other bug-tracking
+systems -
+`Bugzilla::Migrate <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Migrate.html>`_.
+It provides the infrastructure you will need,
+but requires a module to be written to define the specifics of the system you
+are coming from. One exists for
+`Gnats <https://www.gnu.org/software/gnats/>`_. If you write one for a
+popular system, please share your code with us.
+
+Alternatively, Bugzilla comes with a script, :file:`importxml.pl`, which
+imports bugs in Bugzilla's XML format. You can see examples of this format
+by clicking the :guilabel:`XML` link at the bottom of a bug in a running
+Bugzilla. You would need to read the script to see how it handles errors,
+default values, creating non-existing values and so on.
+
+Bugzilla::Migrate is preferred if possible.
+
+
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.
diff --git a/docs/en/rst/installing/multiple-bugzillas.rst b/docs/en/rst/installing/multiple-bugzillas.rst
new file mode 100644
index 000000000..1e2d7951f
--- /dev/null
+++ b/docs/en/rst/installing/multiple-bugzillas.rst
@@ -0,0 +1,41 @@
+.. _multiple-bz-dbs:
+
+One Installation, Multiple Instances
+####################################
+
+This is a somewhat specialist feature; if you don't know whether you need it,
+you don't. It is useful to admins who want to run many separate instances of
+Bugzilla from a single installed codebase.
+
+This is possible by using the ``PROJECT`` environment variable. When accessed,
+Bugzilla checks for the existence of this variable, and if present, uses
+its value to check for an alternative configuration file named
+:file:`localconfig.<PROJECT>` in the same location as
+the default one (:file:`localconfig`). It also checks for
+customized templates in a directory named
+:file:`<PROJECT>` in the same location as the
+default one (:file:`template/<langcode>`). By default
+this is :file:`template/en/default` so ``PROJECT``'s templates
+would be located at :file:`template/en/PROJECT`.
+
+To set up an alternate installation, just export ``PROJECT=foo`` before
+running :command:`checksetup.pl` for the first time. It will
+result in a file called :file:`localconfig.foo` instead of
+:file:`localconfig`. Edit this file as described above, with
+reference to a new database, and re-run :command:`checksetup.pl`
+to populate it. That's all.
+
+Now you have to configure the web server to pass this environment
+variable when accessed via an alternate URL, such as virtual host for
+instance. The following is an example of how you could do it in Apache,
+other Webservers may differ.
+
+.. code-block:: apache
+
+    <VirtualHost 12.34.56.78:80>
+        ServerName bugzilla.example.com
+        SetEnv PROJECT foo
+    </VirtualHost>
+
+Don't forget to also export this variable before accessing Bugzilla
+by other means, such as repeating tasks like those above.
diff --git a/docs/en/rst/installing/mysql.rst b/docs/en/rst/installing/mysql.rst
new file mode 100644
index 000000000..1107547a6
--- /dev/null
+++ b/docs/en/rst/installing/mysql.rst
@@ -0,0 +1,143 @@
+.. _mysql:
+
+MySQL
+#####
+
+You need MySQL version 5.0.15 or higher.
+
+It's possible to test which version of MySQL you have installed with:
+
+:command:`mysql -V`
+
+Installing
+==========
+
+Windows
+-------
+
+Download the MySQL 32-bit or 64-bit MSI installer from the
+`MySQL website <http://www.mysql.com/downloads/mysql/>`_ (~28 MB).
+
+MySQL has a standard Windows installer. It's ok to select a Typical MySQL
+install (the default). The rest of this documentation assumes assume you
+have installed MySQL into :file:`C:\\mysql`. Adjust paths appropriately if not.
+
+Linux/Mac OS X
+--------------
+
+The package install instructions given previously should have installed MySQL
+on your machine, if it didn't come with it already. Run:
+
+:command:`mysql_secure_installation`
+
+and follow its advice.
+
+If you did install MySQL manually rather than from a package, make sure the
+server is started when the machine boots.
+
+.. _mysql-add-user:
+
+Add a User
+==========
+
+You need to add a new MySQL user for Bugzilla to use. Run the :file:`mysql`
+command-line client and enter:
+
+::
+
+    GRANT SELECT, INSERT,
+    UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
+    CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
+    TO bugs@localhost IDENTIFIED BY '$DB_PASS';
+
+    FLUSH PRIVILEGES;
+
+You need to replace ``$DB_PASS`` with a strong password you have chosen.
+Write that password down somewhere.
+
+The above command permits an account called ``bugs``
+to connect from the local machine, ``localhost``. Modify the command to
+reflect your setup if you will be connecting from another
+machine or as a different user.
+
+Change Configuration
+====================
+
+To change MySQL's configuration, you need to edit your MySQL
+configuration file, which is:
+
+* Red Hat/Fedora: :file:`/etc/my.cnf`
+* Debian/Ubuntu: :file:`/etc/mysql/my.cnf`
+* Windows: :file:`C:\\mysql\\bin\\my.ini`
+* Mac OS X: :file:`/etc/my/cnf`
+
+.. _mysql-max-allowed-packet:
+
+Allow Large Attachments and Many Comments
+-----------------------------------------
+
+By default on some systems, MySQL will only allow you to insert things
+into the database that are smaller than 1MB.
+
+Bugzilla attachments
+may be larger than this. Also, Bugzilla combines all comments
+on a single bug into one field for full-text searching, and the
+combination of all comments on a single bug could in some cases
+be larger than 1MB.
+
+We recommend that you allow at least 16MB packets by
+adding or altering the ``max_allowed_packet`` parameter in your MySQL
+configuration in the ``[mysqld]`` section, so that the number is at least
+16M, like this (note that it's ``M``, not ``MB``):
+
+::
+
+    [mysqld]
+    # Allow packets up to 16M
+    max_allowed_packet=16M
+
+.. _mysql-small-words:
+
+Allow Small Words in Full-Text Indexes
+--------------------------------------
+
+By default, words must be at least four characters in length
+in order to be indexed by MySQL's full-text indexes. This causes
+a lot of Bugzilla-specific words to be missed, including "cc",
+"ftp" and "uri".
+
+MySQL can be configured to index those words by setting the
+``ft_min_word_len`` param to the minimum size of the words to index.
+
+::
+
+    [mysqld]
+    # Allow small words in full-text indexes
+    ft_min_word_len=2
+
+.. _mysql-attach-table-size:
+
+Permit Attachments Table to Grow Beyond 4GB
+===========================================
+
+This is optional configuration for Bugzillas which are expected to become
+very large, and needs to be done after Bugzilla is fully installed.
+
+By default, MySQL will limit the size of a table to 4GB.
+This limit is present even if the underlying filesystem
+has no such limit.  To set a higher limit, run the :file:`mysql`
+command-line client and enter the following, replacing ``$bugs_db``
+with your Bugzilla database name (which is ``bugs`` by default):
+
+.. code-block:: sql
+
+    USE $bugs_db;
+    
+    ALTER TABLE attachments AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
+
+The above command will change the limit to 20GB. MySQL will have
+to make a temporary copy of your entire table to do this, so ideally
+you should do this when your attachments table is still small.
+
+.. note:: If you have set the setting in Bugzilla which allows large
+   attachments to be stored on disk, the above change does not affect that.
diff --git a/docs/en/rst/installing/optional-post-install-config.rst b/docs/en/rst/installing/optional-post-install-config.rst
new file mode 100644
index 000000000..f79918d2a
--- /dev/null
+++ b/docs/en/rst/installing/optional-post-install-config.rst
@@ -0,0 +1,133 @@
+.. _optional-post-install-config:
+
+Optional Post-Install Configuration
+###################################
+
+Bugzilla has a number of optional features. This section describes how
+to configure or enable them.
+
+.. _recurring-tasks:
+
+Recurring Tasks
+===============
+
+Several of the below features require you to set up a script to run at
+recurring intervals. The method of doing this varies by operating system.
+
+Linux
+-----
+
+Run:
+
+:command:`crontab -e`
+
+This should bring up the crontab file in your editor. Add the relevant
+cron line from the sections below in order to enable the corresponding
+feature.
+
+Windows
+-------
+
+Windows comes with a Task Scheduler. To run a particular script, do the
+following:
+
+#. :guilabel:`Control Panel` --> :guilabel:`Scheduled Tasks` -->
+   :guilabel:`Add Scheduled Task`
+
+#. Next
+
+#. Browse
+
+#. Find :file:`perl.exe` (normally :file:`C:\\Perl\\bin\\perl.exe`)
+
+#. Give the task a name, such as "Bugzilla <scriptname>"
+
+#. Request the task be performed at your desired time and interval
+
+#. If you're running Apache as a user, not as SYSTEM, enter that user
+   here. Otherwise you're best off creating an account that has write access
+   to the Bugzilla directory and using that
+
+#. Tick "Open Advanced Properties.." and click Finish
+
+#. Append the script name to the end of the "Run" field. eg
+   :command:`C:\\Perl\\bin\\perl.exe C:\\Bugzilla\\<scriptname>`
+
+#. Change "start in" to the Bugzilla directory
+
+.. _installation-bug-graphs:
+
+Bug Graphs
+==========
+
+If you have installed the necessary Perl modules, as indicated by
+:file:`checksetup.pl`, you can ask Bugzilla to regularly collect statistics
+so that you can see graphs and charts.
+
+On Linux, use a cron line as follows:
+
+.. code-block:: none
+
+    5 0 * * * cd <your-bugzilla-directory> && ./collectstats.pl
+
+On Windows, schedule the :file:`collectstats.pl` script to run daily.
+
+After two days have passed you'll be able to view bug graphs from
+the Reports page.
+
+.. _installation-whining:
+
+Whining
+=======
+
+Users can configure Bugzilla to annoy them at regular intervals, by having
+Bugzilla execute saved searches at certain times and emailing the results to
+the user.  This is known as "Whining".  The details of how a user configures
+Whining is described in :ref:`whining`, but for it to work a Perl script must
+be executed at regular intervals.
+
+On Linux, use a cron line as follows:
+
+.. code-block:: none
+
+    */15 * * * * cd <your-bugzilla-directory> && ./whine.pl
+
+On Windows, schedule the :file:`whine.pl` script to run every 15 minutes.
+
+.. _installation-whining-cron:
+
+Whining at Untriaged Bugs
+=========================
+
+It's possible for bugs to languish in an untriaged state. Bugzilla has a
+specific system to issue complaints about this particular problem to all the
+relevant engineers automatically by email.
+
+On Linux, use a cron line as follows:
+
+.. code-block:: none
+
+    55 0 * * * cd <your-bugzilla-directory> && ./whineatnews.pl
+
+On Windows, schedule the :file:`whineatnews.pl` script to run daily.
+
+Dependency Graphs
+=================
+
+Bugzilla can draw graphs of the dependencies (depends on/blocks relationships)
+between bugs, if you install a package called :file:`dot`.
+
+Linux
+-----
+
+Put the complete path to the :file:`dot` command (from the ``graphviz``
+package) in the :param:`webdotbase` parameter. E.g. :paramval:`/usr/bin/dot`.
+
+Windows
+-------
+
+Download and install Graphviz from
+`the Graphviz website <http://www.graphviz.org/Download_windows.php>`_. Put
+the complete path to :file:`dot.exe` in the :param:`webdotbase` parameter,
+using forward slashes as path separators. E.g.
+:paramval:`C:/Program Files/ATT/Graphviz/bin/dot.exe`.
diff --git a/docs/en/rst/installing/oracle.rst b/docs/en/rst/installing/oracle.rst
new file mode 100644
index 000000000..860b61fe6
--- /dev/null
+++ b/docs/en/rst/installing/oracle.rst
@@ -0,0 +1,69 @@
+.. _oracle:
+
+Oracle
+######
+
+.. warning:: Bugzilla supports Oracle, but none of the current developers run
+   it. Your mileage may vary.
+
+You need Oracle version 10.02.0 or later.
+
+.. _oracle-tablespace:
+
+Create a New Tablespace
+=======================
+
+You can use the existing tablespace or create a new one for Bugzilla.
+To create a new tablespace, run the following command:
+
+::
+
+    CREATE TABLESPACE bugs
+    DATAFILE '*$path_to_datafile*' SIZE 500M
+    AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
+
+Here, the name of the tablespace is 'bugs', but you can
+choose another name. *$path_to_datafile* is
+the path to the file containing your database, for instance
+:file:`/u01/oradata/bugzilla.dbf`.
+The initial size of the database file is set in this example to 500 Mb,
+with an increment of 30 Mb everytime we reach the size limit of the file.
+
+.. _oracle-add-user:
+
+Add a User to Oracle
+====================
+
+The user name and password must match what you set in :file:`localconfig`
+(``$db_user`` and ``$db_pass``, respectively). Here, we assume that
+the user name is 'bugs' and the tablespace name is the same
+as above.
+
+::
+
+    CREATE USER bugs
+    IDENTIFIED BY "$db_pass"
+    DEFAULT TABLESPACE bugs
+    TEMPORARY TABLESPACE TEMP
+    PROFILE DEFAULT;
+    -- GRANT/REVOKE ROLE PRIVILEGES
+    GRANT CONNECT TO bugs;
+    GRANT RESOURCE TO bugs;
+    -- GRANT/REVOKE SYSTEM PRIVILEGES
+    GRANT UNLIMITED TABLESPACE TO bugs;
+    GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
+
+.. _oracle_webserver:
+
+Configure the Web Server
+========================
+
+If you use Apache, append these lines to :file:`httpd.conf`
+to set ORACLE_HOME and LD_LIBRARY_PATH. For instance:
+
+.. code-block:: apache
+
+    SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/
+    SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/
+
+When this is done, restart your web server.
diff --git a/docs/en/rst/installing/postgresql.rst b/docs/en/rst/installing/postgresql.rst
new file mode 100644
index 000000000..1d0ec1d49
--- /dev/null
+++ b/docs/en/rst/installing/postgresql.rst
@@ -0,0 +1,58 @@
+.. _postgresql:
+
+PostgreSQL
+##########
+
+Test which version of PostgreSQL you have installed with:
+
+:command:`psql -V`
+
+You need PostgreSQL version 8.03.0000 or higher.
+
+If you install PostgreSQL manually rather than from a package, make sure the
+server is started when the machine boots.
+
+.. _posgresql-add-user:
+
+Add a User
+==========
+
+You need to add a new user to PostgreSQL for the Bugzilla
+application to use when accessing the database. The following instructions
+assume the defaults in :file:`localconfig`; if you
+changed those, you need to modify the commands appropriately.
+
+On most systems, to create a user in PostgreSQL, login as the root user, and
+then switch to being the postgres (Unix) user:
+
+:command:`su - postgres`
+
+As the postgres user, you then need to create a new user:
+
+:command:`createuser -U postgres -dRSP bugs`
+
+When asked for a password, provide one and write it down for later reference.
+
+The created user will not be a superuser (-S) and will not be able to create
+new users (-R). He will only have the ability to create databases (-d).
+
+.. _postgresql-access:
+
+Permit Access
+=============
+
+Edit the file :file:`pg_hba.conf` which is
+usually located in :file:`/var/lib/pgsql/data/`. In this file,
+you will need to add a new line to it as follows:
+
+::
+
+    host   all    bugs   127.0.0.1    255.255.255.255  md5
+
+This means that for TCP/IP (host) connections, allow connections from
+'127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use
+password authentication ('md5') for that user.
+
+Now, you will need to stop and start PostgreSQL fully. (Do not use any
+'restart' command, due to the possibility of a change to
+:file:`postgresql.conf`.)
diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst
new file mode 100644
index 000000000..220421bce
--- /dev/null
+++ b/docs/en/rst/installing/quick-start.rst
@@ -0,0 +1,223 @@
+.. _quick-start:
+
+Quick Start (Ubuntu Linux 14.04)
+################################
+
+This quick start guide makes installing Bugzilla as simple as possible for
+those who are able to choose their environment. It creates a system using
+Ubuntu Linux 14.04 LTS, Apache and MySQL, and installs Bugzilla as the default
+home page. It requires a little familiarity with Linux and the command line.
+
+Obtain Your Hardware
+====================
+
+Ubuntu 14.04 LTS Server requires a 64-bit processor.
+Bugzilla itself has no prerequisites beyond that, although you should pick
+reliable hardware. You can also probably use any 64-bit virtual machine
+or cloud instance that you have root access on. 
+
+Install the OS
+==============
+
+Get `Ubuntu Server 14.04 LTS <http://www.ubuntu.com/download/server>`_
+and follow the `installation instructions <http://www.ubuntu.com/download/server/install-ubuntu-server>`_.
+Here are some tips:
+
+* Choose any server name you like.
+* When creating the initial Linux user, call it ``bugzilla``, give it a 
+  strong password, and write that password down.
+* You do not need an encrypted home directory.
+* Choose all the defaults for the "partitioning" part (excepting of course
+  where the default is "No" and you need to press "Yes" to continue).
+* Choose "install security updates automatically" unless you want to do
+  them manually.
+* From the install options, choose "OpenSSH Server" and "LAMP Server".
+* Set the password for the MySQL root user to a strong password, and write
+  that password down.
+* Install the Grub boot loader to the Master Boot Record.
+
+Reboot when the installer finishes.
+
+Become root
+===========
+
+ssh to the machine as the 'bugzilla' user, or start a console. Then:
+
+:command:`sudo su`
+   
+Install Prerequisites
+=====================
+
+:command:`apt-get install git nano`
+
+:command:`apt-get install apache2 mysql-server libappconfig-perl libdate-calc-perl libtemplate-perl libmime-perl build-essential libdatetime-timezone-perl libdatetime-perl libemail-sender-perl libemail-mime-perl libemail-mime-modifier-perl libdbi-perl libdbd-mysql-perl libcgi-pm-perl libmath-random-isaac-perl libmath-random-isaac-xs-perl apache2-mpm-prefork libapache2-mod-perl2 libapache2-mod-perl2-dev libchart-perl libxml-perl libxml-twig-perl perlmagick libgd-graph-perl libtemplate-plugin-gd-perl libsoap-lite-perl libhtml-scrubber-perl libjson-rpc-perl libdaemon-generic-perl libtheschwartz-perl libtest-taint-perl libauthen-radius-perl libfile-slurp-perl libencode-detect-perl libmodule-build-perl libnet-ldap-perl libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl libhtml-formattext-withlinks-perl libgd-dev lynx-cur`
+
+This will take a little while. It's split into two commands so you can do
+the next steps (up to step 7) in another terminal while you wait for the
+second command to finish. If you start another terminal, you will need to
+:command:`sudo su` again.
+
+Download Bugzilla
+=================
+
+Get it from our Git repository:
+
+:command:`cd /var/www`
+
+:command:`rm -rf html`
+
+:command:`git clone --branch bugzilla-X.X-stable https://git.mozilla.org/bugzilla/bugzilla html`
+
+(where "X.X" is the 2-digit version number of the stable release of Bugzilla
+that you want - e.g. 4.4)
+
+:command:`cd html`
+   
+Configure MySQL
+===============
+
+The following instructions use the simple :file:`nano` editor, but feel
+free to use any text editor you are comfortable with.
+
+:command:`nano /etc/mysql/my.cnf`
+
+Set the following values, which increase the maximum attachment size and
+make it possible to search for short words and terms:
+
+* Alter on Line 52: ``max_allowed_packet=100M``
+* Add as new line 31, in the ``[mysqld]`` section: ``ft_min_word_len=2``
+
+Save and exit.
+
+Then, add a user to MySQL for Bugzilla to use:
+
+:command:`mysql -u root -p -e "GRANT ALL PRIVILEGES ON bugs.* TO bugs@localhost IDENTIFIED BY '$db_pass'"`
+
+Replace ``$db_pass`` with a strong password you have generated. Write it down.
+When you run the above command, it will prompt you for the MySQL root password
+that you configured when you installed Ubuntu. You should make ``$db_pass``
+different to that password.
+
+Restart MySQL:
+
+:command:`service mysql restart`
+
+Configure Apache
+================
+
+:command:`nano /etc/apache2/sites-available/bugzilla.conf`
+
+Paste in the following and save:
+
+.. code-block:: apache
+
+ ServerName localhost
+
+ <Directory /var/www/html>
+   AddHandler cgi-script .cgi
+   Options +ExecCGI
+   DirectoryIndex index.cgi index.html
+   AllowOverride Limit FileInfo Indexes Options
+ </Directory>
+
+:command:`a2ensite bugzilla`
+
+:command:`a2enmod cgi headers expires`
+
+:command:`service apache2 restart`
+
+Check Setup
+===========
+
+Bugzilla comes with a :file:`checksetup.pl` script which helps with the
+installation process. It will need to be run twice. The first time, it
+generates a config file (called :file:`localconfig`) for the database
+access information, and the second time (step 10)
+it uses the info you put in the config file to set up the database.
+
+:command:`cd /var/www/html`
+
+:command:`./checksetup.pl`
+
+Edit :file:`localconfig`
+========================
+
+:command:`nano localconfig`
+
+You will need to set the following values:
+
+* Line 29: set ``$webservergroup`` to ``www-data``
+* Line 67: set ``$db_pass`` to the password for the ``bugs`` user you created
+  in MySQL a few steps ago
+
+Check Setup (again)
+===================
+
+Run the :file:`checksetup.pl` script again to set up the database.
+
+:command:`./checksetup.pl`
+
+It will ask you to give an email address, real name and password for the
+first Bugzilla account to be created, which will be an administrator.
+Write down the email address and password you set.
+
+Test Server
+===========
+
+:command:`./testserver.pl http://localhost/`
+
+All the tests should pass. You will get warnings about deprecation from
+the ``Chart::Base`` Perl module; just ignore those.
+
+.. todo:: Chart::Base gives confusing deprecation warnings :-|
+          https://rt.cpan.org/Public/Bug/Display.html?id=79658 , unfixed for
+          2 years. :bug:`1070117`.
+
+Access Via Web Browser
+======================
+
+Access the front page:
+
+:command:`lynx http://localhost/`
+
+It's not really possible to use Bugzilla for real through Lynx, but you
+can view the front page to validate visually that it's up and running.
+
+You might well need to configure your DNS such that the server has, and
+is reachable by, a name rather than IP address. Doing so is out of scope
+of this document. In the mean time, it is available on your local network
+at ``http://<ip address>/``, where ``<ip address>`` is (unless you have
+a complex network setup) the "inet addr" value displayed when you run
+:command:`ifconfig eth0`.
+
+Configure Bugzilla
+==================
+
+Once you have worked out how to access your Bugzilla in a graphical
+web browser, bring up the front page, click :guilabel:`Log In` in the
+header, and log in as the admin user you defined in step 10.
+
+Click the :guilabel:`Parameters` link on the page it gives you, and set
+the following parameters in the :guilabel:`Required Settings` section:
+
+* :param:`urlbase`:
+  :paramval:`http://<servername>/` or :paramval:`http://<ip address>/`
+
+Click :guilabel:`Save Changes` at the bottom of the page.
+
+There are several ways to get Bugzilla to send email. The easiest is to
+use Gmail, so we do that here so you have it working. Visit
+https://gmail.com and create a new Gmail account for your Bugzilla to use.
+Then, open the :guilabel:`Email` section of the Parameters using the link
+in the left column, and set the following parameter values:
+
+* :param:`mail_delivery_method`: :paramval:`SMTP`
+* :param:`mailfrom`: :paramval:`new_gmail_address@gmail.com`
+* :param:`smtpserver`: :paramval:`smtp.gmail.com:465`
+* :param:`smtp_username`: :paramval:`new_gmail_address@gmail.com`
+* :param:`smtp_password`: :paramval:`new_gmail_password`
+* :param:`smtp_ssl`: :paramval:`On`
+
+Click :guilabel:`Save Changes` at the bottom of the page.
+
+And you're all ready to go. :-)
diff --git a/docs/en/rst/installing/sanity-check.rst b/docs/en/rst/installing/sanity-check.rst
new file mode 100644
index 000000000..4f8fb11c6
--- /dev/null
+++ b/docs/en/rst/installing/sanity-check.rst
@@ -0,0 +1,26 @@
+.. _sanity-check:
+
+Sanity Check
+############
+
+Over time it is possible for the Bugzilla database to become corrupt
+or to have anomalies. This could happen through manual database
+administration outside of the Bugzilla user interface, or from some
+other unexpected event. Bugzilla includes a "Sanity Check" that
+can perform several basic database checks, and repair certain problems or
+inconsistencies.
+
+To run a Sanity Check, log in as an Administrator and click the
+:guilabel:`Sanity Check` link in the admin page. Any problems that are found
+will be displayed in red letters. If the script is capable of fixing a
+problem, it will present a link to initiate the fix. If the script cannot
+fix the problem it will require manual database administration or recovery.
+
+Sanity Check can also be run from the command line via the perl
+script :file:`sanitycheck.pl`. The script can also be run as
+a :command:`cron` job. Results will be delivered by email to an address
+specified on the command line.
+
+Sanity Check should be run on a regular basis as a matter of
+best practice.
+
diff --git a/docs/en/rst/installing/sqlite.rst b/docs/en/rst/installing/sqlite.rst
new file mode 100644
index 000000000..bf5953666
--- /dev/null
+++ b/docs/en/rst/installing/sqlite.rst
@@ -0,0 +1,14 @@
+.. _sqlite:
+
+SQLite
+######
+
+.. warning:: Due to SQLite's `concurrency
+   limitations <http://sqlite.org/faq.html#q5>`_ we recommend SQLite only for
+   small and development Bugzilla installations.
+
+Once you have SQLite installed, no additional configuration is required to
+run Bugzilla.
+
+The database will be stored in :file:`$BUGZILLA_HOME/data/db/$db_name`, where
+``$db_name`` is the database name defined in :file:`localconfig`.
diff --git a/docs/en/rst/installing/upgrading-customizations.rst b/docs/en/rst/installing/upgrading-customizations.rst
new file mode 100644
index 000000000..c99c6a9f7
--- /dev/null
+++ b/docs/en/rst/installing/upgrading-customizations.rst
@@ -0,0 +1,20 @@
+.. _upgrading-customizations:
+
+Upgrading a Customized or Extended Bugzilla
+###########################################
+
+If your Bugzilla has been customized or uses extensions, you will need to
+make your customizations or extensions work with your new version of Bugzilla.
+If this is the case, you are particularly strongly recommended to do a test
+upgrade on a test system and use that to help you port forward your
+customizations.
+
+If your extension came from a third party, look to see if an updated version
+is available for the version of Bugzilla you are upgrading to. If not, and
+you want to continue using it, you'll need to port it forward yourself.
+
+If you are upgrading from a version of Bugzilla earlier than 3.6 and have
+extensions for which a newer version is not available from an upstream source,
+then you need to convert them. This is because the extension format changed
+in version 3.6. There is a file called :file:`extension-convert.pl` in the
+:file:`contrib` directory which may be able to help you with that.
diff --git a/docs/en/rst/installing/upgrading-with-1.inc.rst b/docs/en/rst/installing/upgrading-with-1.inc.rst
new file mode 100644
index 000000000..4861f6ea9
--- /dev/null
+++ b/docs/en/rst/installing/upgrading-with-1.inc.rst
@@ -0,0 +1,41 @@
+Before You Upgrade
+==================
+
+Before you start your upgrade, there are a few important
+steps to take:
+
+#. Read the
+   `Release Notes <http://www.bugzilla.org/releases/>`_ of the version you're
+   upgrading to and all intermediate versions, particularly the "Notes for
+   Upgraders" sections, if present. They may make you aware of additional
+   considerations.
+
+#. Run the :ref:`sanity-check` on your installation. Attempt to fix all
+   warnings that the page produces before you start, or it's
+   possible that you may experience problems during your upgrade.
+
+#. Work out how to :ref:`back up <backups>` your Bugzilla entirely, and
+   how to restore from a backup if need be.
+
+Customized Bugzilla?
+--------------------
+
+If you have modified the code or templates of your Bugzilla,
+then upgrading requires a bit more thought and effort than the simple process
+below. See :ref:`template-method` for a discussion of the various methods of
+code customization that may have been used.
+
+The larger the jump you are trying to make, the more difficult it
+is going to be to upgrade if you have made local code customizations.
+Upgrading from 4.2 to 4.2.1 should be fairly painless even if
+you are heavily customized, but going from 2.18 to 4.2 is going
+to mean a fair bit of work re-writing your local changes to use
+the new files, logic, templates, etc. If you have done no local
+changes at all, however, then upgrading should be approximately
+the same amount of work regardless of how long it has been since
+your version was released.
+
+If you have made customizations, you should do the upgrade on a test system
+with the same configuration and make sure all your customizations still work.
+If not, port and test them so you have them ready to reapply once you do
+the upgrade for real.
diff --git a/docs/en/rst/installing/upgrading-with-2.inc.rst b/docs/en/rst/installing/upgrading-with-2.inc.rst
new file mode 100644
index 000000000..d8e2dbfaa
--- /dev/null
+++ b/docs/en/rst/installing/upgrading-with-2.inc.rst
@@ -0,0 +1,32 @@
+Upgrading the Database
+======================
+
+Run :file:`checksetup.pl`. This will do everything required to convert
+your existing database and settings to the new version.
+
+:command:`cd $BUGZILLA_HOME`
+
+:command:`./checksetup.pl`
+
+   .. warning:: For some upgrades, running :file:`checksetup.pl` on a large
+      installation (75,000 or more bugs) can take a long time,
+      possibly several hours, if e.g. indexes need to be rebuilt. If this
+      length of downtime would be a problem for you, you can determine
+      timings for your particular situation by doing a test upgrade on a
+      development server with the production data.
+
+:file:`checksetup.pl` may also tell you that you need some additional
+Perl modules, or newer versions of the ones you have. You will need to
+install these, either system-wide or using the :file:`install-module.pl`
+script that :file:`checksetup.pl` recommends.
+
+Finishing The Upgrade
+=====================
+
+#. Reactivate Bugzilla by clear the text that you put into the
+   :param:`shutdownhtml` parameter.
+
+#. Run another :ref:`sanity-check` on your
+   upgraded Bugzilla. It is recommended that you fix any problems
+   you see immediately. Failure to do this may mean that Bugzilla
+   may not work entirely correctly. 
diff --git a/docs/en/rst/installing/upgrading-with-a-tarball.rst b/docs/en/rst/installing/upgrading-with-a-tarball.rst
new file mode 100644
index 000000000..2bbfb3158
--- /dev/null
+++ b/docs/en/rst/installing/upgrading-with-a-tarball.rst
@@ -0,0 +1,74 @@
+.. _upgrading-with-a-tarball:
+
+Upgrading with a Tarball
+########################
+
+If you are unable (or unwilling) to use Git, another option is to obtain a
+tarball of the latest version from our website and upgrade your Bugzilla
+installation using that.
+
+Without a source code management system to help you, the process may be
+trickier.
+
+.. include:: upgrading-with-1.inc.rst
+
+As you are using a tarball and not an SCM, it's not at all easy to see if
+you've made local code customizations. You may have to use institutional
+knowledge, or download a fresh copy of your *current* version of Bugzilla
+and compare the two directories. If you find that you have, you'll need
+to turn them into a patch file, perhaps by diffing the two directories,
+and then reapply that patch file later. If you are customizing Bugzilla
+locally, please consider
+:ref:`rebasing your install on top of git <migrating-from-a-tarball>`.
+
+.. _upgrade-files-tarball:
+
+Getting The New Bugzilla
+========================
+
+Download a copy of the latest version of Bugzilla from the
+`Download Page <http://www.bugzilla.org/download/>`_ into a separate
+directory (which we will call :file:`bugzilla-new`) alongside your existing
+Bugzilla installation (which we will assume is in a directory called
+:file:`bugzilla`).
+
+Copy Across Data and Modules
+============================
+
+Copy the contents of the following directories from your current installation
+of Bugzilla into the corresponding directory in :file:`bugzilla-new/`:
+
+.. code-block:: none
+
+  lib/
+  data/
+  template/en/custom (may or may not exist)
+
+You also need to copy any extensions you have written or installed, which are
+in the :file:`extensions/` directory. Bugzilla ships with some extensions,
+so again if you want to know if any of the installed extensions are yours,
+you may have to compare with a clean copy of your current version. You can
+disregard any which have a :file:`disabled` file - those are not enabled.
+
+Lastly, copy the following file from your current installation of Bugzilla
+into the corresponding place in :file:`bugzilla-new/`:
+
+.. code-block:: none
+
+  localconfig
+
+This file contains your database password and access details.
+
+Swap The New Version In
+=======================
+
+Now we swap the directories over. From the directory containing the
+:file:`bugzilla` and :file:`bugzilla-new` directories, run:
+
+:command:`mv bugzilla bugzilla-old`
+
+:command:`mv bugzilla-new bugzilla`
+
+:command:`cd bugzilla`
+
+.. include:: upgrading-with-2.inc.rst
diff --git a/docs/en/rst/installing/upgrading-with-git.rst b/docs/en/rst/installing/upgrading-with-git.rst
new file mode 100644
index 000000000..78b4fb1e0
--- /dev/null
+++ b/docs/en/rst/installing/upgrading-with-git.rst
@@ -0,0 +1,69 @@
+.. _upgrading-with-git:
+
+Upgrading with Git
+##################
+
+Upgrading to new Bugzilla releases is very simple, and you can upgrade
+from any version to any later version in one go - there is no need for
+intermediate steps. There is a script named :file:`checksetup.pl` included
+with Bugzilla that will automatically do all of the database migration
+for you.
+
+.. include:: upgrading-with-1.inc.rst
+
+You can see if you have local code customizations using:
+
+:command:`git diff`
+
+If that comes up empty, then run:
+
+:command:`git log | head`
+
+and see if the last commit looks like one made by the Bugzilla team, or
+by you. If it looks like it was made by us, then you have made no local
+code customizations.
+
+.. _start-upgrade-git:
+
+Starting the Upgrade
+====================
+
+When you are ready to go:
+
+#. Shut down your Bugzilla installation by putting some explanatory text
+   in the :param:`shutdownhtml` parameter.
+
+#. Make all necessary :ref:`backups <backups>`.
+   *THIS IS VERY IMPORTANT*. If anything goes wrong during the upgrade,
+   having a backup allows you to roll back to a known good state.
+
+.. _upgrade-files-git:
+
+Getting The New Bugzilla
+========================
+
+In the commands below, ``$BUGZILLA_HOME`` represents the directory
+in which Bugzilla is installed. Assuming you followed the installation
+instructions and your Bugzilla is a checkout of a stable branch,
+you can get the latest point release of your current version by simply doing:
+
+:command:`cd $BUGZILLA_HOME`
+
+:command:`git pull`
+
+If you want to upgrade to a newer release of Bugzilla, then you will
+additionally need to do:
+
+:command:`git checkout bugzilla-X.X-stable`
+
+where "X.X" is the 2-digit version number of the stable version you want to
+upgrade to (e.g. "4.4").
+
+.. note:: Do not attempt to downgrade Bugzilla this way - it won't work.
+
+If you have local code customizations, git will attempt to merge them. If
+it fails, then you should implement the plan you came up with when you
+detected these customizations in the step above, before you started the
+upgrade.
+
+.. include:: upgrading-with-2.inc.rst
diff --git a/docs/en/rst/installing/upgrading.rst b/docs/en/rst/installing/upgrading.rst
new file mode 100644
index 000000000..f43897fb3
--- /dev/null
+++ b/docs/en/rst/installing/upgrading.rst
@@ -0,0 +1,70 @@
+.. _upgrading:
+
+Upgrading
+#########
+
+You can upgrade Bugzilla from any version to any later version in one go -
+there is no need to pass through intermediate versions unless you are changing
+the method by which you obtain the code along the way.
+
+.. warning:: Upgrading is a one-way process. You cannot "downgrade" an
+   upgraded Bugzilla. If you wish to revert to the old Bugzilla
+   version for any reason, you will have to restore your system
+   from a backup. Those with critical data or large installations may wish
+   to test the upgrade on a development server first, using a copy of the
+   production data and configuration.
+ 
+Bugzilla uses the Git version control system to store its code. A modern
+Bugzilla installation consists of a checkout of a stable version of the code
+from our Git repository. This makes upgrading much easier. If this is
+already true of your installation, see :ref:`upgrading-with-git`.
+
+Before Git, we used to use Bazaar and, before that, CVS. If your installation
+of Bugzilla consists of a checkout from one of those two systems, you need to
+upgrade in three steps:
+
+1. Upgrade to the latest point release of your current Bugzilla version.
+2. Move to Git while staying on exactly the same release.
+3. Upgrade to the latest Bugzilla using the instructions for :ref:`upgrading-with-git`.
+
+See :ref:`migrating-from-bazaar` or :ref:`migrating-from-cvs` as appropriate.
+
+Some Bugzillas were installed simply by downloading a copy of the code as
+an archive file ("tarball"). However, recent tarballs have included source
+code management system information, so you may be able to use the Git, Bzr
+or CVS instructions.
+
+If you aren't sure which of these categories you fall into, to find out which
+version control system your copy of Bugzilla recognizes, look for the
+following subdirectories in your root Bugzilla directory:
+
+* :file:`.git`: you installed using Git - follow :ref:`upgrading-with-git`.
+* :file:`.bzr`: you installed using Bazaar - follow :ref:`migrating-from-bazaar`.
+* :file:`CVS`: you installed using CVS - follow :ref:`migrating-from-cvs`.
+* None of the above: you installed using an old tarball - follow
+  :ref:`migrating-from-a-tarball`.
+
+It is also possible, particularly if your server machine does not have and
+cannot be configured to have access to the public internet, to upgrade using
+a tarball. See :ref:`upgrading-with-a-tarball`.
+
+Whichever path you use, you may need help with
+:ref:`upgrading-customizations`.
+
+.. toctree::
+   :maxdepth: 1
+
+   upgrading-with-git
+   migrating-from-bzr
+   migrating-from-cvs
+   migrating-from-a-tarball
+   upgrading-with-a-tarball
+   upgrading-customizations
+
+Bugzilla can automatically notify administrators when new releases are
+available if the :param:`upgrade_notification` parameter is set.
+Administrators will see these notifications when they access the Bugzilla home
+page. Bugzilla will check once per day for new releases. If you are behind a
+proxy, you may have to set the :param:`proxy_url` parameter accordingly. If
+the proxy requires authentication, use the
+:paramval:`http://user:pass@proxy_url/` syntax.
diff --git a/docs/en/rst/installing/windows.rst b/docs/en/rst/installing/windows.rst
new file mode 100644
index 000000000..e70483daf
--- /dev/null
+++ b/docs/en/rst/installing/windows.rst
@@ -0,0 +1,175 @@
+.. _windows:
+
+Windows
+#######
+
+Making Bugzilla work on Windows is more difficult than making it work on Unix,
+fewer Bugzilla developers use it and so it's less well supported. We would
+particularly recommend against doing it for a large site. However, if
+you are still determined to go ahead, here's how.
+
+.. windows-install-perl:
+
+ActiveState Perl
+================
+
+ActiveState make a popular distribution of Perl for Windows.
+
+Download the ActiveState Perl 5.12.4 or higher MSI installer from the
+`ActiveState website <http://www.activestate.com/activeperl/downloads>`_.
+
+ActiveState Perl uses a standard Windows Installer. Install, sticking with
+the defaults, which will install Perl into :file:`C:\\Perl`. It is not
+recommended to install Perl into a directory containing a space, such as
+:file:`C:\\Program Files`.
+
+Once the install has completed, log out and log in again to pick up the
+changes to the ``PATH`` environment variable.
+
+.. _windows-install-bzfiles:
+
+Bugzilla
+========
+
+The best way to get Bugzilla is to check it out from git. Download and install
+git from the `git website <http://git-scm.com/download>`_, and then run:
+
+:command:`git clone --branch bugzilla-X.X-stable https://git.mozilla.org/bugzilla/bugzilla C:\\bugzilla`
+
+where "X.X" is the 2-digit version number of the stable release of Bugzilla
+that you want (e.g. 4.4).
+
+The rest of this documentation assumes you have installed Bugzilla into
+:file:`C:\\bugzilla`. Adjust paths appropriately if not.
+
+If it's not possible to use git (e.g. because your Bugzilla machine has no
+internet access), you can
+`download a tarball of Bugzilla <http://www.bugzilla.org/download/>`_ and
+copy it across. Bugzilla comes as a 'tarball' (:file:`.tar.gz` extension),
+which any competent Windows archiving tool should be able to open.
+
+.. windows-install-perl-modules:
+
+Perl Modules
+============
+
+Bugzilla requires a number of perl modules to be installed. They are
+available in the ActiveState repository, and are installed with the
+:file:`ppm` tool. You can either use it on the command line, as below,
+or just type :command:`ppm`, and you will get a GUI.
+
+If you use a proxy server or a firewall you may have trouble running PPM.
+This is covered in the
+`ActivePerl FAQ <http://aspn.activestate.com/ASPN/docs/ActivePerl/faq/ActivePerl-faq2.html#ppm_and_proxies>`_.
+
+Install the following modules with:
+
+:command:`ppm install <modulename>`
+
+* CGI.pm
+* Digest-SHA
+* TimeDate
+* DateTime
+* DateTime-TimeZone
+* DBI
+* Template-Toolkit
+* Email-Sender
+* Email-MIME
+* URI
+* List-MoreUtils
+* Math-Random-ISAAC
+* File-Slurp
+* JSON-XS
+* Win32
+* Win32-API
+
+The following modules enable various optional Bugzilla features; try and
+install them, but don't worry too much to begin with if you can't get them
+installed:
+
+* GD
+* Chart
+* Template-GD
+* GDTextUtil
+* GDGraph
+* MIME-tools
+* libwww-perl
+* XML-Twig
+* PatchReader
+* perl-ldap
+* Authen-SASL
+* Net-SMTP-SSL
+* RadiusPerl
+* SOAP-Lite
+* XMLRPC-Lite
+* JSON-RPC
+* Test-Taint
+* HTML-Parser
+* HTML-Scrubber
+* Encode
+* Encode-Detect
+* Email-Reply
+* HTML-FormatText-WithLinks
+* TheSchwartz
+* Daemon-Generic
+* mod_perl
+* Apache-SizeLimit
+* File-MimeInfo
+* IO-stringy
+* Cache-Memcached
+* Text-Markdown
+* File-Copy-Recursive
+* GraphViz
+
+.. warning:: These lists have been extracted from Bugzilla's source code and
+             have not been tested. Please let us know if you find errors in it
+             of any sort.
+
+.. note:: The :file:`install-module.pl` script doesn't work with ActivePerl
+   on Windows.
+
+.. _windows-config-webserver:
+
+Web Server
+==========
+
+Any web server that is capable of running CGI scripts can be made to work.
+We have specific instructions for the following:
+
+* :ref:`apache-windows`
+* :ref:`iis`
+
+.. windows-config-database:
+
+Database Engine
+===============
+
+Bugzilla supports MySQL, PostgreSQL, Oracle and SQLite as database servers.
+You only require one of these systems to make use of Bugzilla. MySQL is
+most commonly used, and is the only one for which Windows instructions have
+been tested. SQLite is good for trial installations as it requires no
+setup. Configure your server according to the instructions below:
+
+* :ref:`mysql`
+* :ref:`postgresql`
+* :ref:`oracle`
+* :ref:`sqlite`
+
+.. |checksetupcommand| replace:: :command:`checksetup.pl`
+.. |testservercommand| replace:: :command:`testserver.pl http://<your-bugzilla-server>/`
+
+.. include:: installing-end.inc.rst
+
+If you don't see the main Bugzilla page, but instead see "It works!!!",
+then somehow your Apache has not picked up your modifications to
+:file:`httpd.conf`. If you are on Windows 7 or later, this could be due to a
+new feature called "VirtualStore". `This blog post
+<http://blog.netscraps.com/bugs/apache-httpd-conf-changes-ignored-in-windows-7.html>`_
+may help to solve the problem.
+
+If you get an "Internal Error..." message, it could be that
+``ScriptInterpreterSource Registry-Strict`` is not set in your
+:ref:`Apache configuration <apache-windows>`. Check again if it is set
+properly.
+
+Next, do the :ref:`essential-post-install-config`.