Bug 1849943: copy existing bugzilla installation docs as is (#123)

* copy existing bugzilla installation docs as is

* Add warning, add docker page, add refs to docker page

docs/en/rst/about/index.rst

@@ -20,9 +20,9 @@ Evaluating Bugzilla
 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

docs/en/rst/index.rst

@@ -8,6 +8,7 @@ Bugzilla Documentation (bugzilla.org)
 
    about/index
    using/index
+   installing/index
    administering/index
    integrating/index
    api/index

docs/en/rst/installing/apache-windows.rst

@@ -0,0 +1,136 @@
+.. _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`

docs/en/rst/installing/apache.rst

@@ -0,0 +1,145 @@
+.. 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.

docs/en/rst/installing/backups.rst

@@ -0,0 +1,38 @@
+.. _backups:
+
+Backups
+#######
+
+Database
+========
+
+Here are some sample commands you could use to backup
+your database, depending on what database system you're
+using. You may have to modify these commands for your
+particular setup. Replace the $VARIABLEs with appropriate values for your
+setup.
+
+MySQL
+-----
+
+:command:`mysqldump --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`
+

docs/en/rst/installing/db_server.rst

@@ -0,0 +1,18 @@
+.. _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

docs/en/rst/installing/docker.rst

@@ -0,0 +1,12 @@
+.. _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>`_.