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