Andrew Pearson,
Ben FrantzDale,
+Byron Jones,
Dave Lawrence,
Dave Miller,
Dawn Endico,
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
+rst_prolog = """
+.. role:: param
+ :class: param
+
+.. role:: paramval
+ :class: paramval
+
+.. role:: group
+ :class: group
+
+.. role:: field
+ :class: field
+
+.. |min-perl-ver| replace:: 5.10.1
+"""
+
+rst_epilog = """
+
+----------
+
+This documentation undoubtedly has bugs; if you find some, please file
+them `here <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation>`_.
+"""
# -- Options for HTML output ---------------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'Bugzilladoc'
-rst_prolog = """
-.. role:: param
- :class: param
-
-.. role:: paramval
- :class: paramval
-
-.. role:: group
- :class: group
-
-.. role:: field
- :class: field
-
-.. |min-perl-ver| replace:: 5.10.1
-"""
-
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
.. toctree::
:maxdepth: 2
- :numbered:
+ :numbered: 4
about/index
installing/index
--- /dev/null
+.. _apache-windows:
+
+Apache
+######
+
+These instructions require editing the Apache configuration file, which is
+at :file:`C:\\Program Files\\Apache Group\\Apache2\\conf\\httpd.conf`.
+
+Installing
+==========
+
+Download the Apache HTTP Server, version 2.2.x or higher, from
+`the Apache website <http://httpd.apache.org/download.cgi>`_.
+
+Apache uses a standard Windows installer. Just follow the prompts, making sure
+you "Install for All Users". Be aware the Apache will always install itself
+into an :file:`Apache2` directory under what ever path you specify. The
+default install path will be displayed as
+:file:`C:\\Program Files\\Apache Group`, which will result in Apache being
+installed to :file:`C:\\Program Files\\Apache Group\\Apache2`.
+
+If you are already running IIS on your machine, you must configure Apache to
+run on a port other than 80, which IIS is using. However you aren't asked the
+port to listen on at install time. Choose "All Users" (which says port 80),
+and we'll change the port later.
+
+The remainder of this document assumes you have installed Apache into
+the default location, :file:`C:\\Program Files\\Apache Group\\Apache2`.
+
+Apache Account Permissions
+==========================
+
+By default Apache installs itself to run as the SYSTEM account. For security
+reasons it's better the reconfigure the service to run as an Apache user.
+Create a new Windows user that is a member of **no** groups, and reconfigure
+the Apache2 service to run as that account.
+
+Whichever account you are running Apache as, SYSTEM or otherwise, needs write
+and modify access to the following directories and all their subdirectories.
+Depending on your version of Windows, this access may already be granted.
+
+* :file:`C:\\Bugzilla\\data`
+* :file:`C:\\Program Files\\Apache Group\\Apache2\\logs`
+* :file:`C:\\Temp`
+* :file:`C:\\Windows\\Temp`
+
+Note that :file:`C:\\Bugzilla\\data` is created the first time you run
+:file:`checksetup.pl`.
+
+Port and DocumentRoot
+=====================
+
+Edit the Apache configuration file (see above).
+
+If you need to change the port that Apache runs on (listens on, or binds to),
+for example because another web server such as IIS is running on the same
+machine, edit the ``Listen`` option and change the value after the colon.
+
+Change the ``DocumentRoot`` setting to point to :file:`C:/Bugzilla`. There
+are two locations in :file:`httpd.conf` that need to be updated (search for
+``DocumentRoot``). You need to use ``/`` instead of ``\`` as a path separator.
+
+Enable CGI Support
+==================
+
+Edit the Apache configuration file (see above).
+
+To enable CGI support in Apache, you need to enable the CGI handler, by
+uncommenting the ``AddHandler cgi-script .cgi`` line.
+
+Teach Apache About Bugzilla
+===========================
+
+Edit the Apache configuration file (see above).
+
+Add the following stanza:
+
+.. code-block:: apache
+
+ <Directory "C:/Bugzilla">
+ ScriptInterpreterSource Registry-Strict
+ Options Indexes FollowSymLinks ExecCGI
+ DirectoryIndex index.cgi index.html
+ AllowOverride All
+ Order allow,deny
+ Allow from all
+ </Directory>
+
+.. todo:: This is still a bit different from the Linux instructions (apart
+ from ScriptInterpreterSource, obviously). Is that intended?
+
+In order for ``ScriptInterpreterSource Registry-Strict`` to work, you also
+need to add an entry to the Registry so Apache will use Perl to execute .cgi
+files.
+
+Create a key ``HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command`` with the
+default value of the full path of :file:`perl.exe` with a ``-T`` parameter.
+For example :file:`C:\\Perl\\bin\\perl.exe -T`.
+
+Logging
+=======
+
+Unless you want to keep statistics on how many hits your Bugzilla install is
+getting, it's a good idea to disable logging by commenting out the
+``CustomLog`` directive in the Apache config file.
+
+If you don't disable logging, you should at least disable logging of "query
+strings". When external systems interact with Bugzilla via webservices
+(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL
+(in the query string). Therefore, to avoid storing passwords in clear text
+on the server we recommend configuring Apache to not include the query string
+in its log files.
+
+#. Find the following line in the Apache config file, which defines the
+ logging format for ``vhost_combined``:
+
+ .. code-block:: apache
+
+ LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined
+
+#. Replace ``%r`` with ``%m %U``.
+
+.. todo:: Is this the right line? Or given how we've configured it above, is it not a vhost?
+
+Restart Apache
+==============
+
+Finally, restart Apache to get it pick up the changes:
+
+:command:`net stop apache2`
+
+:command:`net start apache2`
-.. _apache:
+.. This document is shared among all non-Windows OSes.
+
+.. _apache-linux:
Apache
######
should probably only consider mod_perl if your Bugzilla is going to be heavily
used.
-These instructions require editing the Apache configuration file.
-In Fedora and Red Hat Linux, this file is found as
-:file:`/etc/httpd/conf/httpd.conf`.
-In Ubuntu and Debian, it is :file:`/etc/apache2/apache2.conf`. Alternatively,
-on those latter two distributions, you can instead put the below code into a
+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/`.
Securing Apache
.. code-block:: apache
- <Directory /var/www/html/bugzilla>
- AddHandler cgi-script .cgi
- Options +ExecCGI +FollowSymLinks
- DirectoryIndex index.cgi index.html
- AllowOverride Limit FileInfo Indexes Options
- </Directory>
-
-These instructions allow Apache to run .cgi files found
-within the Bugzilla directory; instructs the server to look
-for a file called :file:`index.cgi` or, if not
-found, :file:`index.html` if someone
-only types the directory name into the browser; and allows
-Bugzilla's :file:`.htaccess` files to override
+ <Directory /var/www/html/bugzilla>
+ AddHandler cgi-script .cgi
+ Options +ExecCGI +FollowSymLinks
+ DirectoryIndex index.cgi index.html
+ AllowOverride Limit FileInfo Indexes Options
+ </Directory>
+
+These instructions allow Apache to run .cgi files found within the Bugzilla
+directory; instructs the server to look for a file called :file:`index.cgi`
+or, if not found, :file:`index.html` if someone only types the directory name
+into the browser; and allows Bugzilla's :file:`.htaccess` files to override
some global permissions.
-.. note:: On Windows, you may have to also add the
- ``ScriptInterpreterSource Registry-Strict``
- line; see :ref:`Windows specific notes <win32-http>`.
-
.. _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
-:orphan:
+.. _essential-post-install-config:
+
+Essential Post-Installation Configuration
+#########################################
+
+Bugzilla is configured in the Administration Parameters. Log in with the
+administrator account you defined in the last :file:`checksetup.pl` run,
+then click :guilabel:`Administration` in the header, and then
+:guilabel:`Parameters`. You will see the different parameter sections
+down the left hand side of the page.
+
+.. _config-essential-params:
+
+Parameters
+==========
+
+There are a few parameters which it is very important to define (or
+explicitly decide not to change).
+
+The first set of these are in the :guilabel:`Required Settings` section.
+
+* :param:`urlbase`: this is the URL by which people should access
+ Bugzilla's front page.
+* :param:`sslbase`: if you have configured SSL on your Bugzilla server,
+ this is the SSL URL by which people should access Bugzilla's front page.
+* :param:`ssl_redirect`: Set this if you want everyone to be redirected
+ to use the SSL version. Recommended if you have set up SSL.
+* :param:`cookiebase`: Bugzilla uses cookies to remember who each user is.
+ In order to set those cookies in the correct scope, you may need to set a
+ cookiebase. If your Bugzilla is at the root of your domain, you don't need
+ to change the default value.
+
+You may want to put your email address in the :param:`maintainer`
+parameter in the :guilabel:`General` section. This will then let people
+know who to contact if they see problems or hit errors.
+
+If you don't want just anyone able to read your Bugzilla, set the
+:param:`requirelogin` parameter in the :guilabel:`User Authentication`
+section, and change or clear the :param:`createemailregexp` parameter.
.. _email:
Email
-#####
+=====
Bugzilla requires the ability to set up email. You have a number of choices
here. The simplest is to get Gmail or some other email provider to do the
.. _install-MTA:
Use Another Mail Server
-=======================
+-----------------------
This section corresponds to choosing a :param:`mail_delivery_method` of
:paramval:`SMTP`.
:param:`smtp_password`)
* Whether the server uses SSL (Parameter: :param:`smtp_ssl`)
* The address you should be sending mail 'From' (Parameter:
- :param:`mailfrom``)
+ :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:`smtp_ssl`: :paramval:`On`
Run Your Own Mail Server
-========================
+------------------------
This section corresponds to choosing a :param:`mail_delivery_method` of
:paramval:`Sendmail`.
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.
+
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
If a simple mail sent with the command-line :file:`mail` program
succeeds, then Bugzilla should also be fine.
+
+.. _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.
-:orphan:
-
.. _iis:
Microsoft IIS
#############
-If you are running Bugzilla on Windows and choose to use
-Microsoft's *Internet Information Services*
-or *Personal Web Server* you will need
-to perform a number of other configuration steps as explained below.
-You may also want to refer to the following Microsoft Knowledge
-Base articles:
-`245225 - HOW TO: Configure and Test a PERL Script with IIS 4.0,
-5.0, and 5.1 <http://support.microsoft.com/default.aspx?scid=kb;en-us;245225>`_
-(for *Internet Information Services*) and
-`231998 - HOW TO: FP2000: How to Use Perl with Microsoft Personal Web
-Server on Windows 95/98 <http://support.microsoft.com/default.aspx?scid=kb;en-us;231998>`_
-(for *Personal Web Server*).
-
-You will need to create a virtual directory for the Bugzilla
-install. Put the Bugzilla files in a directory that is named
-something *other* than what you want your
-end-users accessing. That is, if you want your users to access
-your Bugzilla installation through
-``http://<yourdomainname>/Bugzilla``, then do
-*not* put your Bugzilla files in a directory
-named ``Bugzilla``. Instead, place them in a different
-location, and then use the IIS Administration tool to create a
-Virtual Directory named "Bugzilla" that acts as an alias for the
-actual location of the files. When creating that virtual directory,
-make sure you add the ``Execute (such as ISAPI applications or
-CGI)`` access permission.
-
-You will also need to tell IIS how to handle Bugzilla's
-.cgi files. Using the IIS Administration tool again, open up
-the properties for the new virtual directory and select the
-Configuration option to access the Script Mappings. Create an
-entry mapping .cgi to:
-
-::
-
- <full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s
-
-For example:
-
-::
-
- c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
-
-.. note:: The ActiveState install 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.
-
-IIS will also need to know that the index.cgi should be treated
-as a default document. On the Documents tab page of the virtual
-directory properties, you need to add index.cgi as a default
-document type. If you wish, you may remove the other default
-document types for this particular virtual directory, since Bugzilla
-doesn't use any of them.
-
-Also, and this can't be stressed enough, make sure that files
-such as :file:`localconfig` and your
-:file:`data` directory are
-secured.
-
-.. todo:: See also https://wiki.mozilla.org/Installing_under_IIS_7.5
+Bugzilla works with IIS as a normal CGI application. These instructions assume
+that you are using Windows 7 Ultimate x64. Procedures for other versions are
+probably similar.
+
+Begin by starting Internet Information Services (IIS) Manager.
+:guilabel:`Start` --> :guilabel:`Administrators Tools` -->
+:guilabel:`Internet Information Services (IIS) Manager`. Or run the command:
+
+:command:`inetmgr`
+
+Create a New Application
+========================
+
+Expand your :guilabel:`Server` until the :guilabel:`Default Web Site` shows
+its children.
+
+Right-click :guilabel:`Default Web Site` and select
+:guilabel:`Add Application` from the menu.
+
+Unde :guilabel:`Alias`, enter the alias for the website. This is the path
+below the domain where you want Bugzilla to appear.
+
+Under :guilabel:`Physical Path`, enter the path to Bugzilla,
+:file:`C:\\Bugzilla`.
+
+When finished, click :guilabel:`OK`.
+
+Configure the Default Document
+==============================
+
+Click on the Application that you just created. Double-click on
+:guilabel:`Default Document`, and click :guilabel:`Add` underneath the
+Actions menu.
+
+Under :guilabel:`Name`, enter ``index.cgi``.
+
+All other default documents can be removed for this application.
+
+.. warning:: Do not delete the default document from the
+ :guilabel:`Default Website`.
+
+Add Handler Mappings
+====================
+
+Ensure that you are at the Default Website. Under :guilabel:`IIS`,
+double-click :guilabel:`Handler Mappings`. Under :guilabel:`Actions`, click
+:guilabel:`Add Script Map`. You need to do this twice.
+
+For the first one, set the following values (replacing paths if necessary):
+
+* :guilabel:`Request Path`: ``*.pl``
+* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe "%s% %s%``
+* :guilabel:`Name`: ``Perl Script Map``
+
+At the prompt select :guilabel:`No`.
+
+.. note:: The ActiveState Perl installer may have already created an entry for
+ .pl files that is limited to ``GET,HEAD,POST``. If so, this mapping should
+ be removed, as Bugzilla's .pl files are not designed to be run via a web
+ server.
+
+.. todo:: My `source <https://wiki.mozilla.org/Installing_under_IIS_7.5>`_ says
+ to add a mapping for .pl, but that's sort of contradicted by the note above
+ from a different source. Which is right?
+
+For the second one, set the following values (replacing paths if necessary):
+
+* :guilabel:`Request Path`: ``*.cgi``
+* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe "%s% %s%``
+* :guilabel:`Name`: ``CGI Script Map``
+
+At the prompt select :guilabel:`No`.
+
+Bugzilla Application
+====================
+
+Ensure that you are at the Bugzilla Application. Under :guilabel:`IIS`,
+double-click :guilabel:`Handler Mappings`. Under :guilabel:`Actions`, click
+:guilabel:`Add Script Map`.
+
+Set the following values (replacing paths if necessary):
+
+* :guilabel:`Request Path`: ``*.cgi``
+* :guilabel:`Executable`: ``C:\Perl\bin\perl.exe -x"C:\Bugzilla" -wT "%s" %s``
+* :guilabel:`Name`: ``Bugzilla``
+
+At the prompt select :guilabel:`No`.
+
+.. todo:: The Executable lines in the three things above are weirdly
+ inconsistent. Is this intentional? My source is `this page <https://wiki.mozilla.org/Installing_under_IIS_7.5>`_.
+
+.. todo:: `LpSolit <http://lpsolit.wordpress.com/2010/10/22/make-bugzilla-work-with-iis7-easy/>`_
+ suggests there's a step to do with authorizing CGI modules. Where does that fit?
+
+Common Problems
+===============
+
+Bugzilla runs but it's not possible to log in
+ You've probably configured IIS to use ActiveState's ISAPI DLL -- in other
+ words you're using PerlEx, or the executable IIS is configured to use is
+ :file:`PerlS.dll` or :file:`Perl30.dll`.
+
+ Reconfigure IIS to use :file:`perl.exe`.
+
+IIS returns HTTP 502 errors
+ You probably forgot the ``-T`` argument to :file:`perl` when configuring the
+ executable in IIS.
+
+XMLRPC interface not working with IIS
+ This is a known issue. See :bug:`708252`.
linux
windows
mac-os-x
- post-install-config
+ essential-post-install-config
+ optional-post-install-config
migrating
moving
--- /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.
.. todo:: Which versions of RHEL have packages new enough for us to support them?
+.. _linux-install-packages:
+
Install Packages
================
------------------
The following command will install Red Hat's packaged version of Bugzilla:
+
:command:`yum install bugzilla httpd mysql-server`
However, if you go this route, you need to read :bug:`415605`, which details
-some problems with the Bugzilla rpm. Then, you can skip to
-:ref:`configuring your database <config-database>`. It may be useful to know
-that Fedora stores the Bugzilla files in :file:`/usr/share/bugzilla`, so
+some problems with the Email::Send package. Then, you can skip to
+:ref:`configuring your database <linux-config-database>`. It may be useful to
+know that Fedora stores the Bugzilla files in :file:`/usr/share/bugzilla`, so
that's where you'll run :file:`checksetup.pl`.
If you want to install a version of Bugzilla from the Bugzilla project, you
If you are running RHEL6, you will have to enable the "RHEL Server Optional"
channel in RHN to get some of those packages.
+.. todo:: Add Sqlite RPMs
+
Ubuntu and Debian
-----------------
libtest-taint-perl libauthen-radius-perl libfile-slurp-perl
libencode-detect-perl libmodule-build-perl libnet-ldap-perl
libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl
-libhtml-formattext-withlinks-perl libgd-dev lynx-cur`
+libhtml-formattext-withlinks-perl libgd-dev lynx-cur graphviz`
+
+.. todo:: Add Sqlite debs
Gentoo
------
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 <config-database>`.
+Then, you can skip to :ref:`configuring your database
+<linux-config-database>`.
+
+.. _linux-install-perl:
Perl
====
Bugzilla requires at least Perl |min-perl-ver|.
-.. _install-bzfiles:
+.. _linux-install-bzfiles:
Bugzilla
========
.. todo:: Why is this necessary? What does the webserver write there before
checksetup.pl is run?
-.. _install-perlmodules:
+.. _linux-install-perl-modules:
Perl Modules
============
.. todo:: Give examples for Debian/Ubuntu and RedHat?
-.. _config-webserver:
+.. _linux-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:
+We have specific configuration instructions for the following:
.. toctree::
:maxdepth: 1
apache
-.. _config-database:
+.. _linux-config-database:
Database Engine
===============
oracle
sqlite
-.. _localconfig:
-
-localconfig
-===========
-
-You should now run :file:`checksetup.pl` again, this time
-without the ``--check-modules`` switch.
-
-:command:`./checksetup.pl`
-
-: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.
-The default is ``apache``, which is correct for Red Hat and Fedora. On Debian
-and Ubuntu, the correct value is ``www-data``.
-
-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. 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.
-
-.. _install-config-bugzilla:
-
-Bugzilla
-========
-
-Your Bugzilla should now be working. Check by running:
-
-:command:`testserver.pl http://<your-bugzilla-server>/`
+.. |checksetupcommand| replace:: :command:`./checksetup.pl`
+.. |testservercommand| replace:: :command:`./testserver.pl http://<your-bugzilla-server>/`
-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.
+.. include:: installing-end.inc.rst
-Next, do the :ref:`post-install-config`.
+Next, do the :ref:`essential-post-install-config`.
Mac OS X
########
-`<https://wiki.mozilla.org/Bugzilla:Mac_OS_X_installation>`_ is what we have
-right now...
+.. _macosx-install-packages:
-*Mac OS X*
-==========
+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:
-Making Bugzilla work on Mac OS X requires the following
-adjustments.
+Bugzilla
+========
-.. _macosx-sendmail:
+The best way to get Bugzilla is to check it out from git:
-Sendmail
---------
+:command:`git clone https://git.mozilla.org/bugzilla/bugzilla`
-In 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 fool Bugzilla, as long as Bugzilla can
-find it. Bugzilla is able to find the fake sendmail executable without
-any assistance.
+Run the above command in your home directory. 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:
-Libraries & Perl Modules on Mac OS X
-------------------------------------
+Additional System Libraries
+===========================
-Apple does not include the GD library with Mac OS X. Bugzilla
-needs this for bug graphs.
+Apple does not include the GD library with Mac OS X. Bugzilla needs this if
+you want to display bug graphs.
-You can use MacPorts (`<http://www.macports.org/>`_)
-or Fink (`<http://sourceforge.net/projects/fink/>`_), both
-of which are similar in nature to the CPAN installer, but install
-common unix programs.
+You can use `MacPorts <http://www.macports.org/>`_ or
+`Fink <http://sourceforge.net/projects/fink/>`_, both of which install common
+Unix programs on Mac OS X.
-Follow the instructions for setting up MacPorts or Fink.
-Once you have one installed, you'll want to use it to install the
-:file:`gd2` package.
+Follow the instructions for setting up MacPorts or Fink. Once you have one
+installed, use it to install the :file:`gd2` package.
Fink will prompt you for a number of dependencies, type 'y' and hit
enter to install all of the dependencies and then watch it work. You will
-then be able to use CPAN to
-install the GD Perl module.
+then be able to use CPAN to install the GD Perl module.
.. note:: To prevent creating conflicts with the software that Apple
installs by default, Fink creates its own directory tree at :file:`/sw`
Perl module config script asks where your :file:`libgd`
is, be sure to tell it :file:`/sw/lib`.
-Also available via MacPorts and Fink is
-:file:`expat`. After installing the expat package, you
-will be able to install XML::Parser using CPAN. If you use fink, there
-is one caveat. Unlike recent versions of
-the GD module, XML::Parser doesn't prompt for the location of the
-required libraries. When using CPAN, you will need to use the following
-command sequence:
+.. _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:
+
+.. toctree::
+ :maxdepth: 1
+
+ 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. Configure your server according to the
+instructions below.
+
+.. todo:: Has anyone tried anything other than MySQL on Mac OS X?
-::
+.. toctree::
+ :maxdepth: 1
- # perl -MCPAN -e'look XML::Parser'
- # perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include
- # make; make test; make install
- # exit
+ mysql
+ postgresql
+ oracle
+ sqlite
-The :command:`look` command will download the module and spawn
-a new shell with the extracted files as the current working directory.
+.. |checksetupcommand| replace:: :command:`perl checksetup.pl`
+.. |testservercommand| replace:: :command:`perl testserver.pl http://<your-bugzilla-server>/`
-You should watch the output from these :command:`make` commands,
-especially ``make test`` as errors may prevent
-XML::Parser from functioning correctly with Bugzilla.
+.. include:: installing-end.inc.rst
-The :command:`exit` command will return you to your original shell.
+Next, do the :ref:`essential-post-install-config`.
MySQL
#####
-Test which version of MySQL you have installed with:
+You need MySQL version 5.0.15 or higher.
+
+It's possible to test which version of MySQL you have installed with:
:command:`mysql -V`
-You need MySQL version 5.0.15 or higher.
+Installing
+==========
-If you install MySQL manually rather than from a package, make sure the
-server is started when the machine boots.
+Windows
+-------
+
+Download the MySQL 32-bit or 64-bit MSI installer from the
+`MySQL website <http://www.mysql.com/downloads/mysql/>`_ (~28 MB).
-.. _mysql-secure:
+MySQL has a standard Windows installer. It's ok to select a Typical MySQL
+install (the default). The rest of this documentation assumes assume you
+have installed MySQL into :file:`C:\\mysql`. Adjust paths appropriately if not.
-Secure MySQL
-============
+Linux/Mac OS X
+--------------
-On non-Windows platforms, run
+The package install instructions given previously should have installed MySQL
+on your machine, if it didn't come with it already. Run:
:command:`mysql_secure_installation`
and follow its advice.
+If you did install MySQL manually rather than from a package, make sure the
+server is started when the machine boots.
+
.. _mysql-add-user:
Add a User
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
-=========================================
-
-To change MySQL's configuration, you need to edit your MySQL
-configuration file, which is usually :file:`/etc/my.cnf`
-on Linux.
+-----------------------------------------
By default on some systems, MySQL will only allow you to insert things
into the database that are smaller than 1MB.
.. _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
--- /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:`dot`.
+
+Linux
+-----
+
+Put the complete path to the :file:`dot` command (from the ``graphviz``
+package) in the :param:`webdotbase` parameter. E.g. :paramval:`/usr/bin/dot`.
+
+Windows
+-------
+
+Download and install Graphviz from
+`the Graphviz website <http://www.graphviz.org/Download_windows.php>`_. Put
+the complete path to :file:`dot.exe` in the :param:`webdotbase` parameter,
+using forward slashes as path separators. E.g.
+:paramval:`C:/Program Files/ATT/Graphviz/bin/dot.exe`.
+
+.. _multiple-bz-dbs:
+
+Running Multiple Bugzillas from a Single Code Installation
+==========================================================
+
+.. todo:: This doesn't really live here. Where does it live?
+
+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 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
-.. _post-install-config:
-
-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:
-
-Essential Parameters
-====================
-
-There are a few parameters which it is very important to define (or
-explicitly decide not to change).
-
-The first set of these are in the :guilabel:`Required Settings` section.
-
-* :param:`urlbase`: this is the URL by which people should access
- Bugzilla's front page.
-* :param:`sslbase`: if you have configured SSL on your Bugzilla server,
- this is the SSL URL by which people should access Bugzilla's front page.
-* :param:`ssl_redirect`: Set this if you want everyone to be redirected
- to use the SSL version. Recommended if you have set up SSL.
-* :param:`cookiebase`: Bugzilla uses cookies to remember who each user is.
- In order to set those cookies in the correct scope, you may need to set a
- cookiebase. If your Bugzilla is at the root of your domain, you don't need
- to change the default value.
-
-You may want to put your email address in the :param:`maintainer`
-parameter in the :guilabel:`General` section. This will then let people
-know who to contact if they see problems or hit errors.
-
-If you don't want just anyone able to read your Bugzilla, set the
-:param:`requirelogin` parameter in the :guilabel:`User Authentication`
-section, and change or clear the :param:`createemailregexp` parameter.
-
-You will also need to set appropriate parameters so Bugzilla knows how to
-:ref:`send email <email>`.
-
-.. _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.
-
-.. _optional-features:
-
-Optional Features
-=================
-
-Bugzilla has a number of optional features. This section describes how
-to configure or enable them.
-
-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. Run:
-
-:command:`crontab -e`
-
-This should bring up the crontab file in your editor. Add a cron entry like
-this to run :file:`collectstats.pl` daily at 5 after midnight:
-
-.. code-block:: none
-
- 5 0 * * * cd <your-bugzilla-directory> && ./collectstats.pl
-
-After two days have passed you'll be able to view bug graphs from
-the Reports page.
-
-Windows does not have 'cron', but it does have the Task Scheduler, which
-performs the same duties. There are also third-party tools that can be used
-to implement cron, such as `nncron <http://www.nncron.ru/>`_.
-
-.. _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.
-
-This can be done by adding the following repeating command, in
-the same manner as explained above for bug graphs. This example, using cron
-syntax, runs it every 15 minutes, which is the recommended interval.
-
-.. code-block:: none
-
- */15 * * * * cd <your-bugzilla-directory> && ./whine.pl
-
-.. _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.
-
-This can be done by adding the following repeating command, in
-the same manner as explained above for bug graphs. This example, using cron
-syntax, runs it at 12.55am:
-
-.. code-block:: none
-
- 55 0 * * * cd <your-bugzilla-directory> && ./whineatnews.pl
-
-.. _multiple-bz-dbs:
-
-Running Multiple Bugzillas from a Single Code Installation
-----------------------------------------------------------
-
-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 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.
Windows
#######
-Microsoft Windows
-=================
-
-Making Bugzilla work on Windows is more difficult than making it
-work on Unix. For that reason, we still recommend doing so on a Unix
-based system such as GNU/Linux. That said, if you do want to get
-Bugzilla running on Windows, you will need to make the following
-adjustments. A detailed step-by-step
-`installation guide for Windows <https://wiki.mozilla.org/Bugzilla:Win32Install>`_ is also available
-if you need more help with your installation.
-
-:file:`checksetup.pl` will print out a list of the
-required and optional Perl modules, together with the versions
-(if any) installed on your machine.
-The list of required modules is reasonably long; however, you
-may already have several of them installed.
-
-The preferred way to install missing Perl modules is to use the package
-manager provided by your operating system (e.g ``rpm``, ``apt-get`` or
-``yum`` on Linux distros, or ``ppm`` on Windows
-if using ActivePerl, see :ref:`win32-perl-modules`).
-If some Perl modules are still missing or are too old, then we recommend
-using the :file:`install-module.pl` script (doesn't work
-with ActivePerl on Windows). For instance, on Unix,
-you invoke :file:`install-module.pl` as follows:
-Add a User to Oracle
-
-
-
-.. _win32-perl:
-
-Win32 Perl
-----------
-
-Perl for Windows can be obtained from
-`ActiveState <http://www.activestate.com/>`_.
-You should be able to find a compiled binary at `<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/>`_.
-The following instructions assume that you are using version
-|min-perl-ver| of ActiveState.
+Making Bugzilla work on Windows is more difficult than making it work on Unix,
+fewer Bugzilla developers use it and so it's less well supported. However, if
+you are still determined to do it, here's how.
+
+.. note:: ``mod_perl`` doesn't work very well on Windows, so you probably
+ don't want to use Windows for a large site.
+
+.. todo:: Is this still true?
+
+.. windows-install-perl:
+
+ActiveState Perl
+================
+
+ActiveState make a popular distribution of Perl for Windows.
+
+Download the ActiveState Perl 5.12.4 or higher MSI installer from the
+`ActiveState website <http://www.activestate.com/activeperl/downloads>`_.
+
+ActiveState Perl uses a standard Windows Installer. Install, sticking with
+the defaults, which will install Perl into :file:`C:\\Perl`. It is not
+recommended to install Perl into a directory containing a space, such as
+:file:`C:\\Program Files`.
+
+Once the install has completed, log out and log in again to pick up the
+changes to the ``PATH`` environment variable.
.. note:: These instructions are for 32-bit versions of Windows. If you are
using a 64-bit version of Windows, you will need to install 32-bit
Perl in order to install the 32-bit modules as described below.
-.. _win32-perl-modules:
+.. todo:: Is this still true?
+
+.. _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 https://git.mozilla.org/bugzilla/bugzilla C:\\bugzilla`
+
+The rest of this documentation assumes you have installed Bugzilla into
+:file:`C:\\bugzilla`. Adjust paths appropriately if not.
+
+If it's not possible to use git (e.g. because your Bugzilla machine has no
+internet access), you can
+`download a tarball of Bugzilla <http://www.bugzilla.org/download/>`_ and
+copy it across. Bugzilla comes as a 'tarball' (:file:`.tar.gz` extension),
+which any competent Windows archiving tool should be able to open.
+
+.. windows-install-perl-modules:
+
+Perl Modules
+============
+
+Bugzilla requires a number of perl modules to be installed. They are
+available in the ActiveState repository, and are installed with the
+:file:`ppm` tool. You can either use it on the command line, as below,
+or just type :command:`ppm`, and you will get a GUI.
+
+If you use a proxy server or a firewall you may have trouble running PPM.
+This is covered in the
+`ActivePerl FAQ <http://aspn.activestate.com/ASPN/docs/ActivePerl/faq/ActivePerl-faq2.html#ppm_and_proxies>`_.
-Perl Modules on Win32
----------------------
+Install the following modules with:
-Bugzilla on Windows requires the same perl modules found in
-:ref:`install-perlmodules`. The main difference is that
-windows uses PPM instead
-of CPAN. ActiveState provides a GUI to manage Perl modules. We highly
-recommend that you use it. If you prefer to use ppm from the
-command-line, type:
+:command:`ppm install <modulename>`
-::
+* AppConfig
+* TimeDate
+* DBI
+* DBD-mysql
+* Template-Toolkit
+* MailTools
+* GD
+* Chart
+* GDGraph
+* PatchReader
+* Net-LDAP-Express (required only if you want to do LDAP authentication)
- C:\perl> ppm install <module name>
+.. todo:: Is this list current and complete?
-If you are using Perl |min-perl-ver|, the best source for the Windows PPM modules
-needed for Bugzilla is probably the theory58S website, which you can add
-to your list of repositories as follows:
+.. note:: The :file:`install-module.pl` script doesn't work with ActivePerl
+ on Windows.
-::
+.. todo:: Is this still true?
- ppm repo add theory58S http://cpan.uwinnipeg.ca/PPMPackages/10xx/
+.. _windows-config-webserver:
-If you are using Perl 5.12 or newer, you no longer need to add
-this repository. All modules you need are already available from
-the ActiveState repository.
+Web Server
+==========
-.. note:: The PPM repository stores modules in 'packages' that may have
- a slightly different name than the module. If retrieving these
- modules from there, you will need to pay attention to the information
- provided when you run :command:`checksetup.pl` as it will
- tell you what package you'll need to install.
+Any web server that is capable of running CGI scripts can be made to work.
+We have specific instructions for the following:
-.. note:: If you are behind a corporate firewall, you will need to let the
- ActiveState PPM utility know how to get through it to access
- the repositories by setting the HTTP_proxy system environmental
- variable. For more information on setting that variable, see
- the ActiveState documentation.
+.. toctree::
+ :maxdepth: 1
-.. _win32-http:
+ apache-windows
+ iis
-Serving the web pages
----------------------
+.. windows-config-database:
-As is the case on Unix based systems, any web server should
-be able to handle Bugzilla; however, the Bugzilla Team still
-recommends Apache whenever asked.
+Database Engine
+===============
-.. note:: The web server looks at :file:`/usr/bin/perl` to
- call Perl. If you are using Apache on windows, you can set the
- `ScriptInterpreterSource <http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource>`_
- directive in your Apache config file to make it look at the
- right place: insert the line
+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.
- ::
- ScriptInterpreterSource Registry-Strict
+.. toctree::
+ :maxdepth: 1
- into your :file:`httpd.conf` file, and create the key
+ mysql
+ postgresql
+ oracle
+ sqlite
- ::
- HKEY_CLASSES_ROOT\\.cgi\\Shell\\ExecCGI\\Command
+.. |checksetupcommand| replace:: :command:`checksetup.pl`
+.. |testservercommand| replace:: :command:`testserver.pl http://<your-bugzilla-server>/`
- with ``C:\\Perl\\bin\\perl.exe -T`` as value (adapt to your
- path if needed) in the registry. When this is done, restart Apache.
+.. include:: installing-end.inc.rst
-.. _win32-email:
+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.
-Sending Email
--------------
+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.
-To enable Bugzilla to send email on Windows, the server running the
-Bugzilla code must be able to connect to, or act as, an SMTP server.
+Next, do the :ref:`essential-post-install-config`.
`inline markup section <http://sphinx-doc.org/latest/markup/inline.html>`_
is worth a read.
-Bugzilla's particular documentation conventions are as follows.
+Bugzilla's particular documentation conventions are as follows:
Block Directives
################
-Every heading should be preceded by an anchor, with a globally-unique name
-with no spaces. Then we demonstrate the available heading levels we haven't
-used yet:
+Chapter headings use the double-equals, page title headings the #, and then
+the three other levels are headings within a page. Every heading should be
+preceded by an anchor, with a globally-unique name with no spaces. Now, we
+demonstrate the available heading levels we haven't used yet:
.. _uniqueanchorname:
.. warning:: This is a warning of a potential serious problem you should be
aware of.
+.. todo:: This is some documentation-related task that still needs doing.
+
Use both of the above block types sparingly. Consider putting the information
in the main text, omitting it, or (if long) placing it in a subsidiary file.
projects / thirdparty / bugzilla.git / commitdiff
