If you want to try out Bugzilla to see if it meets your needs, you can do so on
`Mozilla’s Bugzilla (BMO) test server <https://bugzilla-dev.allizom.org/>`_,
though it comes with various Mozilla-specific customizations. The easiest way to
-explore the admin tools and more is `running a minimum local copy of BMO
-<https://github.com/mozilla-bteam/bmo/blob/master/README.rst>`_ using Vagrant or
-Docker. We are not offering any online vanilla test environment at this time.
+explore the admin tools and more is :ref:`running a minimum local copy of
+BMO <docker>` using Vagrant or Docker. We are not offering a generic
+test environment at this time.
The `Bugzilla FAQ <https://wiki.mozilla.org/Bugzilla:FAQ>`_ may also be helpful,
as it answers a number of questions people sometimes have about whether Bugzilla
about/index
using/index
+ installing/index
administering/index
integrating/index
api/index
--- /dev/null
+.. _apache-windows:
+
+Apache on Windows
+#################
+
+Bugzilla supports all versions of Apache 2.2.x and 2.4.x.
+
+Installing
+==========
+
+Download the Apache HTTP Server as a :file:`.zip` archive either from the
+`Apache Lounge website <http://www.apachelounge.com/download>`_ or from the
+`Apache Haus website <http://www.apachehaus.com/cgi-bin/download.plx>`_.
+
+Unzip the archive into :file:`C:\\Apache24`. If you move it elsewhere, then
+you must edit several variables in :file:`httpd.conf`, including ``ServerRoot``
+and ``DocumentRoot``.
+
+You must now edit the Apache configuration file :file:`C:\\Apache24\\conf\\httpd.conf`
+and do the following steps:
+
+#. Uncomment ``LoadModule cgi_module modules/mod_cgi.so`` at the beginning of the
+ file to enable CGI support.
+#. Uncomment ``AddHandler cgi-script .cgi`` to register :file:`.cgi` files
+ as CGI scripts. For this handler to work, you must create a key in the
+ Windows registry named ``HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command`` with
+ the default value pointing to the full path of :file:`perl.exe` with a ``-T``
+ parameter. For example :file:`C:\\Perl\\bin\\perl.exe -T` if you use ActivePerl,
+ or :file:`C:\\Strawberry\\perl\\bin\\perl.exe -T` if you use Strawberry Perl.
+#. Add an Alias and a Directory for Bugzilla:
+
+.. code-block:: apache
+
+ Alias "/bugzilla/" "C:/bugzilla/"
+ <Directory "C:/bugzilla">
+ ScriptInterpreterSource Registry-Strict
+ Options +ExecCGI +FollowSymLinks
+ DirectoryIndex index.cgi index.html
+ AllowOverride All
+ Require all granted
+ </Directory>
+
+.. warning:: The above block takes a simple approach to access control and is
+ correct for Apache 2.4. For Apache 2.2, replace ``Require all granted``
+ with ``Allow from all``. If you have other access control
+ requirements, you may need to make further modifications.
+
+You now save your changes and start Apache as a service. From the Windows
+command line (:file:`cmd.exe`):
+
+:command:`C:\\Apache24\\bin>httpd.exe -k install`
+
+That's it! Bugzilla is now accessible from http://localhost/bugzilla.
+
+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:\\Apache24\\logs`
+* :file:`C:\\Windows\\Temp`
+
+Note that :file:`C:\\Bugzilla\\data` is created the first time you run
+:file:`checksetup.pl`.
+
+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.)
+
+Using Apache with SSL
+=====================
+
+If you want to enable SSL with Apache, i.e. access Bugzilla from
+https://localhost/bugzilla, you need to do some extra steps:
+
+#. Edit :file:`C:\\Apache24\\conf\\httpd.conf` and uncomment these lines:
+
+ * ``LoadModule ssl_module modules/mod_ssl.so``
+ * ``LoadModule socache_shmcb_module modules/mod_socache_shmcb.so``
+ * ``Include conf/extra/httpd-ssl.conf``
+
+#. Create your :file:`.key` and :file:`.crt` files using :file:`openssl.exe`
+ provided with Apache:
+
+ :command:`C:\\Apache24\\bin>openssl.exe req -x509 -nodes -days 730 -newkey rsa:2048 -keyout server.key -out server.crt`
+
+ :file:`openssl.exe` will ask you a few questions about your location and
+ your company name to populate fields of the certificate.
+
+#. Once the key and the certificate for your server are generated, move them
+ into :file:`C:\\Apache24\\conf` so that their location matches the
+ ``SSLCertificateFile`` and ``SSLCertificateKeyFile`` variables defined in
+ :file:`C:\\Apache24\\conf\\extra\\httpd-ssl.conf` (which you don't need to
+ edit).
+
+.. note:: This process leads to a self-signed certificate which will generate
+ browser warnings on first visit. If your Bugzilla has a public DNS
+ name, you can get a cert from a CA which will not have this problem.
+
+Restart Apache
+==============
+
+Finally, restart Apache to pick up the changes, either from the Services
+console or from the command line:
+
+:command:`C:\\Apache24\\bin>httpd.exe -k restart`
--- /dev/null
+.. 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 All
+ </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.
+
+On some Linux distributions you will need to enable the Apache CGI
+module. On Debian/Ubuntu, this is done with:
+
+:command:`sudo a2enmod cgi`
+
+If you find that the webserver is returning the Perl code as text rather
+than executing it, then this is the problem.
+
+.. _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.
--- /dev/null
+.. _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 --max-allowed-packet=32M -u $USERNAME -p $DATABASENAME > backup.sql`
+
+The value for :command:`max-allowed-packet` should be the value you've set in
+your :ref:`MySQL configuration file <mysql>`, and should be larger than the
+largest attachment in your database. See the
+`mysqldump documentation <http://dev.mysql.com/doc/mysql/en/mysqldump.html>`_
+for more information on :file:`mysqldump`.
+
+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`
+
--- /dev/null
+.. _db_server:
+
+Database Server
+###############
+
+Bugzilla requires a database to store its data. We recommend either MySQL or
+PostgreSQL for production installations. Oracle 10 should work fine, but very
+little or no testing has been done with Oracle 11 and 12. SQLite is easy to
+configure but, due to its limitations, it should only be used for testing
+purposes and very small installations.
+
+.. toctree::
+ :maxdepth: 1
+
+ mysql
+ postgresql
+ oracle
+ sqlite
--- /dev/null
+.. _docker:
+
+Evaluating with Docker
+######################
+
+.. Placeholder for running under docker.
+
+.. note:: At this time the Bugzilla team has not produced a production
+ Docker container for running the server in production. These instructions
+ cover running Bugzilla in a docker container for evaluation.
+
+See the `Docker instructions <https://github.com/bugzilla/harmony/blob/main/docker/README.md>`_.
--- /dev/null
+.. _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:`cookiepath`: 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
+ cookiepath. 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`.
--- /dev/null
+.. _iis:
+
+Microsoft IIS
+#############
+
+Bugzilla works with IIS as a normal CGI application. These instructions assume
+that you are using Windows 7 or Windows 10. 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:`Yes`.
+
+.. 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.
+
+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:`Yes`.
+
+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:`Yes`.
+
+Now it's time to restart the IIS server to take these changes into account.
+From the top-level menu, which contains the name of your machine, click
+:guilabel:`Restart` under :guilabel:`Manage Server`. Or run the command:
+
+:command:`iisreset`
+
+Enable Rewrite Rules for REST
+=============================
+
+REST URLs are usually of the form http://.../bugzilla/rest/version instead of
+http://.../bugzilla/rest.cgi/version. To let IIS redirect rest/ URLs to rest.cgi,
+you need to download and install the
+`URL Rewrite extension for IIS <http://www.iis.net/downloads/microsoft/url-rewrite>`_.
+Direct download links are available at the bottom of the page for both x86 and
+x64 Windows.
+
+Once installed, you open the IIS Manager again and go to your Bugzilla
+Application. From here, double-click :guilabel:`URL Rewrite`. Then click
+:guilabel:`Add Rule(s)` under the :guilabel:`Actions` menu and click
+:guilabel:`Blank rule` in the :guilabel:`Inbound rules` section.
+
+Fill the fields as follows. Other fields do not need to be edited.
+
+* :guilabel:`Name`: ``REST``
+* :guilabel:`Pattern`: ``^rest/(.*)$``
+* :guilabel:`Rewrite URL`: ``rest.cgi/{R:1}``
+
+There is no need to restart IIS. Changes take effect immediately.
+
+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.
--- /dev/null
+.. highlight:: console
+
+.. _installing:
+
+==================================
+Installation and Maintenance Guide
+==================================
+
+.. warning:: This section, as is, is copied over from the mainline Bugzilla
+ install documentation. There are significant changes in how
+ Harmony should be deployed. As such, do not refer to this
+ documentation for now, but use the `Docker instructions
+ <https://github.com/bugzilla/harmony/blob/main/docker/README.md>`_
+ as a guide. The Bugzilla team are revising this section.
+
+.. 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. See 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, read the :ref:`Quick Start instructions <quick-start>`.
+
+If you wish to run a local evaluation instance of Bugzilla, see the :ref:`Docker instructions <docker>`.
+
+.. toctree::
+ :maxdepth: 1
+
+ docker
+ quick-start
+ linux
+ windows
+ mac-os-x
+ web_server
+ db_server
+ essential-post-install-config
+ optional-post-install-config
+ migrating
+ moving
+ upgrading
+ backups
+ sanity-check
+ merging-accounts
+ multiple-bugzillas
--- /dev/null
+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.
--- /dev/null
+.. _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 or MariaDB 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, CentOS Stream and RHEL
+------------------------------
+
+The following command will install Fedora's packaged version of Bugzilla:
+
+:command:`dnf install bugzilla httpd mariadb-server`
+
+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
+or have it on RHEL or CentOS, you will need to do the following instead:
+
+On CentOS Stream and RHEl, add the Fedora EPEL repo, in the way described
+in the `installation instructions <https://docs.fedoraproject.org/en-US/epel/>`_.
+
+Run the following to install the base Bugzilla dependencies:
+
+:command:`dnf install git httpd httpd-devel mariadb-devel gcc
+mariadb-server mod_perl mod_perl-devel 'perl(autodie)' 'perl(CGI)'
+'perl(Date::Format)' 'perl(DateTime)' 'perl(DateTime::TimeZone)'
+'perl(DBI)' 'perl(DBD::mysql)' 'perl(DBIx::Connector)' 'perl(Digest::SHA)'
+'perl(Email::MIME)' 'perl(Email::Sender)' 'perl(fields)' 'perl(JSON::XS)'
+'perl(List::MoreUtils)' 'perl(Math::Random::ISAAC)' 'perl(Memoize)'
+'perl(Safe)' 'perl(Template)' 'perl(URI)'`
+
+On Fedora, all the optional dependencies are available:
+
+:command:`dnf install gd-devel graphviz patchutils
+'perl(Apache2::SizeLimit)' 'perl(Authen::Radius)' 'perl(Authen::SASL)'
+'perl(Cache::Memcached)' 'perl(Chart::Lines)' 'perl(Daemon::Generic)'
+'perl(Email::Reply)' 'perl(Encode)' 'perl(Encode::Detect)'
+'perl(File::Copy::Recursive)' 'perl(File::MimeInfo::Magic)'
+'perl(File::Which)' '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(LWP::UserAgent)' 'perl(MIME::Parser)' 'perl(mod_perl2)'
+'perl(Net::LDAP)' 'perl(Net::SMTP::SSL)' 'perl(PatchReader)'
+'perl(SOAP::Lite)' 'perl(Template::Plugin::GD::Image)'
+'perl(Test::Taint)' 'perl(TheSchwartz)' 'perl(XMLRPC::Lite)'
+'perl(XML::Twig)'`
+
+On CentOS Stream and RHEL with EPEL, some modules are missing in the
+repositories, so use the following instead:
+
+:command:`dnf install gd-devel graphviz patchutils
+'perl(Apache2::SizeLimit)' 'perl(Authen::Radius)' 'perl(Authen::SASL)'
+'perl(Cache::Memcached)' 'perl(Encode)' 'perl(Encode::Detect)'
+'perl(File::Copy::Recursive)' 'perl(File::MimeInfo::Magic)'
+'perl(File::Which)' 'perl(GD)' 'perl(GD::Graph)' 'perl(GD::Text)'
+'perl(HTML::Parser)' 'perl(HTML::Scrubber)' 'perl(IO::Scalar)'
+'perl(JSON::RPC)' 'perl(LWP::UserAgent)' 'perl(MIME::Parser)'
+'perl(mod_perl2)' 'perl(Net::LDAP)' 'perl(Net::SMTP::SSL)'
+'perl(SOAP::Lite)' 'perl(Test::Taint)' 'perl(XMLRPC::Lite)'
+'perl(XML::Twig)'`
+
+and install the missing optional modules with:
+
+:command:`cd /var/www/html/bugzilla/ && ./install-module.pl Chart::Lines
+Daemon::Generic Email::Reply HTML::FormatText::WithLinks PatchReader
+Template::Plugin::GD::Image TheSchwartz`
+
+If you plan to use a database other than MariaDB, you will need to also install
+the appropriate packages for that.
+
+Ubuntu and Debian
+-----------------
+
+You can install required packages with:
+:command:`apt install apache2 build-essential git
+libcgi-pm-perl libdatetime-perl libdatetime-timezone-perl
+libdbi-perl libdbix-connector-perl libdigest-sha-perl libemail-address-perl
+libemail-mime-perl libemail-sender-perl libjson-xs-perl
+liblist-moreutils-perl libmath-random-isaac-perl libtemplate-perl
+libtimedate-perl liburi-perl libmariadb-dev-compat libdbd-mysql-perl
+mariadb-server`
+
+If you plan to use a database other than MariaDB, you will need to also install
+the appropriate packages for that (in the command above, the packages required
+for MariaDB are ``libdbd-mysql-perl``, ``libmariadb-dev-compat`` and ``mariadb-server``).
+
+You can install optional packages with:
+:command:`apt install graphviz libapache2-mod-perl2
+libapache2-mod-perl2-dev libauthen-radius-perl libauthen-sasl-perl
+libcache-memcached-perl libchart-perl libdaemon-generic-perl
+libemail-reply-perl libencode-detect-perl libencode-perl
+libfile-copy-recursive-perl libfile-mimeinfo-perl libfile-which-perl
+libgd-dev libgd-graph-perl libgd-perl libgd-text-perl
+libhtml-formattext-withlinks-perl libhtml-parser-perl
+libhtml-scrubber-perl libio-stringy-perl libjson-rpc-perl
+libmime-tools-perl libnet-ldap-perl libnet-smtp-ssl-perl
+libsoap-lite-perl libtemplate-plugin-gd-perl libtest-taint-perl
+libtheschwartz-perl libwww-perl libxmlrpc-lite-perl libxml-twig-perl`
+
+There is no Ubuntu package for ``PatchReader`` and so you will have to install that module
+outside the package manager if you want it.
+
+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>`.
+
+openSUSE
+--------
+
+:command:`zypper in bugzilla`
+
+has been available in the openSUSE Leap repositories since 15.2 and is
+in the openSUSE Tumbleweed repositories, also comes with an optional
+``bugzilla-apache`` package, that allows you to 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 release-X.X-stable https://github.com/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>`
+
+.. _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 (or MariaDB, its compatible counterpart), PostgreSQL,
+Oracle and SQLite as database servers. You only require one of these systems
+to make use of Bugzilla. MySQL or MariaDB are 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`.
--- /dev/null
+.. _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 release-X.X-stable https://github.com/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`.
--- /dev/null
+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.
--- /dev/null
+.. 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.
--- /dev/null
+.. 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
+``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://github.com/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.
--- /dev/null
+.. _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
--- /dev/null
+.. _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
+
+The old bzr.mozilla.org server has been decommissioned. This may not
+be a problem but, in some cases, running some of the commands below will
+make :command:`bzr` attempt to contact the server and time out. If and
+only if that happens to you, you will need to switch to the new server,
+as follows. Enter your Bugzilla directory and run:
+
+:command:`bzr info`
+
+and look at the Location: section of the output.
+If it says "light checkout root" then run:
+
+:command:`bzr -Ossl.cert_reqs=none switch https://bzr.bugzilla.org/bugzilla/$VERSION`
+
+Alternatively, if it says "branch root" or "checkout root" then run:
+
+:command:`bzr -Ossl.cert_reqs=none pull --remember https://bzr.bugzilla.org/bugzilla/$VERSION`
+
+Replace $VERSION with the two-digit version number of your current
+Bugzilla, e.g. "4.2" (see below for how to find that).
+
+.. include:: migrating-from-2.inc.rst
--- /dev/null
+.. _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
+
+
--- /dev/null
+.. _migrating-from-other-btses:
+
+Migrating From Other Bug-Tracking Systems
+#########################################
+
+Bugzilla has a framework you can use for migrating from other bug-tracking
+systems - :api:`Bugzilla::Migrate <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.
+
+
--- /dev/null
+.. _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.
--- /dev/null
+.. _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.
--- /dev/null
+.. _mysql:
+
+MySQL
+#####
+
+It is strongly advised to use MariaDB which is a drop-in replacement for
+MySQL and is fully compatible with Bugzilla. If MySQL must be used, be
+aware that the minimum required version is MySQL 5.0.15 and that MySQL 8
+or higher cannot be used at this time.
+
+All commands in this document work regardless of whether MySQL or
+MariaDB are used.
+
+It's possible to test which version of MySQL you have installed with:
+
+:command:`mysql -V`
+
+Installing
+==========
+
+Windows
+-------
+
+Download the MariaDB 32-bit or 64-bit MSI installer from the
+`MariaDB website <https://mariadb.org/download/?t=mariadb&os=windows>`_ (~66 MB).
+
+MariaDB has a standard Windows installer. It's ok to select a the
+default install options. The rest of this documentation assumes assume you
+have installed MariaDB 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.
+
+Create the Database
+===================
+
+You need to create a database for Bugzilla to use. Run the :file:`mysql`
+command-line client and enter:
+
+::
+ CREATE DATABASE IF NOT EXISTS bugs CHARACTER SET = 'utf8';
+
+The above command makes sure a database like that doesn't exist already.
+
+.. _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
+ :force:
+
+ 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.
--- /dev/null
+.. _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:`graphviz`.
+
+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,
+e.g. :paramval:`C:\\Program Files (x86)\\Graphviz2.38\\bin\\dot.exe`.
+
+Documentation
+=============
+
+Bugzilla has extensive documentation and help, written in
+`reStructured Text <http://sphinx-doc.org/rest.html>`_
+format. A generic compiled copy exists on
+`bugzilla.readthedocs.org <https://bugzilla.readthedocs.org/>`_, and
+:guilabel:`Help` links point to it by default. You can also build and use
+a local copy of the documentation, for instance because you have added Bugzilla
+extensions which come with documentation, or because your users don't have
+Internet access from their machines.
+
+Bugzilla will automatically detect that you've compiled the documentation
+and link to it in preference to the copy on the Internet. Don't forget to
+recompile it when you upgrade Bugzilla or install new extensions.
+
+Linux
+-----
+
+* Install `Sphinx <http://sphinx-doc.org/>`_. Most Linux distros have it in
+ a package named :file:`python-sphinx`.
+
+* Then go to your Bugzilla directory and run:
+
+ :command:`docs/makedocs.pl`
+
+Windows
+-------
+
+* Download and install `Python <https://www.python.org/downloads/>`_.
+ Both Python 2.7 and 3.x will work. Adding :file:`python` to the :param:`PATH`
+ environment variable, as suggested by the Python installer, will make your
+ life easier.
+
+* Install `Sphinx <http://sphinx-doc.org/>`_. Run :command:`cmd.exe` and type:
+
+ :command:`pip install sphinx`
+
+* Then go to your :file:`C:\\bugzilla\\docs` directory and run:
+
+ :command:`makedocs.pl`
--- /dev/null
+.. _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.
--- /dev/null
+.. _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`.)
--- /dev/null
+.. _quick-start:
+
+Quick Start (Ubuntu Linux 22.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 22.04 LTS, Apache and MariaDB. It requires a little familiarity
+with Linux and the command line.
+
+Obtain Your Hardware
+====================
+
+Ubuntu 22.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 22.04 LTS <https://www.ubuntu.com/download/server>`_
+and follow the `installation instructions
+<https://www.ubuntu.com/download/server/install-ubuntu-server>`_.
+Here are some tips:
+
+* You do not need an encrypted lvm group, root or 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 any server name you like.
+* When creating the initial Linux user, call it ``bugzilla``, give it a
+ strong password, and write that password down.
+* From the install options, choose "OpenSSH Server".
+
+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 install git nano`
+
+:command:`apt install apache2 build-essential mariadb-server
+libcgi-pm-perl libdigest-sha-perl libtimedate-perl libdatetime-perl
+libdatetime-timezone-perl libdbi-perl libdbix-connector-perl libtemplate-perl
+libemail-address-perl libemail-sender-perl libemail-mime-perl
+liburi-perl liblist-moreutils-perl libmath-random-isaac-perl
+libjson-xs-perl libgd-perl libchart-perl libtemplate-plugin-gd-perl
+libgd-text-perl libgd-graph-perl libmime-tools-perl libwww-perl
+libxml-twig-perl libnet-ldap-perl libauthen-sasl-perl
+libnet-smtp-ssl-perl libauthen-radius-perl libsoap-lite-perl
+libxmlrpc-lite-perl libjson-rpc-perl libtest-taint-perl
+libhtml-parser-perl libhtml-scrubber-perl libencode-perl
+libencode-detect-perl libemail-reply-perl
+libhtml-formattext-withlinks-perl libtheschwartz-perl
+libdaemon-generic-perl libapache2-mod-perl2 libapache2-mod-perl2-dev
+libfile-mimeinfo-perl libio-stringy-perl libcache-memcached-perl
+libfile-copy-recursive-perl libfile-which-perl libdbd-mysql-perl
+perlmagick lynx graphviz python3-sphinx rst2pdf`
+
+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.
+
+Configure MariaDB
+=================
+
+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/mariadb.conf.d/50-server.cnf`
+
+Set the following values, which increase the maximum attachment size and
+make it possible to search for short words and terms:
+
+* Uncomment and alter on Line 34 to have a value of at least: ``max_allowed_packet=100M``
+* Add as new line 42, in the ``[mysqld]`` section: ``ft_min_word_len=2``
+
+Save and exit.
+
+Create a database ``bugs`` for Bugzilla:
+
+:command:`mysql -u root -e "CREATE DATABASE IF NOT EXISTS bugs CHARACTER SET = 'utf8'"`
+
+Then, add a user to MariaDB for Bugzilla to use:
+
+:command:`mysql -u root -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.
+You should make ``$db_pass`` different to your password.
+
+Restart MariaDB:
+
+:command:`service mariadb restart`
+
+Configure Apache
+================
+
+:command:`nano /etc/apache2/sites-available/bugzilla.conf`
+
+Paste in the following and save:
+
+.. code-block:: apache
+
+ Alias /bugzilla /var/www/webapps/bugzilla
+ <Directory /var/www/webapps/bugzilla>
+ AddHandler cgi-script .cgi
+ Options +ExecCGI
+ DirectoryIndex index.cgi index.html
+ AllowOverride All
+ </Directory>
+
+This configuration sets up Bugzilla to be served on your server under ``/bugzilla`` path.
+For more in depth setup instructions, refer to :ref:`Apache section of this documentation <apache>`.
+
+:command:`a2ensite bugzilla`
+
+:command:`a2enmod cgi headers expires rewrite`
+
+:command:`service apache2 restart`
+
+Download Bugzilla
+=================
+
+Get it from our Git repository:
+
+:command:`mkdir -p /var/www/webapps`
+
+:command:`cd /var/www/webapps`
+
+:command:`git clone --branch release-X.X-stable https://github.com/bugzilla/bugzilla bugzilla`
+
+(where "X.X" is the 2-digit version number of the stable release of Bugzilla
+that you want - e.g. 5.0)
+
+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/webapps/bugzilla`
+
+: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 MariaDB 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/bugzilla`
+
+All the tests should pass. You will get a warning about failing to run
+``gdlib-config``; just ignore it.
+
+.. todo:: ``gdlib-config`` is no longer in Ubuntu.
+
+Access Via Web Browser
+======================
+
+Access the front page:
+
+:command:`lynx http://localhost/bugzilla`
+
+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>/bugzilla``, where ``<ip address>`` is (unless you
+have a complex network setup) the address starting with 192 displayed when
+you run :command:`hostname -I`.
+
+Accessing Bugzilla from the Internet
+====================================
+
+To be able to access Bugzilla from anywhere in the world, you don't have
+to make it internet facing at all, there are free VPN services that let
+you set up your own network that is accessible anywhere. One of those is
+Tailscale, which has a fairly accessible `Quick Start guide <https://tailscale.com/kb/1017/install/>`_.
+
+If you are setting up an internet facing Bugzilla, it's essential to set
+up SSL, so that the communication between the server and users is
+encrypted. For local and intranet installation this matters less, and
+for those cases, you could set up a self signed local certificate
+instead.
+
+There are a few ways to set up free SSL thanks to `Let's Encrypt <https://letsencrypt.org/>`_.
+The two major ones would be Apache's `mod_md <https://httpd.apache.org/docs/2.4/mod/mod_md.html>`_
+and EFF's `certbot <https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal>`_,
+but we don't cover the exact specifics of this here, as that's out of
+scope of this guide.
+
+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>/bugzilla/` or :paramval:`http://<ip address>/bugzilla/`
+* :param:`ssl_redirect`:
+ :paramval:`on` if you set up an SSL certificate
+
+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. :-)
--- /dev/null
+.. _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.
+
--- /dev/null
+.. _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`.
--- /dev/null
+.. _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.
--- /dev/null
+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.
--- /dev/null
+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.
--- /dev/null
+.. _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
--- /dev/null
+.. _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.
+
+Bugzilla is now hosted on Github, but we used to be hosted on git.mozilla.org.
+If you got the code from git.mozilla.org, you need to point your
+checkout at Github instead. To find out, run:
+
+:command:`git remote -v`
+
+If you see "git.mozilla.org" anywhere in the output, then run:
+
+:command:`git remote set-url origin https://github.com/bugzilla/bugzilla`
+
+This change will only ever need to be done once.
+
+.. 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 release-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
--- /dev/null
+.. _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.
--- /dev/null
+.. _web_server:
+
+Web Server
+##########
+
+Bugzilla requires a web server to run CGI scripts. It supports the following:
+
+.. toctree::
+ :maxdepth: 1
+
+ apache
+ apache-windows
+ iis
--- /dev/null
+.. _windows:
+
+Windows
+#######
+
+Making Bugzilla work on Windows is not more difficult than making it work on
+Linux. However, fewer developers use Windows to test Bugzilla and so we would
+still recommend using Linux for large sites to get better support.
+
+.. windows-install-perl:
+
+Perl
+====
+
+You have two main choices to install Perl on Windows: ActivePerl and Strawberry
+Perl.
+
+The ActivePerl Windows Installer can be downloaded from the
+`ActiveState website <http://www.activestate.com/activeperl/downloads>`_.
+Perl will be installed by default 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.
+
+The Strawberry Perl Windows Installer can be downloaded from the
+`Strawberry Perl website <http://strawberryperl.com>`_. Perl will be installed
+by default into :file:`C:\\Strawberry`.
+
+One big advantage of Strawberry Perl over ActivePerl is that with Strawberry
+Perl, you can use the usual tools available on other OSes to install missing
+Perl modules directly from CPAN, whereas ActivePerl requires you to use its own
+:file:`ppm` tool to download pre-compiled Perl modules from ActiveState.
+The modules in the ActivePerl repository may be a bit older than those on CPAN.
+
+.. _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 release-X.X-stable https://github.com/bugzilla/bugzilla C:\\bugzilla`
+
+where "X.X" is the 2-digit version number of the stable release of Bugzilla
+that you want (e.g. 5.0).
+
+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. Some of them are
+mandatory, and some others, which enable additional features, are optional.
+
+If you are using ActivePerl, these modules 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 mandatory 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
+* JSON-XS
+* Win32
+* Win32-API
+* DateTime-TimeZone-Local-Win32
+
+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
+* File-Copy-Recursive
+
+If you are using Strawberry Perl, you should use the :file:`install-module.pl`
+script to install modules, which is the same script used for Linux. Some of
+the required modules are already installed by default. The remaining ones can
+be installed using the command:
+
+:command:`perl install-module.pl <modulename>`
+
+The list of modules to install will be displayed by :file:`checksetup.pl`; see
+below.
+
+.. _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`.
projects / thirdparty / bugzilla.git / commitdiff
