4.1. Step-by-step Install

4.1.1. MySQL

Visit the MySQL homepage at http://www.mysql.com to grab and install the latest stable release of the server.

Many of the binary versions of MySQL store their data files in /var. On some Unix systems, this is part of a smaller root partition, and may not have room for your bug database. You can set the data directory as an option to configure if you build MySQL from source yourself.

If you install from something other than a packaging/installation system (such as .rpm, .dep, .exe, or .msi) you will need to configure your system so the MySQL server daemon will come back up whenever your machine reboots.

If you wish to have attachments larger than 64K, you will have to configure MySQL to accept large packets. This is done by adding the text in Figure 4-1 to your my.conf file. There is also a parameter in Bugzilla for setting the maximum allowable attachment size. You should set this value to be slightly larger than that parameter.

[mysqld]
# Allow packets up to 1M
set-variable = max_allowed_packet=1M
        

If you are running Bugzilla and MySQL on the same machine, you may also wish to utilize the skip-networking option as mentioned in Section 5.6.2 for the added security.

4.1.2. Perl

Any machine that doesn't have Perl on it is a sad machine indeed. Perl can be got in source form from http://www.perl.com. There are also binary versions available for many platforms, most of which are linked to from perl.com. Although Bugzilla runs with perl 5.6, it's a good idea to be up to the very latest version if you can when running Bugzilla. As of this writing, that is Perl version 5.8.

4.1.3. Perl Modules

Perl modules can be found using CPAN on Unix based systems or PPM on Win32. The root servers have a real tendency to bog down, so please use mirrors.

Good instuctions can be found for using each of these services on their respective websites. The basics can be found in Example 4-1 for CPAN and Section 4.3.1.2 for PPM.

Many people complain that Perl modules will not install for them. Most times, the error messages complain that they are missing a file in "@INC". 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 are the local UNIX sysadmin, please consult the newsgroup/mailing list for further assistance or hire someone to help you out.

Perl Modules (minimum version):

1. Bundle::Bugzilla (Will allow you to skip the rest)

2. AppConfig (1.52)

3. CGI (2.88)

4. Data::Dumper (any)

5. Date::Format (2.21)

6. DBI (1.32)

7. DBD::mysql (2.1010)

8. File::Spec (0.82)

9. File::Temp (any)

10. Template Toolkit (2.08)

11. Text::Wrap (2001.0131)

1. GD (1.20) for bug charting

2. Chart::Base (0.99c) for bug charting

3. XML::Parser (any) for the XML interface

4. GD::Graph (any) for bug charting

5. GD::Text::Align (any) for bug charting

6. MIME::Parser (any) for the email interface

7. PatchReader (0.9.1) for pretty HTML view of patches

bash# perl -MCPAN -eshell              
cpan shell -- CPAN exploration and modules installation (v1.63)
ReadLine support enabled

cpan>

        

4.1.3.12. GD (1.20) [optional]

The GD library was written by Thomas Boutell a long while ago to programmatically generate images in C. Since then it's become the defacto standard for programmatic image construction. The Perl bindings to it found in the GD library are used on millions of web pages to generate graphs on the fly. That's what Bugzilla will be using it for so you must install it if you want any of the graphing to work.

The Perl GD library requires some other libraries that may or may not be installed on your system, including libpng and libgd. The full requirements are listed in the Perl GD library README. If compiling GD fails, it's probably because you're missing a required library.

The version of the GD perl module you need is very closely tied to the libgd version installed on your system. If you have a version 1.x of libgd the 2.x versions of the GD perl module won't work for you.

        CPAN Download Page: http://search.cpan.org/dist/GD/
        PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GD.zip
        Documentation: http://stein.cshl.org/WWW/software/GD/
      

4.1.4. HTTP Server

You have freedom of choice here, pretty much any web server that is capable of running CGI scripts will work. Section 4.4 has more information about configuring web servers to work with Bugzilla.

We strongly recommend Apache as the web server to use. The Bugzilla Guide installation instructions, in general, assume you are using Apache. If you have got Bugzilla working using another webserver, please share your experiences with us by filing a bug in Bugzilla Documentation.

4.1.5. Bugzilla

You should untar the Bugzilla files into a directory that you're willing to make writable by the default web server user (probably "nobody"). You may decide to put the files in the main web space for your web server or perhaps in /usr/local with a symbolic link in the web space that points to the Bugzilla directory.

If you symlink the bugzilla directory into your Apache's HTML hierarchy, you may receive Forbidden errors unless you add the "FollowSymLinks" directive to the <Directory> entry for the HTML root in httpd.conf.

Once all the files are in a web accessible directory, make that directory writable by your webserver's user. This is a temporary step until you run the post-install checksetup.pl script, which locks down your installation.

The default Bugzilla distribution is not designed to be placed in a cgi-bin directory (this includes any directory which is configured using the ScriptAlias directive of Apache). This will probably change as part of bug 44659.

4.1.6. Setting Up the MySQL Database

After you've gotten all the software installed and working you're ready to start preparing the database for its life as the back end to a high quality bug tracker.

This first thing you'll want to do is make sure you've given the "root" user a password as suggested in Section 5.6.2. For clarity, these instructions will assume that your MySQL user for Bugzilla will be "bugs_user", the database will be called "bugs_db" and the password for the "bugs_user" user is "bugs_password". You should, of course, substitute the values you intend to use for your site.

Most people use "bugs" for both the user and database name.

Next, we use an SQL GRANT command to create a "bugs_user" user, and grant sufficient permissions for checksetup.pl, which we'll use later, to work its magic. This also restricts the "bugs_user" user to operations within a database called "bugs_db", and only allows the account to connect from "localhost". Modify it to reflect your setup if you will be connecting from another machine or as a different user.

mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,
       DROP,REFERENCES ON bugs_db.* TO bugs_user@localhost
       IDENTIFIED BY 'bugs_password';
mysql> FLUSH PRIVILEGES;
      

If you are using MySQL 4, the bugs user also needs to be granted the LOCK TABLES and CREATE TEMPORARY TABLES permissions.

4.1.7. checksetup.pl

Next, run the magic checksetup.pl script. (Many thanks to Holger Schurig for writing this script!) This script is designed to make sure your perl modules are the correct version and your MySQL database and other configuration options are consistent with the Bugzilla CGI files. It will make sure Bugzilla files and directories have reasonable permissions, set up the data directory, and create all the MySQL tables.

bash# ./checksetup.pl
      

The first time you run it, it will create a file called localconfig.

This file contains a variety of settings you may need to tweak including how Bugzilla should connect to the MySQL database.

The connection settings include:

1. server's host: just use "localhost" if the MySQL server is local

2. database name: "bugs_db" if you're following these directions

3. MySQL username: "bugs_user" if you're following these directions

4. Password for the "bugs_user" MySQL account; ("bugs_password" above)

Once you are happy with the settings, su to the user your web server runs as, and re-run checksetup.pl. (Note: on some security-conscious systems, you may need to change the login shell for the webserver account before you can do this.) On this second run, it will create the database and an administrator account for which you will be prompted to provide information.

The checksetup.pl script is designed so that you can run it at any time without causing harm. You should run it after any upgrade to Bugzilla.

4.1.8. Configuring Bugzilla

You should run through the parameters on the Edit Parameters page (link in the footer) and set them all to appropriate values. They key parameters are documented in Section 5.1.