Background

Bugzilla is a very popular open-source bug-tracking system.  It is used by many companies (large and small) to not only track defects and their remediation, but also to track various other development tasks, including new feature work, enhancement requests, etc.  It can even be used as part of a change-control process (e.g. SAS-70, SOx, etc.).

Because Bugzilla is an open-source project, it is actively enhanced and can be installed on a number of different systems.  It is easily customized in both appearance and functionality which provides it with the flexibility to fit into the existing development process of almost any team.

The project’s site (http://www.bugzilla.org) has a plethora of documentation, example usages, forums, as well as the latest releases.  The latest stable release can be found on their download page.  This post contains specific instructions for installing Bugzilla on a system running Mac OS X Server (Leopard).

Preliminary Preparations

Perl

An appropriate version of perl should already be available as part of the normal operating system installation.  Bugzilla requires a minimum of version 5.8.1 and version 5.8.8 should already be installed (as of OS X 10.5.8).  The version of perl can be verified with the following command:

/usr/bin/perl --version

MySQL

Bugzilla can utilize several different databases to store its data, but Mac OS X Server already has MySQL included in its normal installation so it makes sense to use that option.  However, the MySQL installed by default with Mac OS X Server does not include the necessary files to build a MySQL application so these must be installed manually.

To install the MySQL build files:

1. Go to the Apple open source download page and select the appropriate version of the operating system the installation is running.
2. Download the binary version of the MySQL package (for 10.5.8, the correct package is MySQL-45).
3. Decompress the packaged binary.

   tar xzf MySQL-45.binaries.tar.gz

4. Navigate to the uncompressed package directory.

   cd MySQL-45.binaries

5. Decompress the internal package into the destination directory.

   sudo tar -xzvf MySQL-45.root.tar.gz -C /

To enable the MySQL service:

1. Open the Server Admin application and connect to the server.
2. Select the server name and click on the “Settings” icon and then the “Services” tab.
3. Enable the MySQL service by clicking on the appropriate checkbox.
4. Click on the “Save” button to save the new configuration.

To start the MySQL service:

1. Open the Server Admin application and connect to the server.
2. Select the MySQL service from the list of available services.
3. Click on the “Settings” tab.
4. If necessary, set the root password for the MySQL service.  The default database location of /var/mysql may also be overridden if desired.
5. Click on the “Save” button to save the new configuration.
6. Click on the “Start MySQL” to startup the new service.

Apache

Bugzilla can utilize a wide variety of web servers, but Apache is already installed with Mac OS X Server so it makes sense to use that option.  For this installation, Bugzilla will be configured in its own subdomain (e.g. bugzilla.example.com) and not as a directory of another domain (e.g. www.example.com/bugzilla).

To setup the bugzilla domain:

1. Open the Server Admin application and connect to the server hosting DNS services.
2. Select the DNS service from the list of available services.
3. Select the “Zones” icon.
4. Select the Primary Zone for the site (e.g. example.com).
5. Click on the “Add Record” drop-down and select the “Add Alias (CNAME)” item.
6. Enter the Alias Name for the bugzilla subdomain.  The alias name should be fully qualified. This means the full domain name should be given and terminated with a period.

   bugzilla.example.com.

7. Enter the Destination for the bugzilla alias.  (i.e. the name of the server running Apache).  The domain name should be fully qualified. This means the full domain name should be given and terminated with a period.

   www.example.com.

8. Click on the “Save” button to save the new configuration.
9. Restart the DNS service to activate the new domain name.

To setup the bugzilla web site:

1. Open the Server Admin application and connect to the server hosting the web server.
2. Select the Web service from the list of available services.
3. Select the “Sites” icon.
4. Click on the “+” button to create a new site entry.
5. Click on the “General” tab and fill out the information for the new site entry:
   

   Domain Name: bugzilla.example.com
   Host Description: Bugzilla
   IP Address: any
   Port: 80
   Web Folder: /opt/local/www/bugzilla
   Default Index Files: index.cgi
   Error Document: /error.html
   Administrator Email: admin@example.com

6. Select the “Options” tab and enable the “CGI Execution” and “Allow All Overrides” options.
7. Select the “Logging” tab and setup the logging information:
   

   Enable Access Log: enabled
   Archive every: 7 days
   Location: /var/log/apache2/bugzilla_access_log
   Error Log Archive every: 7 days
   Error Log Location: /var/log/apache2/bugzilla_error_log
   Error Log Level: Warnings

8. Select the “Web Services” tab and disable any additional services selected.
9. Enable the new site by clicking the “Enabled” checkbox next to the site entry.
10. Click on the “Save” button to save the new configuration.
11. Restart the Web service to activate the new site.

Bugzilla

In this installation, Bugzilla is installed in the /opt/local/src directory so as to keep it isolated from the “stock” operating system tools and utilities.  This makes upgrading either the operating system or Bugzilla easier and less likely to result in conflicts.  In order to further simplify future upgrades, a symbolic link (/opt/local/www/bugzilla) is used as the root web folder instead of directly utilizing the actual Bugzilla source directory.

1. Download the latest Bugzilla source tarball.
2. Copy the tarball to source directory.

   sudo cp bugzilla-3.4.2.tar.gz /opt/local/src

3. Unpack the source tarball.

   cd /opt/local/src
sudo tar xzf bugzilla-3.4.2.tar.gz

4. Change the owner and group to the default web server user.

   sudo chown -R _www:_www bugzilla-3.4.2

5. Create an alias in the web folder to the active Bugzilla source.

   sudo ln -s /opt/local/src/bugzilla-3.4.2 /opt/local/www/bugzilla

Perl Modules

There are a number of perl modules (both required and optional) that Bugzilla requires for operating.  Fortunately, there are several utilities included in the Bugzilla directory that can be used to determine what needs installation as well as actually installing the necessary modules.  For these installations, it is strongly suggested that you run the commands in a root shell.

To install the perl modules:

1. Create a root shell.

   sudo bash

2. Execute the check-modules.pl script.

   /opt/local/src/bugzilla-3.4.2/checksetup.pl --check_modules

3. Install all the required perl modules identified by the check-modules.pl script.
4. Install the appropriate database binding module (DBD:mysql)

   /usr/bin/perl install-module.pl DBD::mysql

5. Install any optional modules desired.
6. Exit from the root shell.

   exit

Mail

Mac OS X Server already comes with a compatible mail transfer agent (Postfix) so no additional installation is necessary.  A working mail service is necessary for Bugzilla to issue event alerts and notifications.

Configuration

localconfig

The localconfig file is an auto-generated file that contains many of the core Bugzilla configuration variables.  Generation of the file is done by running the checksetup.pl script (with no additional parameters).  The resulting file is not immediately usable as it requires a couple quick updates to properly configure the database access.

1. Execute the checksetup.pl script to generate the localconfig file.

   cd /opt/local/src/bugzilla-3.4.2
./checksetup.pl

2. Change the $db_driver variable in the localconfig file.

   $db_driver = 'mysql'

3. Change the $db_pass variable in the localconfig file to the password for ‘bugs’ user of the database.  (The ‘bugs’ user will be created shortly.)

   $db_pass = '********'

4. Change the $webservergroup variable in the localconfig file.

   $webservergroup = '_www'

MySQL

In order to provide a better working experience with Bugzilla, it is necessary to update some of the MySQL configuration variables.  In addition, a new database user must be created.

1. Edit the /etc/my.cnf file to permit large attachments and many comments

   max_allowed_packet=4M

2. Edit the /etc/my.cnf file to allow small words in full-text indexes

   ft_min_word_len=2

3. Add the ‘bugs’ database user with associated privileges.  Be sure to specify the same password for the ‘bugs’ users as in the configuration of the localconfig file.

   mysql -u root -p
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, CREATE TEMPORARY TABLES, DROP, REFERENCES on bugs.* to bugs@localhost IDENTIFIED BY '********';
mysql> FLUSH PRIVILEGES;
mysql> commit;
mysql> exit;

4. Run the checksetup.pl script again to create the database tables, groups, users, and indexes.  Be sure to note the created administrator account and password for future reference.

Bugzilla

Bugzilla should now be accessible to a web browser at the domain specified earlier.  (http://bugzilla.example.com)  While it is usable in this state, there are some additional configuration settings that should be made with the administrator’s account.

1. Login as the administrator using the bugzilla administrator’s email address and password previously set.
2. Click on the “Administration” link.
3. Click on the “Parameters” link.
4. Set the email address of the maintainer.

   bugadmin@example.com

5. Set the URL base of the installation.

   http://bugzilla.example.com/

6. Set the cookie domain for the service.

   bugzilla.example.com

7. Click on the “Save Changes” button to save the new parameters.

Related Links

• Configuring RADIUS support for Bugzilla