| <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> |
| <!-- $Id$ --> |
| <chapter id="installing-bugzilla"> |
| <title>Installing Bugzilla</title> |
| |
| <section id="installation"> |
| <title>Installation</title> |
| |
| <note> |
| <para>If you just want to <emphasis>use</emphasis> 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. |
| </para> |
| </note> |
| |
| <para>The Bugzilla server software is usually installed on Linux or |
| Solaris. |
| If you are installing on another OS, check <xref linkend="os-specific"/> |
| before you start your installation to see if there are any special |
| instructions. |
| </para> |
| |
| <para>This guide assumes that you have administrative access to the |
| Bugzilla machine. It not possible to |
| install and run Bugzilla itself without administrative access except |
| in the very unlikely event that every single prerequisite is |
| already installed. |
| </para> |
| |
| <warning> |
| <para>The installation process may make your machine insecure for |
| short periods of time. Make sure there is a firewall between you |
| and the Internet. |
| </para> |
| </warning> |
| |
| <para> |
| You are strongly recommended to make a backup of your system |
| before installing Bugzilla (and at regular intervals thereafter :-). |
| </para> |
| |
| <para>In outline, the installation proceeds as follows: |
| </para> |
| |
| <procedure> |
| <step> |
| <para><link linkend="install-perl">Install Perl</link> |
| (&min-perl-ver; or above) |
| </para> |
| </step> |
| <step> |
| <para><link linkend="install-database">Install a Database Engine</link> |
| </para> |
| </step> |
| <step> |
| <para><link linkend="install-webserver">Install a Webserver</link> |
| </para> |
| </step> |
| <step> |
| <para><link linkend="install-bzfiles">Install Bugzilla</link> |
| </para> |
| </step> |
| <step> |
| <para><link linkend="install-perlmodules">Install Perl modules</link> |
| </para> |
| </step> |
| <step> |
| <para> |
| <link linkend="install-MTA">Install a Mail Transfer Agent</link> |
| (Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version) |
| </para> |
| </step> |
| <step> |
| <para>Configure all of the above. |
| </para> |
| </step> |
| </procedure> |
| |
| <section id="install-perl"> |
| <title>Perl</title> |
| |
| <para>Installed Version Test: <programlisting>perl -v</programlisting></para> |
| |
| <para>Any machine that doesn't have Perl on it is a sad machine indeed. |
| If you don't have it and your OS doesn't provide official packages, |
| visit <ulink url="http://www.perl.com"/>. |
| Although Bugzilla runs with Perl &min-perl-ver;, |
| it's a good idea to be using the latest stable version. |
| </para> |
| </section> |
| |
| <section id="install-database"> |
| <title>Database Engine</title> |
| |
| <para> |
| Bugzilla supports MySQL, PostgreSQL and Oracle as database servers. |
| You only require one of these systems to make use of Bugzilla. |
| </para> |
| |
| <section id="install-mysql"> |
| <title>MySQL</title> |
| <para>Installed Version Test: <programlisting>mysql -V</programlisting></para> |
| |
| <para> |
| If you don't have it and your OS doesn't provide official packages, |
| visit <ulink url="http://www.mysql.com"/>. You need MySQL version |
| &min-mysql-ver; or higher. |
| </para> |
| |
| <note> |
| <para> Many of the binary |
| versions of MySQL store their data files in |
| <filename class="directory">/var</filename>. |
| On some Unix systems, this is part of a smaller root partition, |
| and may not have room for your bug database. To change the data |
| directory, you have to build MySQL from source yourself, and |
| set it as an option to <filename>configure</filename>.</para> |
| </note> |
| |
| <para>If you install from something other than a packaging/installation |
| system, such as .rpm (Redhat Package), .deb (Debian Package), .exe |
| (Windows Executable), or .msi (Microsoft Installer), make sure the MySQL |
| server is started when the machine boots. |
| </para> |
| </section> |
| |
| <section id="install-pg"> |
| <title>PostgreSQL</title> |
| <para>Installed Version Test: <programlisting>psql -V</programlisting></para> |
| |
| <para> |
| If you don't have it and your OS doesn't provide official packages, |
| visit <ulink url="http://www.postgresql.org/"/>. You need PostgreSQL |
| version &min-pg-ver; or higher. |
| </para> |
| |
| <para>If you install from something other than a packaging/installation |
| system, such as .rpm (Redhat Package), .deb (Debian Package), .exe |
| (Windows Executable), or .msi (Microsoft Installer), make sure the |
| PostgreSQL server is started when the machine boots. |
| </para> |
| </section> |
| |
| <section id="install-oracle"> |
| <title>Oracle</title> |
| <para> |
| Installed Version Test: <programlisting>select * from v$version</programlisting> |
| (you first have to log in into your DB) |
| </para> |
| |
| <para> |
| If you don't have it and your OS doesn't provide official packages, |
| visit <ulink url="http://www.oracle.com/"/>. You need Oracle |
| version &min-oracle-ver; or higher. |
| </para> |
| |
| <para> |
| If you install from something other than a packaging/installation |
| system, such as .rpm (Redhat Package), .deb (Debian Package), .exe |
| (Windows Executable), or .msi (Microsoft Installer), make sure the |
| Oracle server is started when the machine boots. |
| </para> |
| </section> |
| </section> |
| |
| <section id="install-webserver"> |
| <title>Web Server</title> |
| |
| <para>Installed Version Test: view the default welcome page at |
| http://<your-machine>/</para> |
| |
| <para>You have freedom of choice here, pretty much any web server that |
| is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm> |
| scripts will work. |
| However, we strongly recommend using the Apache web server |
| (either 1.3.x or 2.x), and |
| the installation instructions usually assume you are |
| using it. If you have got Bugzilla working using another web server, |
| please share your experiences with us by filing a bug in &bzg-bugs;. |
| </para> |
| |
| <para> |
| If you don't have Apache and your OS doesn't provide official packages, |
| visit <ulink url="http://httpd.apache.org/"/>. |
| </para> |
| |
| </section> |
| |
| <section id="install-bzfiles"> |
| <title>Bugzilla</title> |
| |
| <para> |
| <ulink url="http://www.bugzilla.org/download/">Download a Bugzilla tarball</ulink> |
| (or check it out from CVS) and place |
| it in a suitable directory, accessible by the default web server user |
| (probably <quote>apache</quote> or <quote>www</quote>). |
| Good locations are either directly in the web server's document directories or |
| in <filename>/usr/local</filename> with a symbolic link to the web server's |
| document directories or an alias in the web server's configuration. |
| </para> |
| |
| <caution> |
| <para>The default Bugzilla distribution is NOT designed to be placed |
| in a <filename class="directory">cgi-bin</filename> directory. This |
| includes any directory which is configured using the |
| <option>ScriptAlias</option> directive of Apache. |
| </para> |
| </caution> |
| |
| <para>Once all the files are in a web accessible directory, make that |
| directory writable by your web server's user. This is a temporary step |
| until you run the |
| <filename>checksetup.pl</filename> |
| script, which locks down your installation.</para> |
| </section> |
| |
| <section id="install-perlmodules"> |
| <title>Perl Modules</title> |
| |
| <para>Bugzilla's installation process is based |
| on a script called <filename>checksetup.pl</filename>. |
| The first thing it checks is whether you have appropriate |
| versions of all the required |
| Perl modules. The aim of this section is to pass this check. |
| When it passes, proceed to <xref linkend="configuration"/>. |
| </para> |
| |
| <para> |
| At this point, you need to <filename>su</filename> to root. You should |
| remain as root until the end of the install. To check you have the |
| required modules, run: |
| </para> |
| |
| <screen><prompt>bash#</prompt> ./checksetup.pl --check-modules</screen> |
| |
| <para> |
| <filename>checksetup.pl</filename> will print out a list of the |
| required and optional Perl modules, together with the versions |
| (if any) installed on your machine. |
| The list of required modules is reasonably long; however, you |
| may already have several of them installed. |
| </para> |
| |
| <para> |
| There is a meta-module called Bundle::Bugzilla, |
| which installs all the other |
| modules with a single command. You should use this if you are running |
| Perl 5.6.1 or above. |
| </para> |
| |
| <para> |
| The preferred way of installing Perl modules is via CPAN on Unix, |
| or PPM on Windows (see <xref linkend="win32-perl-modules"/>). These |
| instructions assume you are using CPAN; if for some reason you need |
| to install the Perl modules manually, see |
| <xref linkend="install-perlmodules-manual"/>. |
| </para> |
| |
| <screen><prompt>bash#</prompt> perl -MCPAN -e 'install "<modulename>"'</screen> |
| |
| <para> |
| If you using Bundle::Bugzilla, invoke the magic CPAN command on it. |
| Otherwise, you need to work down the |
| list of modules that <filename>checksetup.pl</filename> says are |
| required, in the order given, invoking the command on each. |
| </para> |
| |
| <tip> |
| <para>Many people complain that Perl modules will not install for |
| them. Most times, the error messages complain that they are missing a |
| file in |
| <quote>@INC</quote>. |
| Virtually every time, this error is due to permissions being set too |
| restrictively for you to compile Perl modules or not having the |
| necessary Perl development libraries installed on your system. |
| Consult your local UNIX systems administrator for help solving these |
| permissions issues; if you |
| <emphasis>are</emphasis> |
| the local UNIX sysadmin, please consult the newsgroup/mailing list |
| for further assistance or hire someone to help you out.</para> |
| </tip> |
| |
| <note> |
| <para>If you are using a package-based system, and attempting to install the |
| Perl modules from CPAN, 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 <filename><packagename>-devel</filename>.</para> |
| </note> |
| |
| <para> |
| Here is a complete list of modules and their minimum versions. |
| Some modules have special installation notes, which follow. |
| </para> |
| |
| <para>Required Perl modules: |
| <orderedlist> |
| |
| <listitem> |
| <para> |
| CGI &min-cgi-ver; |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Date::Format (&min-date-format-ver;) |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| DBI (&min-dbi-ver;) |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <link linkend="install-modules-dbd-mysql">DBD::mysql</link> |
| (&min-dbd-mysql-ver;) if using MySQL |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| DBD::Pg (&min-dbd-pg-ver;) if using PostgreSQL |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| DBD::Oracle (&min-dbd-oracle-ver;) if using Oracle |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| File::Spec (&min-file-spec-ver;) |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <link linkend="install-modules-template">Template</link> |
| (&min-template-ver;) |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Email::Send (&min-email-send-ver;) |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Email::MIME::Modifier (&min-email-mime-modifier-ver;) |
| </para> |
| </listitem> |
| </orderedlist> |
| |
| Optional Perl modules: |
| <orderedlist> |
| <listitem> |
| <para> |
| <link linkend="install-modules-gd">GD</link> |
| (&min-gd-ver;) for bug charting |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Template::Plugin::GD::Image |
| (&min-gd-ver;) for Graphical Reports |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <link linkend="install-modules-chart-base">Chart::Base</link> |
| (&min-chart-base-ver;) for bug charting |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <link linkend="install-modules-gd-graph">GD::Graph</link> |
| (&min-gd-graph-ver;) for bug charting |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <link linkend="install-modules-gd-text">GD::Text</link> |
| (&min-gd-text-ver;) for bug charting |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <link linkend="install-modules-xml-twig">XML::Twig</link> |
| (&min-xml-twig-ver;) for bug import/export |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| MIME::Parser (&min-mime-parser-ver;) for bug import/export |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| LWP::UserAgent |
| (&min-lwp-useragent-ver;) for Automatic Update Notifications |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <link linkend="install-modules-patchreader">PatchReader</link> |
| (&min-patchreader-ver;) for pretty HTML view of patches |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Image::Magick (&min-image-magick-ver;) for converting BMP image attachments to PNG |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Net::LDAP |
| (&min-net-ldap-ver;) for LDAP Authentication |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Authen::Radius |
| (&min-authen-radius-ver;) for RADIUS Authentication |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <link linkend="install-modules-soap-lite">SOAP::Lite</link> |
| (&min-soap-lite-ver;) for the web service interface |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| HTML::Parser |
| (&min-html-parser-ver;) for More HTML in Product/Group Descriptions |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| HTML::Scrubber |
| (&min-html-scrubber-ver;) for More HTML in Product/Group Descriptions |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Email::MIME::Attachment::Stripper |
| (&min-email-mime-attachment-stripper-ver;) for Inbound Email |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Email::Reply |
| (&min-email-reply-ver;) for Inbound Email |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| mod_perl2 |
| (&min-mod_perl2-ver;) for mod_perl |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| CGI |
| (&min-mp-cgi-ver;) for mod_perl |
| </para> |
| </listitem> |
| |
| </orderedlist> |
| </para> |
| |
| <section id="install-modules-dbd-mysql"> |
| <title>DBD::mysql</title> |
| |
| <para>The installation process will ask you a few questions about the |
| desired compilation target and your MySQL installation. For most of the |
| questions the provided default will be adequate, but when asked if your |
| desired target is the MySQL or mSQL packages, you should |
| select the MySQL-related ones. Later you will be asked if you wish to |
| provide backwards compatibility with the older MySQL packages; you |
| should answer YES to this question. The default is NO.</para> |
| |
| <para>A host of 'localhost' should be fine. A testing user of 'test', |
| with a null password, should have sufficient access to run |
| tests on the 'test' database which MySQL creates upon installation. |
| </para> |
| </section> |
| |
| <section id="install-modules-template"> |
| <title>Template Toolkit (&min-template-ver;)</title> |
| |
| <para>When you install Template Toolkit, you'll get asked various |
| questions about features to enable. The defaults are fine, except |
| that it is recommended you use the high speed XS Stash of the Template |
| Toolkit, in order to achieve best performance. |
| </para> |
| </section> |
| |
| <section id="install-modules-gd"> |
| <title>GD (&min-gd-ver;)</title> |
| |
| <para>The GD module is only required if you want graphical reports. |
| </para> |
| |
| <note> |
| <para>The Perl GD module requires some other libraries that may or |
| may not be installed on your system, including |
| <classname>libpng</classname> |
| and |
| <classname>libgd</classname>. |
| The full requirements are listed in the Perl GD module README. |
| If compiling GD fails, it's probably because you're |
| missing a required library.</para> |
| </note> |
| |
| <tip> |
| <para>The version of the GD module you need is very closely tied |
| to the <classname>libgd</classname> version installed on your system. |
| If you have a version 1.x of <classname>libgd</classname> the 2.x |
| versions of the GD module won't work for you. |
| </para> |
| </tip> |
| </section> |
| |
| <section id="install-modules-chart-base"> |
| <title>Chart::Base (&min-chart-base-ver;)</title> |
| |
| <para>The Chart::Base module is only required if you want graphical |
| reports. |
| Note that earlier versions that 0.99c used GIFs, which are no longer |
| supported by the latest versions of GD.</para> |
| </section> |
| |
| <section id="install-modules-gd-graph"> |
| <title>GD::Graph (&min-gd-graph-ver;)</title> |
| |
| <para>The GD::Graph module is only required if you want graphical |
| reports. |
| </para> |
| </section> |
| |
| <section id="install-modules-gd-text"> |
| <title>GD::Text (&min-gd-text-ver;)</title> |
| |
| <para>The GD::Text module is only required if you want graphical |
| reports. |
| </para> |
| </section> |
| |
| <section id="install-modules-xml-twig"> |
| <title>XML::Twig (&min-xml-twig-ver;)</title> |
| |
| <para>The XML::Twig module is only required if you want to import |
| XML bugs using the <filename>importxml.pl</filename> |
| script. This is required to use Bugzilla's "move bugs" feature; |
| you may also want to use it for migrating from another bug database. |
| </para> |
| </section> |
| |
| <section id="install-modules-soap-lite"> |
| <title>SOAP::Lite (&min-soap-lite-ver;)</title> |
| <para>Installing SOAP::Lite enables your Bugzilla installation to be |
| accessible at a standardized Web Service interface (SOAP/XML-RPC) |
| by third-party applications via HTTP(S). |
| </para> |
| </section> |
| |
| <section id="install-modules-patchreader"> |
| <title>PatchReader (&min-patchreader-ver;)</title> |
| |
| <para>The PatchReader module is only required if you want to use |
| Patch Viewer, a |
| Bugzilla feature to show code patches in your web browser in a more |
| readable form. |
| </para> |
| </section> |
| </section> |
| <section id="install-MTA"> |
| <title>Mail Transfer Agent (MTA)</title> |
| |
| <para> |
| Bugzilla is dependent on the availability of an e-mail system for its |
| user authentication and for other tasks. |
| </para> |
| |
| <note> |
| <para> |
| This is not entirely true. It is possible to completely disable |
| email sending, or to have Bugzilla store email messages in a |
| file instead of sending them. However, this is mainly intended |
| for testing, as disabling or diverting email on a production |
| machine would mean that users could miss important events (such |
| as bug changes or the creation of new accounts). |
| </para> |
| |
| <para> |
| For more information, see the <quote>mail_delivery_method</quote> parameter |
| in <xref linkend="parameters" />. |
| </para> |
| </note> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| If you are using Sendmail, version 8.7 or higher is required. |
| If you are using a Sendmail-compatible MTA, it must be congruent with |
| at least version 8.7 of Sendmail. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| If a simple mail sent with the command-line 'mail' program |
| succeeds, then Bugzilla should also be fine. |
| </para> |
| |
| </section> |
| <section id="using-mod_perl-with-bugzilla"> |
| <title>Installing Bugzilla on mod_perl</title> |
| <para>It is now possible to run the Bugzilla software under <literal>mod_perl</literal> on |
| Apache. <literal>mod_perl</literal> has some additional requirements to that of running |
| Bugzilla under <literal>mod_cgi</literal> (the standard and previous way).</para> |
| |
| <para>Bugzilla requires <literal>mod_perl</literal> to be installed, which can be |
| obtained from <ulink url="http://perl.apache.org"/> - Bugzilla requires |
| version &min-mod_perl2-ver; (AKA 2.0.0-RC5) to be installed.</para> |
| |
| <para>Bugzilla also requires a more up-to-date version of the CGI |
| perl module to be installed, version &min-mp-cgi-ver; as opposed to &min-cgi-ver; |
| </para> |
| </section> |
| </section> |
| |
| <section id="configuration"> |
| <title>Configuration</title> |
| |
| <warning> |
| <para> |
| Poorly-configured MySQL and Bugzilla installations have |
| given attackers full access to systems in the past. Please take the |
| security parts of these guidelines seriously, even for Bugzilla |
| machines hidden away behind your firewall. Be certain to read |
| <xref linkend="security"/> for some important security tips. |
| </para> |
| </warning> |
| |
| <section id="localconfig"> |
| <title>localconfig</title> |
| |
| <para> |
| You should now run <filename>checksetup.pl</filename> again, this time |
| without the <literal>--check-modules</literal> switch. |
| </para> |
| <screen><prompt>bash#</prompt> ./checksetup.pl</screen> |
| <para> |
| This time, <filename>checksetup.pl</filename> should tell you that all |
| the correct modules are installed and will display a message about, and |
| write out a file called, <filename>localconfig</filename>. This file |
| contains the default settings for a number of Bugzilla parameters. |
| </para> |
| |
| <para> |
| Load this file in your editor. The only two values you |
| <emphasis>need</emphasis> to change are $db_driver and $db_pass, |
| respectively the type of the database and the password for |
| the user you will create for your database. Pick a strong |
| password (for simplicity, it should not contain single quote |
| characters) and put it here. $db_driver can be either 'mysql', |
| 'Pg' or 'oracle'. |
| </para> |
| |
| <note> |
| <para> |
| In Oracle, <literal>$db_name</literal> should actually be |
| the SID name of your database (e.g. "XE" if you are using Oracle XE). |
| </para> |
| </note> |
| |
| <para> |
| You may need to change the value of |
| <emphasis>webservergroup</emphasis> if your web server does not |
| run in the "apache" group. On Debian, for example, Apache runs in |
| the "www-data" group. If you are going to run Bugzilla on a |
| machine where you do not have root access (such as on a shared web |
| hosting account), you will need to leave |
| <emphasis>webservergroup</emphasis> empty, ignoring the warnings |
| that <filename>checksetup.pl</filename> will subsequently display |
| every time it is run. |
| </para> |
| |
| <caution> |
| <para> |
| If you are using suexec, you should use your own primary group |
| for <emphasis>webservergroup</emphasis> rather than leaving it |
| empty, and see the additional directions in the suexec section |
| <xref linkend="suexec" />. |
| </para> |
| </caution> |
| |
| <para> |
| The other options in the <filename>localconfig</filename> file |
| are documented by their accompanying comments. If you have a slightly |
| non-standard database setup, you may wish to change one or more of |
| the other "$db_*" parameters. |
| </para> |
| </section> |
| |
| <section id="database-engine"> |
| <title>Database Server</title> |
| <para> |
| This section deals with configuring your database server for use |
| with Bugzilla. Currently, MySQL (<xref linkend="mysql"/>), |
| PostgreSQL (<xref linkend="postgresql"/>) and Oracle (<xref linkend="oracle"/>) |
| are available. |
| </para> |
| |
| <section id="database-schema"> |
| <title>Bugzilla Database Schema</title> |
| |
| <para> |
| The Bugzilla database schema is available at |
| <ulink url="http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/">Ravenbrook</ulink>. |
| This very valuable tool can generate a written description of |
| the Bugzilla database schema for any version of Bugzilla. It |
| can also generate a diff between two versions to help someone |
| see what has changed. |
| </para> |
| </section> |
| |
| <section id="mysql"> |
| <title>MySQL</title> |
| |
| <caution> |
| <para> |
| MySQL's default configuration is very insecure. |
| <xref linkend="security-mysql"/> has some good information for |
| improving your installation's security. |
| </para> |
| </caution> |
| |
| <section id="mysql-max-allowed-packet"> |
| <title>Allow large attachments and many comments</title> |
| |
| <para>By default, MySQL will only allow you to insert things |
| into the database that are smaller than 64KB. 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 are very likely to |
| be larger than 64KB.</para> |
| |
| <para>To change MySQL's default, you need to edit your MySQL |
| configuration file, which is usually <filename>/etc/my.cnf</filename> |
| on Linux. We recommend that you allow at least 4MB packets by |
| adding the "max_allowed_packet" parameter to your MySQL |
| configuration in the "[mysqld]" section, like this:</para> |
| |
| <screen>[mysqld] |
| # Allow packets up to 4MB |
| max_allowed_packet=4M |
| </screen> |
| </section> |
| |
| <section> |
| <title>Allow small words in full-text indexes</title> |
| |
| <para>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".</para> |
| |
| <para>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. |
| This can be done by modifying the <filename>/etc/my.cnf</filename> |
| according to the example below:</para> |
| |
| <screen> [mysqld] |
| # Allow small words in full-text indexes |
| ft_min_word_len=2</screen> |
| |
| <para>Rebuilding the indexes can be done based on documentation found at |
| <ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>. |
| </para> |
| </section> |
| |
| <section id="install-setupdatabase-adduser"> |
| <title>Add a user to MySQL</title> |
| |
| <para> |
| You need to add a new MySQL user for Bugzilla to use. |
| (It's not safe to have Bugzilla use the MySQL root account.) |
| The following instructions assume the defaults in |
| <filename>localconfig</filename>; if you changed those, |
| you need to modify the SQL command appropriately. You will |
| need the <replaceable>$db_pass</replaceable> password you |
| set in <filename>localconfig</filename> in |
| <xref linkend="localconfig"/>. |
| </para> |
| |
| <para> |
| We use an SQL <command>GRANT</command> command to create |
| a <quote>bugs</quote> user. This also restricts the |
| <quote>bugs</quote>user to operations within a database |
| called <quote>bugs</quote>, and only allows the account |
| to connect from <quote>localhost</quote>. Modify it to |
| reflect your setup if you will be connecting from another |
| machine or as a different user. |
| </para> |
| |
| <para> |
| Run the <filename>mysql</filename> command-line client and enter: |
| </para> |
| |
| <screen> |
| <prompt>mysql></prompt> GRANT SELECT, INSERT, |
| UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, |
| CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* |
| TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>'; |
| <prompt>mysql></prompt> FLUSH PRIVILEGES; |
| </screen> |
| </section> |
| |
| <section> |
| <title>Permit attachments table to grow beyond 4GB</title> |
| |
| <para> |
| 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, follow these |
| instructions. |
| </para> |
| |
| <para> |
| After you have completed the rest of the installation (or at least the |
| database setup parts), you should run the <filename>MySQL</filename> |
| command-line client and enter the following, replacing <literal>$bugs_db</literal> |
| with your Bugzilla database name (<emphasis>bugs</emphasis> by default): |
| </para> |
| |
| <screen> |
| <prompt>mysql></prompt> use <replaceable>$bugs_db</replaceable> |
| <prompt>mysql></prompt> ALTER TABLE attachments |
| AVG_ROW_LENGTH=1000000, MAX_ROWS=20000; |
| </screen> |
| |
| <para> |
| The above command will change the limit to 20GB. Mysql will have |
| to make a temporary copy of your entire table to do this. Ideally, |
| you should do this when your attachments table is still small. |
| </para> |
| |
| <note> |
| <para> |
| This does not affect Big Files, attachments that are stored directly |
| on disk instead of in the database. |
| </para> |
| </note> |
| </section> |
| </section> |
| |
| <section id="postgresql"> |
| <title>PostgreSQL</title> |
| <section> |
| <title>Add a User to PostgreSQL</title> |
| |
| <para>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 <filename>localconfig</filename>; if you |
| changed those, you need to modify the commands appropriately. You will |
| need the <replaceable>$db_pass</replaceable> password you |
| set in <filename>localconfig</filename> in |
| <xref linkend="localconfig"/>.</para> |
| |
| <para>On most systems, to create the user in PostgreSQL, you will need to |
| login as the root user, and then</para> |
| |
| <screen> <prompt>bash#</prompt> su - postgres</screen> |
| |
| <para>As the postgres user, you then need to create a new user: </para> |
| |
| <screen> <prompt>bash$</prompt> createuser -U postgres -dAP bugs</screen> |
| |
| <para>When asked for a password, provide the password which will be set as |
| <replaceable>$db_pass</replaceable> in <filename>localconfig</filename>. |
| The created user will have the ability to create databases and will not be |
| able to create new users.</para> |
| </section> |
| |
| <section> |
| <title>Configure PostgreSQL</title> |
| |
| <para>Now, you will need to edit <filename>pg_hba.conf</filename> which is |
| usually located in <filename>/var/lib/pgsql/data/</filename>. In this file, |
| you will need to add a new line to it as follows:</para> |
| |
| <para> |
| <computeroutput>host all bugs 127.0.0.1 255.255.255.255 md5</computeroutput> |
| </para> |
| |
| <para>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.</para> |
| |
| <para>Now, you will need to restart PostgreSQL, but you will need to fully |
| stop and start the server rather than just restarting due to the possibility |
| of a change to <filename>postgresql.conf</filename>. After the server has |
| restarted, you will need to edit <filename>localconfig</filename>, finding |
| the <literal>$db_driver</literal> variable and setting it to |
| <literal>Pg</literal> and changing the password in <literal>$db_pass</literal> |
| to the one you picked previously, while setting up the account.</para> |
| </section> |
| </section> |
| |
| <section id="oracle"> |
| <title>Oracle</title> |
| <section> |
| <title>Create a New Tablespace</title> |
| |
| <para> |
| You can use the existing tablespace or create a new one for Bugzilla. |
| To create a new tablespace, run the following command: |
| </para> |
| |
| <programlisting> |
| CREATE TABLESPACE bugs |
| DATAFILE '<replaceable>$path_to_datafile</replaceable>' SIZE 500M |
| AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED |
| </programlisting> |
| |
| <para> |
| Here, the name of the tablespace is 'bugs', but you can |
| choose another name. <replaceable>$path_to_datafile</replaceable> is |
| the path to the file containing your database, for instance |
| <filename>/u01/oradata/bugzilla.dbf</filename>. |
| 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. |
| </para> |
| </section> |
| |
| <section> |
| <title>Add a User to Oracle</title> |
| |
| <para> |
| The user name and password must match what you set in |
| <filename>localconfig</filename> (<literal>$db_user</literal> |
| and <literal>$db_pass</literal>, respectively). Here, we assume that |
| the user name is 'bugs' and the tablespace name is the same |
| as above. |
| </para> |
| |
| <programlisting> |
| CREATE USER bugs |
| IDENTIFIED BY "<replaceable>$db_pass</replaceable>" |
| 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; |
| </programlisting> |
| </section> |
| |
| <section> |
| <title>Configure the Web Server</title> |
| |
| <para> |
| If you use Apache, append these lines to <filename>httpd.conf</filename> |
| to set ORACLE_HOME and LD_LIBRARY_PATH. For instance: |
| </para> |
| |
| <programlisting> |
| SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/ |
| SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/ |
| </programlisting> |
| |
| <para> |
| When this is done, restart your web server. |
| </para> |
| </section> |
| </section> |
| </section> |
| |
| <section> |
| <title>checksetup.pl</title> |
| |
| <para> |
| Next, rerun <filename>checksetup.pl</filename>. 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. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| <filename>checksetup.pl</filename> will then finish. You may rerun |
| <filename>checksetup.pl</filename> at any time if you wish. |
| </para> |
| </section> |
| |
| |
| <section id="http"> |
| <title>Web server</title> |
| <para> |
| Configure your web server according to the instructions in the |
| appropriate section. (If it makes a difference in your choice, |
| the Bugzilla Team recommends Apache.) To check whether your web server |
| is correctly configured, try to access <filename>testagent.cgi</filename> |
| from your web server. If "OK" is displayed, then your configuration |
| is successful. Regardless of which web server |
| you are using, however, ensure that sensitive information is |
| not remotely available by properly applying the access controls in |
| <xref linkend="security-webserver-access"/>. You can run |
| <filename>testserver.pl</filename> to check if your web server serves |
| Bugzilla files as expected. |
| </para> |
| |
| <section id="http-apache"> |
| <title>Bugzilla using Apache</title> |
| <para>You have two options for running Bugzilla under Apache - |
| <link linkend="http-apache-mod_cgi">mod_cgi</link> (the default) and |
| <link linkend="http-apache-mod_perl">mod_perl</link> (new in Bugzilla |
| 2.23) |
| </para> |
| <section id="http-apache-mod_cgi"> |
| <title>Apache <productname>httpd</productname> with mod_cgi</title> |
| |
| <para> |
| To configure your Apache web server to work with Bugzilla while using |
| mod_cgi, do the following: |
| </para> |
| |
| <procedure> |
| <step> |
| <para> |
| Load <filename>httpd.conf</filename> in your editor. |
| In Fedora and Red Hat Linux, this file is found in |
| <filename class="directory">/etc/httpd/conf</filename>. |
| </para> |
| </step> |
| |
| <step> |
| <para> |
| Apache uses <computeroutput><Directory></computeroutput> |
| directives to permit fine-grained permission setting. Add the |
| following lines to a directive that applies to the location |
| of your Bugzilla installation. (If such a section does not |
| exist, you'll want to add one.) In this example, Bugzilla has |
| been installed at |
| <filename class="directory">/var/www/html/bugzilla</filename>. |
| </para> |
| |
| <programlisting> |
| <Directory /var/www/html/bugzilla> |
| AddHandler cgi-script .cgi |
| Options +Indexes +ExecCGI |
| DirectoryIndex index.cgi |
| AllowOverride Limit |
| </Directory> |
| </programlisting> |
| |
| <para> |
| These instructions: allow apache to run .cgi files found |
| within the bugzilla directory; instructs the server to look |
| for a file called <filename>index.cgi</filename> if someone |
| only types the directory name into the browser; and allows |
| Bugzilla's <filename>.htaccess</filename> files to override |
| global permissions. |
| </para> |
| |
| <note> |
| <para> |
| It is possible to make these changes globally, or to the |
| directive controlling Bugzilla's parent directory (e.g. |
| <computeroutput><Directory /var/www/html/></computeroutput>). |
| Such changes would also apply to the Bugzilla directory... |
| but they would also apply to many other places where they |
| may or may not be appropriate. In most cases, including |
| this one, it is better to be as restrictive as possible |
| when granting extra access. |
| </para> |
| </note> |
| </step> |
| |
| <step> |
| <para> |
| <filename>checksetup.pl</filename> can set tighter permissions |
| on Bugzilla's files and directories if it knows what group the |
| web server runs as. Find the <computeroutput>Group</computeroutput> |
| line in <filename>httpd.conf</filename>, place the value found |
| there in the <replaceable>$webservergroup</replaceable> variable |
| in <filename>localconfig</filename>, then rerun |
| <filename>checksetup.pl</filename>. |
| </para> |
| </step> |
| |
| <step> |
| <para> |
| Optional: If Bugzilla does not actually reside in the webspace |
| directory, but instead has been symbolically linked there, you |
| will need to add the following to the |
| <computeroutput>Options</computeroutput> line of the Bugzilla |
| <computeroutput><Directory></computeroutput> directive |
| (the same one as in the step above): |
| </para> |
| |
| <programlisting> |
| +FollowSymLinks |
| </programlisting> |
| |
| <para> |
| Without this directive, Apache will not follow symbolic links |
| to places outside its own directory structure, and you will be |
| unable to run Bugzilla. |
| </para> |
| </step> |
| </procedure> |
| </section> |
| <section id="http-apache-mod_perl"> |
| <title>Apache <productname>httpd</productname> with mod_perl</title> |
| |
| <para>Some configuration is required to make Bugzilla work with Apache |
| and mod_perl</para> |
| |
| <procedure> |
| <step> |
| <para> |
| Load <filename>httpd.conf</filename> in your editor. |
| In Fedora and Red Hat Linux, this file is found in |
| <filename class="directory">/etc/httpd/conf</filename>. |
| </para> |
| </step> |
| |
| <step> |
| <para>Add the following information to your httpd.conf file, substituting |
| where appropriate with your own local paths.</para> |
| |
| <note> |
| <para>This should be used instead of the <Directory> block |
| shown above. This should also be above any other <literal>mod_perl</literal> |
| directives within the <filename>httpd.conf</filename> and must be specified |
| in the order as below.</para> |
| </note> |
| <warning> |
| <para>You should also ensure that you have disabled <literal>KeepAlive</literal> |
| support in your Apache install when utilizing Bugzilla under mod_perl</para> |
| </warning> |
| |
| <programlisting> |
| PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T |
| PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl |
| </programlisting> |
| </step> |
| |
| <step> |
| <para> |
| <filename>checksetup.pl</filename> can set tighter permissions |
| on Bugzilla's files and directories if it knows what group the |
| web server runs as. Find the <computeroutput>Group</computeroutput> |
| line in <filename>httpd.conf</filename>, place the value found |
| there in the <replaceable>$webservergroup</replaceable> variable |
| in <filename>localconfig</filename>, then rerun |
| <filename>checksetup.pl</filename>. |
| </para> |
| </step> |
| </procedure> |
| |
| <para>On restarting Apache, Bugzilla should now be running within the |
| mod_perl environment. Please ensure you have run checksetup.pl to set |
| permissions before you restart Apache.</para> |
| |
| <note> |
| <para>Please bear the following points in mind when looking at using |
| Bugzilla under mod_perl: |
| <itemizedlist> |
| <listitem> |
| <para> |
| mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be |
| looking at 30MB per httpd child, easily. Basically, you just need a lot of RAM. |
| 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. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| 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 |
| <emphasis>restart</emphasis> the server (as in make sure it stops and starts |
| again). You <emphasis>can</emphasis> change localconfig and the params file |
| manually, if you want, because those are re-read every time you load a page. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| 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 <emphasis>won't</emphasis> work.) |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </note> |
| </section> |
| </section> |
| |
| <section id="http-iis"> |
| <title>Microsoft <productname>Internet Information Services</productname></title> |
| |
| <para> |
| If you are running Bugzilla on Windows and choose to use |
| Microsoft's <productname>Internet Information Services</productname> |
| or <productname>Personal Web Server</productname> you will need |
| to perform a number of other configuration steps as explained below. |
| You may also want to refer to the following Microsoft Knowledge |
| Base articles: |
| <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225">245225</ulink> |
| <quote>HOW TO: Configure and Test a PERL Script with IIS 4.0, |
| 5.0, and 5.1</quote> (for <productname>Internet Information |
| Services</productname>) and |
| <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998">231998</ulink> |
| <quote>HOW TO: FP2000: How to Use Perl with Microsoft Personal Web |
| Server on Windows 95/98</quote> (for <productname>Personal Web |
| Server</productname>). |
| </para> |
| |
| <para> |
| You will need to create a virtual directory for the Bugzilla |
| install. Put the Bugzilla files in a directory that is named |
| something <emphasis>other</emphasis> than what you want your |
| end-users accessing. That is, if you want your users to access |
| your Bugzilla installation through |
| <quote>http://<yourdomainname>/Bugzilla</quote>, then do |
| <emphasis>not</emphasis> put your Bugzilla files in a directory |
| named <quote>Bugzilla</quote>. Instead, place them in a different |
| location, and then use the IIS Administration tool to create a |
| Virtual Directory named "Bugzilla" that acts as an alias for the |
| actual location of the files. When creating that virtual directory, |
| make sure you add the <quote>Execute (such as ISAPI applications or |
| CGI)</quote> access permission. |
| </para> |
| |
| <para> |
| You will also need to tell IIS how to handle Bugzilla's |
| .cgi files. Using the IIS Administration tool again, open up |
| the properties for the new virtual directory and select the |
| Configuration option to access the Script Mappings. Create an |
| entry mapping .cgi to: |
| </para> |
| |
| <programlisting> |
| <full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s |
| </programlisting> |
| |
| <para> |
| For example: |
| </para> |
| |
| <programlisting> |
| c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s |
| </programlisting> |
| |
| <note> |
| <para> |
| The ActiveState install may have already created an entry for |
| .pl files that is limited to <quote>GET,HEAD,POST</quote>. If |
| so, this mapping should be <emphasis>removed</emphasis> as |
| Bugzilla's .pl files are not designed to be run via a web server. |
| </para> |
| </note> |
| |
| <para> |
| IIS will also need to know that the index.cgi should be treated |
| as a default document. On the Documents tab page of the virtual |
| directory properties, you need to add index.cgi as a default |
| document type. If you wish, you may remove the other default |
| document types for this particular virtual directory, since Bugzilla |
| doesn't use any of them. |
| </para> |
| |
| <para> |
| Also, and this can't be stressed enough, make sure that files |
| such as <filename>localconfig</filename> and your |
| <filename class="directory">data</filename> directory are |
| secured as described in <xref linkend="security-webserver-access"/>. |
| </para> |
| |
| </section> |
| |
| </section> |
| |
| <section id="install-config-bugzilla"> |
| <title>Bugzilla</title> |
| |
| <para> |
| Your Bugzilla should now be working. Access |
| <filename>http://<your-bugzilla-server>/</filename> - |
| you should see the Bugzilla |
| front page. If not, consult the Troubleshooting section, |
| <xref linkend="troubleshooting"/>. |
| </para> |
| |
| <note> |
| <para> |
| The URL above may be incorrect if you installed Bugzilla into a |
| subdirectory or used a symbolic link from your web site root to |
| the Bugzilla directory. |
| </para> |
| </note> |
| |
| <para> |
| Log in with the administrator account you defined in the last |
| <filename>checksetup.pl</filename> run. You should go through |
| the parameters on the Edit Parameters page |
| (see link in the footer) and see if there are any you wish to |
| change. |
| They key parameters are documented in <xref linkend="parameters"/>; |
| you should certainly alter |
| <command>maintainer</command> and <command>urlbase</command>; |
| you may also want to alter |
| <command>cookiepath</command> or <command>requirelogin</command>. |
| </para> |
| |
| <para> |
| This would also be a good time to revisit the |
| <filename>localconfig</filename> file and make sure that the |
| names of the priorities, severities, platforms and operating systems |
| are those you wish to use when you start creating bugs. Remember |
| to rerun <filename>checksetup.pl</filename> if you change it. |
| </para> |
| |
| <para> |
| Bugzilla has several optional features which require extra |
| configuration. You can read about those in |
| <xref linkend="extraconfig"/>. |
| </para> |
| </section> |
| </section> |
| |
| <section id="extraconfig"> |
| <title>Optional Additional Configuration</title> |
| |
| <para> |
| Bugzilla has a number of optional features. This section describes how |
| to configure or enable them. |
| </para> |
| |
| <section> |
| <title>Bug Graphs</title> |
| |
| <para>If you have installed the necessary Perl modules you |
| can start collecting statistics for the nifty Bugzilla |
| graphs.</para> |
| |
| <screen><prompt>bash#</prompt> <command>crontab -e</command></screen> |
| |
| <para> |
| This should bring up the crontab file in your editor. |
| Add a cron entry like this to run |
| <filename>collectstats.pl</filename> |
| daily at 5 after midnight: |
| </para> |
| |
| <programlisting>5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl</programlisting> |
| |
| <para> |
| After two days have passed you'll be able to view bug graphs from |
| the Reports page. |
| </para> |
| |
| <note> |
| <para> |
| Windows does not have 'cron', but it does have the Task |
| Scheduler, which performs the same duties. There are also |
| third-party tools that can be used to implement cron, such as |
| <ulink url="http://www.nncron.ru/">nncron</ulink>. |
| </para> |
| </note> |
| </section> |
| |
| <section id="installation-whining-cron"> |
| <title>The Whining Cron</title> |
| |
| <para>What good are |
| bugs if they're not annoying? To help make them more so you |
| can set up Bugzilla's automatic whining system to complain at engineers |
| which leave their bugs in the NEW or REOPENED state without triaging them. |
| </para> |
| <para> |
| This can be done by adding the following command as a daily |
| crontab entry, in the same manner as explained above for bug |
| graphs. This example runs it at 12.55am. |
| </para> |
| |
| <programlisting>55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl</programlisting> |
| |
| <note> |
| <para> |
| Windows does not have 'cron', but it does have the Task |
| Scheduler, which performs the same duties. There are also |
| third-party tools that can be used to implement cron, such as |
| <ulink url="http://www.nncron.ru/">nncron</ulink>. |
| </para> |
| </note> |
| </section> |
| |
| <section id="installation-whining"> |
| <title>Whining</title> |
| |
| <para> |
| As of Bugzilla 2.20, users can configure Bugzilla to regularly 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 process of configuring Whining is described |
| in <xref linkend="whining"/>, but for it to work a Perl script must be |
| executed at regular intervals. |
| </para> |
| |
| <para> |
| This can be done by adding the following command as a daily |
| crontab entry, in the same manner as explained above for bug |
| graphs. This example runs it every 15 minutes. |
| </para> |
| |
| <programlisting>*/15 * * * * cd <your-bugzilla-directory> ; ./whine.pl</programlisting> |
| |
| <note> |
| <para> |
| Whines can be executed as often as every 15 minutes, so if you specify |
| longer intervals between executions of whine.pl, some users may not |
| be whined at as often as they would expect. Depending on the person, |
| this can either be a very Good Thing or a very Bad Thing. |
| </para> |
| </note> |
| |
| <note> |
| <para> |
| Windows does not have 'cron', but it does have the Task |
| Scheduler, which performs the same duties. There are also |
| third-party tools that can be used to implement cron, such as |
| <ulink url="http://www.nncron.ru/">nncron</ulink>. |
| </para> |
| </note> |
| </section> |
| |
| <section id="apache-addtype"> |
| <title>Serving Alternate Formats with the right MIME type</title> |
| |
| <para> |
| Some Bugzilla pages have alternate formats, other than just plain |
| <acronym>HTML</acronym>. In particular, a few Bugzilla pages can |
| output their contents as either <acronym>XUL</acronym> (a special |
| Mozilla format, that looks like a program <acronym>GUI</acronym>) |
| or <acronym>RDF</acronym> (a type of structured <acronym>XML</acronym> |
| that can be read by various programs). |
| </para> |
| <para> |
| In order for your users to see these pages correctly, Apache must |
| send them with the right <acronym>MIME</acronym> type. To do this, |
| add the following lines to your Apache configuration, either in the |
| <computeroutput><VirtualHost></computeroutput> section for your |
| Bugzilla, or in the <computeroutput><Directory></computeroutput> |
| section for your Bugzilla: |
| </para> |
| <para> |
| <screen>AddType application/vnd.mozilla.xul+xml .xul |
| AddType application/rdf+xml .rdf</screen> |
| </para> |
| </section> |
| </section> |
| |
| <section id="multiple-bz-dbs"> |
| <title>Multiple Bugzilla databases with a single installation</title> |
| |
| <para>The previous instructions referred to a standard installation, with |
| one unique Bugzilla database. However, you may want to host several |
| distinct installations, without having several copies of the code. 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 |
| <filename>localconfig.<PROJECT></filename> in the same location as |
| the default one (<filename>localconfig</filename>). It also checks for |
| customized templates in a directory named |
| <filename><PROJECT></filename> in the same location as the |
| default one (<filename>template/<langcode></filename>). By default |
| this is <filename>template/en/default</filename> so PROJECT's templates |
| would be located at <filename>template/en/PROJECT</filename>.</para> |
| |
| <para>To set up an alternate installation, just export PROJECT=foo before |
| running <command>checksetup.pl</command> for the first time. It will |
| result in a file called <filename>localconfig.foo</filename> instead of |
| <filename>localconfig</filename>. Edit this file as described above, with |
| reference to a new database, and re-run <command>checksetup.pl</command> |
| to populate it. That's all.</para> |
| |
| <para>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. |
| <programlisting> |
| <VirtualHost 212.85.153.228:80> |
| ServerName foo.bar.baz |
| SetEnv PROJECT foo |
| Alias /bugzilla /var/www/bugzilla |
| </VirtualHost> |
| </programlisting> |
| </para> |
| |
| <para>Don't forget to also export this variable before accessing Bugzilla |
| by other means, such as cron tasks for instance.</para> |
| </section> |
| |
| <section id="os-specific"> |
| <title>OS-Specific Installation Notes</title> |
| |
| <para>Many aspects of the Bugzilla installation can be affected by the |
| operating system you choose to install it on. Sometimes it can be made |
| easier and others more difficult. This section will attempt to help you |
| understand both the difficulties of running on specific operating systems |
| and the utilities available to make it easier. |
| </para> |
| |
| <para>If you have anything to add or notes for an operating system not |
| covered, please file a bug in &bzg-bugs;. |
| </para> |
| |
| <section id="os-win32"> |
| <title>Microsoft Windows</title> |
| <para> |
| Making Bugzilla work on Windows is more difficult than making it |
| work on Unix. For that reason, we still recommend doing so on a Unix |
| based system such as GNU/Linux. That said, if you do want to get |
| Bugzilla running on Windows, you will need to make the following |
| adjustments. A detailed step-by-step |
| <ulink url="https://wiki.mozilla.org/Bugzilla:Win32Install"> |
| installation guide for Windows</ulink> is also available |
| if you need more help with your installation. |
| </para> |
| |
| <section id="win32-perl"> |
| <title>Win32 Perl</title> |
| <para> |
| Perl for Windows can be obtained from |
| <ulink url="http://www.activestate.com/">ActiveState</ulink>. |
| You should be able to find a compiled binary at <ulink |
| url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/" />. |
| The following instructions assume that you are using version |
| 5.8.1 of ActiveState. |
| </para> |
| |
| <note> |
| <para> |
| These instructions are for 32-bit versions of Windows. If you are |
| using a 64-bit version of Windows, you will need to install 32-bit |
| Perl in order to install the 32-bit modules as described below. |
| </para> |
| </note> |
| |
| </section> |
| |
| <section id="win32-perl-modules"> |
| <title>Perl Modules on Win32</title> |
| |
| <para> |
| Bugzilla on Windows requires the same perl modules found in |
| <xref linkend="install-perlmodules"/>. The main difference is that |
| windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead |
| of CPAN. ActiveState provides a GUI to manage Perl modules. We highly |
| recommend that you use it. If you prefer to use ppm from the |
| command-line, type: |
| </para> |
| |
| <programlisting> |
| C:\perl> <command>ppm install <module name></command> |
| </programlisting> |
| |
| <para> |
| The best source for the Windows PPM modules needed for Bugzilla |
| is probably the theory58S website, which you can add to your list |
| of repositories as follows (for Perl 5.8.x): |
| </para> |
| |
| <programlisting> |
| <command>ppm repo add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command> |
| </programlisting> |
| |
| <para> |
| If you are using Perl 5.10.x, you cannot use the same PPM modules as Perl |
| 5.8.x as they are incompatible. In this case, you should add the following |
| repository: |
| </para> |
| <programlisting> |
| <command>ppm repo add theory58S http://cpan.uwinnipeg.ca/PPMPackages/10xx/</command> |
| </programlisting> |
| |
| <note> |
| <para> |
| In versions prior to 5.8.8 build 819 of PPM the command is |
| <programlisting> |
| <command>ppm repository add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command> |
| </programlisting> |
| </para> |
| </note> |
| <note> |
| <para> |
| The PPM repository stores modules in 'packages' that may have |
| a slightly different name than the module. If retrieving these |
| modules from there, you will need to pay attention to the information |
| provided when you run <command>checksetup.pl</command> as it will |
| tell you what package you'll need to install. |
| </para> |
| </note> |
| |
| <tip> |
| <para> |
| If you are behind a corporate firewall, you will need to let the |
| ActiveState PPM utility know how to get through it to access |
| the repositories by setting the HTTP_proxy system environmental |
| variable. For more information on setting that variable, see |
| the ActiveState documentation. |
| </para> |
| </tip> |
| </section> |
| |
| <section id="win32-code-changes"> |
| <title>Code changes required to run on Win32</title> |
| |
| <para> |
| Bugzilla on Win32 is supported out of the box from version 2.20; this |
| means that no code changes are required to get Bugzilla running. |
| </para> |
| |
| </section> |
| |
| <section id="win32-http"> |
| <title>Serving the web pages</title> |
| |
| <para> |
| As is the case on Unix based systems, any web server should |
| be able to handle Bugzilla; however, the Bugzilla Team still |
| recommends Apache whenever asked. No matter what web server |
| you choose, be sure to pay attention to the security notes |
| in <xref linkend="security-webserver-access"/>. More |
| information on configuring specific web servers can be found |
| in <xref linkend="http"/>. |
| </para> |
| |
| <note> |
| <para> |
| If using Apache on windows, you can set the <ulink |
| url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink> |
| directive in your Apache config to avoid having to modify |
| the first line of every script to contain your path to Perl |
| instead of <filename>/usr/bin/perl</filename>. When setting |
| <filename>ScriptInterpreterSource</filename>, do not forget |
| to specify the <command>-T</command> flag to enable the taint |
| mode. For example: <command>C:\Perl\bin\perl.exe -T</command>. |
| </para> |
| </note> |
| |
| </section> |
| |
| <section id="win32-email"> |
| <title>Sending Email</title> |
| |
| <para> |
| To enable Bugzilla to send email on Windows, the server running the |
| Bugzilla code must be able to connect to, or act as, an SMTP server. |
| </para> |
| |
| </section> |
| </section> |
| |
| <section id="os-macosx"> |
| <title><productname>Mac OS X</productname></title> |
| |
| <para>Making Bugzilla work on Mac OS X requires the following |
| adjustments.</para> |
| |
| <section id="macosx-sendmail"> |
| <title>Sendmail</title> |
| |
| <para>In Mac OS X 10.3 and later, |
| <ulink url="http://www.postfix.org/">Postfix</ulink> |
| is used as the built-in email server. Postfix provides an executable |
| that mimics sendmail enough to fool Bugzilla, as long as Bugzilla can |
| find it.</para> |
| |
| <para>As of version 2.20, Bugzilla will be able to find the fake |
| sendmail executable without any assistance. However, you will have |
| to turn on the sendmailnow parameter before you do anything that would |
| result in email being sent. For more information, see the description |
| of the sendmailnow parameter in <xref linkend="parameters"/>.</para> |
| |
| </section> |
| |
| <section id="macosx-libraries"> |
| <title>Libraries & Perl Modules on Mac OS X</title> |
| |
| <para>Apple does not include the GD library with Mac OS X. Bugzilla |
| needs this for bug graphs.</para> |
| |
| <para>You can use DarwinPorts (<ulink url="http://darwinports.com/"/>) |
| or Fink (<ulink url="http://sourceforge.net/projects/fink/"/>), both |
| of which are similar in nature to the CPAN installer, but install |
| common unix programs.</para> |
| |
| <para>Follow the instructions for setting up DarwinPorts or Fink. |
| Once you have one installed, you'll want to use it to install the |
| <filename>gd2</filename> package. |
| </para> |
| |
| <para>Fink will prompt you for a number of dependencies, type 'y' and hit |
| enter to install all of the dependencies and then watch it work. You will |
| then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to |
| install the GD Perl module. |
| </para> |
| |
| <note> |
| <para>To prevent creating conflicts with the software that Apple |
| installs by default, Fink creates its own directory tree at |
| <filename class="directory">/sw</filename> where it installs most of |
| the software that it installs. This means your libraries and headers |
| will be at <filename class="directory">/sw/lib</filename> and |
| <filename class="directory">/sw/include</filename> instead of |
| <filename class="directory">/usr/lib</filename> and |
| <filename class="directory">/usr/include</filename>. When the |
| Perl module config script asks where your <filename>libgd</filename> |
| is, be sure to tell it |
| <filename class="directory">/sw/lib</filename>. |
| </para> |
| </note> |
| |
| <para>Also available via DarwinPorts and Fink is |
| <filename>expat</filename>. After installing the expat package, you |
| will be able to install XML::Parser using CPAN. If you use fink, there |
| is one caveat. Unlike recent versions of |
| the GD module, XML::Parser doesn't prompt for the location of the |
| required libraries. When using CPAN, you will need to use the following |
| command sequence: |
| </para> |
| |
| <screen> |
| # perl -MCPAN -e'look XML::Parser' <co id="macosx-look"/> |
| # perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include |
| # make; make test; make install <co id="macosx-make"/> |
| # exit <co id="macosx-exit"/> |
| </screen> |
| <calloutlist> |
| <callout arearefs="macosx-look macosx-exit"> |
| <para>The look command will download the module and spawn a |
| new shell with the extracted files as the current working directory. |
| The exit command will return you to your original shell. |
| </para> |
| </callout> |
| <callout arearefs="macosx-make"> |
| <para>You should watch the output from these make commands, |
| especially <quote>make test</quote> as errors may prevent |
| XML::Parser from functioning correctly with Bugzilla. |
| </para> |
| </callout> |
| </calloutlist> |
| </section> |
| </section> |
| |
| <section id="os-linux"> |
| <title>Linux Distributions</title> |
| <para>Many Linux distributions include Bugzilla and its |
| dependencies in their native package management systems. |
| Installing Bugzilla with root access on any Linux system |
| should be as simple as finding the Bugzilla package in the |
| package management application and installing it using the |
| normal command syntax. Several distributions also perform |
| the proper web server configuration automatically on installation. |
| </para> |
| <para>Please consult the documentation of your Linux |
| distribution for instructions on how to install packages, |
| or for specific instructions on installing Bugzilla with |
| native package management tools. There is also a |
| <ulink url="http://wiki.mozilla.org/Bugzilla:Linux_Distro_Installation"> |
| Bugzilla Wiki Page</ulink> for distro-specific installation |
| notes. |
| </para> |
| </section> |
| </section> |
| |
| |
| <section id="nonroot"> |
| <title>UNIX (non-root) Installation Notes</title> |
| |
| <section> |
| <title>Introduction</title> |
| |
| <para>If you are running a *NIX OS as non-root, either due |
| to lack of access (web hosts, for example) or for security |
| reasons, this will detail how to install Bugzilla on such |
| a setup. It is recommended that you read through the |
| <xref linkend="installation" /> |
| first to get an idea on the installation steps required. |
| (These notes will reference to steps in that guide.)</para> |
| |
| </section> |
| |
| <section> |
| <title>MySQL</title> |
| |
| <para>You may have MySQL installed as root. If you're |
| setting up an account with a web host, a MySQL account |
| needs to be set up for you. From there, you can create |
| the bugs account, or use the account given to you.</para> |
| |
| <warning> |
| <para>You may have problems trying to set up |
| <command>GRANT</command> permissions to the database. |
| If you're using a web host, chances are that you have a |
| separate database which is already locked down (or one big |
| database with limited/no access to the other areas), but you |
| may want to ask your system administrator what the security |
| settings are set to, and/or run the <command>GRANT</command> |
| command for you.</para> |
| |
| <para>Also, you will probably not be able to change the MySQL |
| root user password (for obvious reasons), so skip that |
| step.</para> |
| </warning> |
| |
| <section> |
| <title>Running MySQL as Non-Root</title> |
| <section> |
| <title>The Custom Configuration Method</title> |
| <para>Create a file .my.cnf in your |
| home directory (using /home/foo in this example) |
| as follows....</para> |
| <programlisting> |
| [mysqld] |
| datadir=/home/foo/mymysql |
| socket=/home/foo/mymysql/thesock |
| port=8081 |
| |
| [mysql] |
| socket=/home/foo/mymysql/thesock |
| port=8081 |
| |
| [mysql.server] |
| user=mysql |
| basedir=/var/lib |
| |
| [safe_mysqld] |
| err-log=/home/foo/mymysql/the.log |
| pid-file=/home/foo/mymysql/the.pid |
| </programlisting> |
| </section> |
| <section> |
| <title>The Custom Built Method</title> |
| |
| <para>You can install MySQL as a not-root, if you really need to. |
| Build it with PREFIX set to <filename class="directory">/home/foo/mysql</filename>, |
| or use pre-installed executables, specifying that you want |
| to put all of the data files in <filename class="directory">/home/foo/mysql/data</filename>. |
| If there is another MySQL server running on the system that you |
| do not own, use the -P option to specify a TCP port that is not |
| in use.</para> |
| </section> |
| |
| <section> |
| <title>Starting the Server</title> |
| <para>After your mysqld program is built and any .my.cnf file is |
| in place, you must initialize the databases (ONCE).</para> |
| <screen> |
| <prompt>bash$</prompt> |
| <command>mysql_install_db</command> |
| </screen> |
| <para>Then start the daemon with</para> |
| <screen> |
| <prompt>bash$</prompt> |
| <command>safe_mysql &</command> |
| </screen> |
| <para>After you start mysqld the first time, you then connect to |
| it as "root" and <command>GRANT</command> permissions to other |
| users. (Again, the MySQL root account has nothing to do with |
| the *NIX root account.)</para> |
| |
| <note> |
| <para>You will need to start the daemons yourself. You can either |
| ask your system administrator to add them to system startup files, or |
| add a crontab entry that runs a script to check on these daemons |
| and restart them if needed.</para> |
| </note> |
| |
| <warning> |
| <para>Do NOT run daemons or other services on a server without first |
| consulting your system administrator! Daemons use up system resources |
| and running one may be in violation of your terms of service for any |
| machine on which you are a user!</para> |
| </warning> |
| </section> |
| </section> |
| |
| </section> |
| |
| <section> |
| <title>Perl</title> |
| |
| <para> |
| On the extremely rare chance that you don't have Perl on |
| the machine, you will have to build the sources |
| yourself. The following commands should get your system |
| installed with your own personal version of Perl: |
| </para> |
| |
| <screen> |
| <prompt>bash$</prompt> |
| <command>wget http://perl.com/CPAN/src/stable.tar.gz</command> |
| <prompt>bash$</prompt> |
| <command>tar zvxf stable.tar.gz</command> |
| <prompt>bash$</prompt> |
| <command>cd perl-5.8.1</command> (or whatever the version of Perl is called) |
| <prompt>bash$</prompt> |
| <command>sh Configure -de -Dprefix=/home/foo/perl</command> |
| <prompt>bash$</prompt> |
| <command>make && make test && make install</command> |
| </screen> |
| |
| <para> |
| Once you have Perl installed into a directory (probably |
| in <filename class="directory">~/perl/bin</filename>), you will need to |
| install the Perl Modules, described below. |
| </para> |
| </section> |
| |
| <section id="install-perlmodules-nonroot"> |
| <title>Perl Modules</title> |
| |
| <para> |
| Installing the Perl modules as a non-root user is accomplished by |
| running the <filename>install-module.pl</filename> |
| script. For more details on this script, see |
| <ulink url="api/install-module.html"><filename>install-module.pl</filename> |
| documentation</ulink> |
| </para> |
| </section> |
| |
| <section> |
| <title>HTTP Server</title> |
| |
| <para>Ideally, this also needs to be installed as root and |
| run under a special web server account. As long as |
| the web server will allow the running of *.cgi files outside of a |
| cgi-bin, and a way of denying web access to certain files (such as a |
| .htaccess file), you should be good in this department.</para> |
| |
| <section> |
| <title>Running Apache as Non-Root</title> |
| |
| <para>You can run Apache as a non-root user, but the port will need |
| to be set to one above 1024. If you type <command>httpd -V</command>, |
| you will get a list of the variables that your system copy of httpd |
| uses. One of those, namely HTTPD_ROOT, tells you where that |
| installation looks for its config information.</para> |
| |
| <para>From there, you can copy the config files to your own home |
| directory to start editing. When you edit those and then use the -d |
| option to override the HTTPD_ROOT compiled into the web server, you |
| get control of your own customized web server.</para> |
| |
| <note> |
| <para>You will need to start the daemons yourself. You can either |
| ask your system administrator to add them to system startup files, or |
| add a crontab entry that runs a script to check on these daemons |
| and restart them if needed.</para> |
| </note> |
| |
| <warning> |
| <para>Do NOT run daemons or other services on a server without first |
| consulting your system administrator! Daemons use up system resources |
| and running one may be in violation of your terms of service for any |
| machine on which you are a user!</para> |
| </warning> |
| </section> |
| </section> |
| |
| <section> |
| <title>Bugzilla</title> |
| |
| <para> |
| When you run <command>./checksetup.pl</command> to create |
| the <filename>localconfig</filename> file, it will list the Perl |
| modules it finds. If one is missing, go back and double-check the |
| module installation from <xref linkend="install-perlmodules-nonroot"/>, |
| then delete the <filename>localconfig</filename> file and try again. |
| </para> |
| |
| <warning> |
| <para>One option in <filename>localconfig</filename> you |
| might have problems with is the web server group. If you can't |
| successfully browse to the <filename>index.cgi</filename> (like |
| a Forbidden error), you may have to relax your permissions, |
| and blank out the web server group. Of course, this may pose |
| as a security risk. Having a properly jailed shell and/or |
| limited access to shell accounts may lessen the security risk, |
| but use at your own risk.</para> |
| </warning> |
| |
| <section id="suexec"> |
| <title>suexec or shared hosting</title> |
| |
| <para>If you are running on a system that uses suexec (most shared |
| hosting environments do this), you will need to set the |
| <emphasis>webservergroup</emphasis> value in <filename>localconfig</filename> |
| to match <emphasis>your</emphasis> primary group, rather than the one |
| the web server runs under. You will need to run the following |
| shell commands after running <command>./checksetup.pl</command>, |
| every time you run it (or modify <filename>checksetup.pl</filename> |
| to do them for you via the system() command). |
| <programlisting> for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done |
| for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done |
| find . -name .htaccess -exec chmod o+r {} \; |
| chmod o+x . data data/webdot</programlisting> |
| Pay particular attention to the number of semicolons and dots. |
| They are all important. A future version of Bugzilla will |
| hopefully be able to do this for you out of the box.</para> |
| </section> |
| </section> |
| </section> |
| |
| |
| <section id="upgrade"> |
| <title>Upgrading to New Releases</title> |
| |
| <para>Upgrading to new Bugzilla releases is very simple. There is |
| a script included with Bugzilla that will automatically |
| do all of the database migration for you.</para> |
| |
| <para>The following sections explain how to upgrade from one |
| version of Bugzilla to another. Whether you are upgrading |
| from one bug-fix version to another (such as 3.0.1 to 3.0.2) |
| or from one major version to another (such as from 3.0 to 3.2), |
| the instructions are always the same.</para> |
| |
| <note> |
| <para> |
| Any examples in the following sections are written as though the |
| user were updating to version 2.22.1, but the procedures are the |
| same no matter what version you're updating to. Also, in the |
| examples, the user's Bugzilla installation is found at |
| <filename>/var/www/html/bugzilla</filename>. If that is not the |
| same as the location of your Bugzilla installation, simply |
| substitute the proper paths where appropriate. |
| </para> |
| </note> |
| |
| <section id="upgrade-before"> |
| <title>Before You Upgrade</title> |
| |
| <para>Before you start your upgrade, there are a few important |
| steps to take:</para> |
| |
| <orderedlist> |
| <listitem> |
| <para> |
| Read the <ulink url="http://www.bugzilla.org/releases/">Release |
| Notes</ulink> of the version you're upgrading to, |
| particularly the "Notes for Upgraders" section. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| View the Sanity Check (<xref linkend="sanitycheck"/>) page |
| on your installation before upgrading. Attempt to fix all warnings |
| that the page produces before you go any further, or you may |
| experience problems during your upgrade. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Shut down your Bugzilla installation by putting some HTML or |
| text in the shutdownhtml parameter |
| (see <xref linkend="parameters"/>). |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Make a backup of the Bugzilla database. |
| <emphasis>THIS IS VERY IMPORTANT</emphasis>. If |
| anything goes wrong during the upgrade, your installation |
| can be corrupted beyond recovery. Having a backup keeps you safe. |
| </para> |
| |
| <warning> |
| <para> |
| 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 database |
| from this backup. |
| </para> |
| </warning> |
| |
| <para>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.</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term>MySQL:</term> |
| <listitem> |
| <para> |
| <command>mysqldump --opt -u bugs -p bugs > bugs.sql</command> |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>PostgreSQL:</term> |
| <listitem> |
| <para> |
| <command>pg_dump --no-privileges --no-owner -h localhost -U bugs |
| > bugs.sql</command> |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </listitem> |
| </orderedlist> |
| </section> |
| |
| <section id="upgrade-files"> |
| <title>Getting The New Bugzilla</title> |
| |
| <para>There are three ways to get the new version of Bugzilla. |
| We'll list them here briefly and then explain them |
| more later.</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term>CVS (<xref linkend="upgrade-cvs"/>)</term> |
| <listitem> |
| <para> |
| If have <command>cvs</command> installed on your machine |
| and you have Internet access, this is the easiest way to |
| upgrade, particularly if you have made modifications |
| to the code or templates of Bugzilla. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>Download the tarball (<xref linkend="upgrade-tarball"/>)</term> |
| <listitem> |
| <para> |
| This is a very simple way to upgrade, and good if you |
| haven't made many (or any) modifications to the code or |
| templates of your Bugzilla. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>Patches (<xref linkend="upgrade-patches"/>)</term> |
| <listitem> |
| <para> |
| If you have made modifications to your Bugzilla, and |
| you don't have Internet access or you don't want to use |
| cvs, then this is the best way to upgrade. |
| </para> |
| |
| <para> |
| You can only do minor upgrades (such as 3.0 to 3.0.1 or |
| 3.0.1 to 3.0.2) with patches. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <section id="upgrade-modified"> |
| <title>If you have modified your Bugzilla</title> |
| |
| <para> |
| If you have modified the code or templates of your Bugzilla, |
| then upgrading requires a bit more thought and effort. |
| A discussion of the various methods of updating compared with |
| degree and methods of local customization can be found in |
| <xref linkend="template-method"/>. |
| </para> |
| |
| <para> |
| The larger the jump you are trying to make, the more difficult it |
| is going to be to upgrade if you have made local customizations. |
| Upgrading from 3.0 to 3.0.1 should be fairly painless even if |
| you are heavily customized, but going from 2.18 to 3.0 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. |
| </para> |
| </section> |
| |
| <section id="upgrade-cvs"> |
| <title>Upgrading using CVS</title> |
| |
| <para> |
| This requires that you have cvs installed (most Unix machines do), |
| and requires that you are able to access cvs-mirror.mozilla.org |
| on port 2401, which may not be an option if you are behind a |
| highly restrictive firewall or don't have Internet access. |
| </para> |
| |
| <para> |
| The following shows the sequence of commands needed to update a |
| Bugzilla installation via CVS, and a typical series of results. |
| </para> |
| |
| <programlisting> |
| bash$ <command>cd /var/www/html/bugzilla</command> |
| bash$ <command>cvs login</command> |
| Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot |
| CVS password: <emphasis>('anonymous', or just leave it blank)</emphasis> |
| bash$ <command>cvs -q update -r BUGZILLA-2_22_1 -dP</command> |
| P checksetup.pl |
| P collectstats.pl |
| P docs/rel_notes.txt |
| P template/en/default/list/quips.html.tmpl |
| <emphasis>(etc.)</emphasis> |
| </programlisting> |
| |
| <caution> |
| <para> |
| If a line in the output from <command>cvs update</command> begins |
| with a <computeroutput>C</computeroutput>, then that represents a |
| file with local changes that CVS was unable to properly merge. You |
| need to resolve these conflicts manually before Bugzilla (or at |
| least the portion using that file) will be usable. |
| </para> |
| </caution> |
| </section> |
| |
| <section id="upgrade-tarball"> |
| <title>Upgrading using the tarball</title> |
| |
| <para> |
| If you are unable (or unwilling) to use CVS, another option that's |
| always available is to obtain the latest tarball from the <ulink |
| url="http://www.bugzilla.org/download/">Download Page</ulink> and |
| create a new Bugzilla installation from that. |
| </para> |
| |
| <para> |
| This sequence of commands shows how to get the tarball from the |
| command-line; it is also possible to download it from the site |
| directly in a web browser. If you go that route, save the file |
| to the <filename class="directory">/var/www/html</filename> |
| directory (or its equivalent, if you use something else) and |
| omit the first three lines of the example. |
| </para> |
| |
| <programlisting> |
| bash$ <command>cd /var/www/html</command> |
| bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz</command> |
| <emphasis>(Output omitted)</emphasis> |
| bash$ <command>tar xzvf bugzilla-2.22.1.tar.gz</command> |
| bugzilla-2.22.1/ |
| bugzilla-2.22.1/.cvsignore |
| <emphasis>(Output truncated)</emphasis> |
| bash$ <command>cd bugzilla-2.22.1</command> |
| bash$ <command>cp ../bugzilla/localconfig* .</command> |
| bash$ <command>cp -r ../bugzilla/data .</command> |
| bash$ <command>cd ..</command> |
| bash$ <command>mv bugzilla bugzilla.old</command> |
| bash$ <command>mv bugzilla-2.22.1 bugzilla</command> |
| </programlisting> |
| |
| <warning> |
| <para> |
| The <command>cp</command> commands both end with periods which |
| is a very important detail--it means that the destination |
| directory is the current working directory. |
| </para> |
| </warning> |
| |
| <para> |
| This upgrade method will give you a clean install of Bugzilla. |
| That's fine if you don't have any local customizations that you |
| want to maintain. If you do have customizations, then you will |
| need to reapply them by hand to the appropriate files. |
| </para> |
| </section> |
| |
| <section id="upgrade-patches"> |
| <title>Upgrading using patches</title> |
| |
| <para> |
| A patch is a collection of all the bug fixes that have been made |
| since the last bug-fix release. |
| </para> |
| |
| <para> |
| If you are doing a bug-fix upgrade—that is, one where only the |
| last number of the revision changes, such as from 2.22 to |
| 2.22.1—then you have the option of obtaining and applying a |
| patch file from the <ulink |
| url="http://www.bugzilla.org/download/">Download Page</ulink>. |
| </para> |
| |
| <para> |
| As above, this example starts with obtaining the file via the |
| command line. If you have already downloaded it, you can omit the |
| first two commands. |
| </para> |
| |
| <programlisting> |
| bash$ <command>cd /var/www/html/bugzilla</command> |
| bash$ <command>wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz</command> |
| <emphasis>(Output omitted)</emphasis> |
| bash$ <command>gunzip bugzilla-2.22-to-2.22.1.diff.gz</command> |
| bash$ <command>patch -p1 < bugzilla-2.22-to-2.22.1.diff</command> |
| patching file checksetup.pl |
| patching file collectstats.pl |
| <emphasis>(etc.)</emphasis> |
| </programlisting> |
| |
| <warning> |
| <para> |
| Be aware that upgrading from a patch file does not change the |
| entries in your <filename class="directory">CVS</filename> directory. |
| This could make it more difficult to upgrade using CVS |
| (<xref linkend="upgrade-cvs"/>) in the future. |
| </para> |
| </warning> |
| |
| </section> |
| </section> |
| |
| <section id="upgrade-completion"> |
| <title>Completing Your Upgrade</title> |
| |
| <para> |
| Now that you have the new Bugzilla code, there are a few final |
| steps to complete your upgrade. |
| </para> |
| |
| <orderedlist> |
| <listitem> |
| <para> |
| If your new Bugzilla installation is in a different |
| directory or on a different machine than your old Bugzilla |
| installation, make sure that you have copied the |
| <filename>data</filename> directory and the |
| <filename>localconfig</filename> file from your old Bugzilla |
| installation. (If you followed the tarball instructions |
| above, this has already happened.) |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| If this is a major update, check that the configuration |
| (<xref linkend="configuration"/>) for your new Bugzilla is |
| up-to-date. Sometimes the configuration requirements change |
| between major versions. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| If you didn't do it as part of the above configuration step, |
| now you need to run <command>checksetup.pl</command>, which |
| will do everything required to convert your existing database |
| and settings for the new version: |
| </para> |
| |
| <programlisting> |
| bash$ <command>cd /var/www/html/bugzilla</command> |
| bash$ <command>./checksetup.pl</command> |
| </programlisting> |
| |
| <warning> |
| <para> |
| The period at the beginning of the command |
| <command>./checksetup.pl</command> is important and can not |
| be omitted. |
| </para> |
| </warning> |
| |
| <caution> |
| <para> |
| If this is a major upgrade (say, 2.22 to 3.0 or similar), |
| running <command>checksetup.pl</command> on a large |
| installation (75,000 or more bugs) can take a long time, |
| possibly several hours. |
| </para> |
| </caution> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Clear any HTML or text that you put into the shutdownhtml |
| parameter, to re-activate Bugzilla. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| View the Sanity Check (<xref linkend="sanitycheck"/>) page in your |
| upgraded Bugzilla. |
| </para> |
| <para> |
| It is recommended that, if possible, you fix any problems |
| you see, immediately. Failure to do this may mean that Bugzilla |
| will not work correctly. Be aware that if the sanity check page |
| contains more errors after an upgrade, it doesn't necessarily |
| mean there are more errors in your database than there were |
| before, as additional tests are added to the sanity check over |
| time, and it is possible that those errors weren't being |
| checked for in the old version. |
| </para> |
| </listitem> |
| </orderedlist> |
| |
| </section> |
| |
| <section id="upgrade-notifications"> |
| <title>Automatic Notifications of New Releases</title> |
| |
| <para> |
| Bugzilla 3.0 introduced the ability to automatically notify |
| administrators when new releases are available, based on the |
| <literal>upgrade_notification</literal> parameter, see |
| <xref linkend="parameters"/>. Administrators will see these |
| notifications when they access the <filename>index.cgi</filename> |
| page, i.e. generally when logging in. Bugzilla will check once per |
| day for new releases, unless the parameter is set to |
| <quote>disabled</quote>. If you are behind a proxy, you may have to set |
| the <literal>proxy_url</literal> parameter accordingly. If the proxy |
| requires authentication, use the |
| <literal>http://user:pass@proxy_url/</literal> syntax. |
| </para> |
| </section> |
| </section> |
| |
| </chapter> |
| |
| <!-- Keep this comment at the end of the file |
| Local variables: |
| mode: sgml |
| sgml-always-quote-attributes:t |
| sgml-auto-insert-required-elements:t |
| sgml-balanced-tag-edit:t |
| sgml-exposed-tags:nil |
| sgml-general-insert-case:lower |
| sgml-indent-data:t |
| sgml-indent-step:2 |
| sgml-local-catalogs:nil |
| sgml-local-ecat-files:nil |
| sgml-minimize-attributes:nil |
| sgml-namecase-general:t |
| sgml-omittag:t |
| sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") |
| sgml-shorttag:t |
| sgml-tag-region-if-active:t |
| End: |
| --> |