The Bugzilla Guide - 2.17.5 Development Release
Prev | Chapter 4. Installation | Next

# 4.1. Step-by-step Install

Bugzilla has been successfully installed under many different operating systems including almost all Unix clones and Microsoft Windows. Many operating systems have utilities that make installation easier or quirks that make it harder. We have tried to collect that information in Section 4.4, so unless you are on Linux, be sure to check out that section before you start your installation.

| Windows is one of those operating systems that has many quirks and is not yet officially supported by the Bugzilla team. If you wish to install Bugzilla on Windows, be sure to see Section 4.4.1.

| While installing Bugzilla, it is a good idea to ensure that there is some kind of configurable firewall between you and the rest of the Internet as your machine may be insecure for periods during the install. Many installation steps require an active Internet connection to complete, but you must take care to ensure that at no point is your machine vulnerable to an attack.

This guide assumes that you already have your operating system installed, network configured, and have administrative access to the machine onto which you are installing Bugzilla. It is possible to install and run Bugzilla itself without administrative access, but you have to either make sure all the required software is installed or get somebody with administrative access to install it for you.

You are strongly recommended to make a backup of your system before installing Bugzilla (and at regular intervals thereafter :-).

Here's a basic step-by-step list:

1. Install Perl (5.6.0 or above)

2. Install MySQL (3.23.41 or above)

3. Install a Webserver

4. Put Bugzilla in the Webspace

5. Install Perl Modules

6. Setup the MySQL Database

## 4.1.1. Perl

Any machine that doesn't have Perl on it is a sad machine indeed. If your OS doesn't come with it, 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.0, 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.2.

## 4.1.2. MySQL

If your OS doesn't come with it or provide official packages, 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.

Figure 4-1. Set Max Packet Size in MySQL

    [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 4.5.2 for the added security.

### 4.1.2.1. Adding a user to MySQL

This first thing you'll want to do is make sure you've given the "root" user a password as suggested in Section 4.5.2. Then, you need to add a user for Bugzilla to use. 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. Don't use it for the password, though...

We use an SQL GRANT command to create a "bugs_user" user. 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, so add them to the list in the `GRANT` command.

## 4.1.3. HTTP Server

You have freedom of choice here, pretty much any web server that is capable of running CGI scripts will work. Section 4.2 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.4. 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 directory in httpd.conf.

| 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).

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.

## 4.1.5. `checksetup.pl`

Next, run the magic checksetup.pl script. This is designed to check whether you have all of the right Perl modules in the correct versions, and that Bugzilla is generally set up correctly.

Eventually, it will make sure Bugzilla files and directories have reasonable permissions, set up the `data` directory, and create all the MySQL tables. But the first time you run it, it's highly likely to tell you that you are missing a few Perl modules. Make a note of which ones they are, and then proceed to the next section to install them.

    bash# ./checksetup.pl

The first time you run it with all the correct modules installed, 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)

Edit the file to change these. 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.6. Perl Modules

Don't be intimidated by this long list of modules. See Section 4.1.6.1 for a way of installing all the ones you need with a single command.

Perl modules can be found using CPAN on Unix based systems or PPM on Win32.

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.4.1.2 for PPM.

Example 4-1. Installing perl modules with CPAN

The easy way:

    bash# perl -MCPAN -e 'install "<modulename>"'

Or the hard way:

    bash# tar xzvf <module>.tar.gz
    bash# cd <module>
    bash# perl Makefile.PL
    bash# make
    bash# make test
    bash# make install

  This assumes that you've already downloaded the `<module>.tar.gz` to the current working directory.
  The process of untarring the module as defined in will create the `<module>` directory.

| 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. CGI (2.88)

3. Date::Format (2.21)

4. DBI (1.32)

5. DBD::mysql (2.1010)

6. File::Spec (0.82)

7. File::Temp (any)

8. Template Toolkit (2.08)

9. Text::Wrap (2001.0131)

and, optionally:

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

### 4.1.6.1. Bundle::Bugzilla

If you are running at least perl 5.6.1, you can save yourself a lot of time by using Bundle::Bugzilla. This bundle contains every module required to get Bugzilla running. It does not include GD and friends, but these are not required for a base install and can always be added later if the need arises.

Assuming your perl was installed with CPAN (most unix installations are), using Bundle::Bugzilla is really easy. Simply follow along with the commands below.

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

    cpan>

  At this point, unless you've used CPAN on this machine before, you'll have to go through a series of configuration steps.

### 4.1.6.2. CGI (2.88)

The CGI module parses form elements and cookies and does many other usefule things. It come as a part of recent perl distributions, but Bugzilla needs a fairly new version.

CPAN Download Page: http://search.cpan.org/dist/CGI.pm/
PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/CGI.zip
Documentation: http://www.perldoc.com/perl5.8.0/lib/CGI.html

### 4.1.6.3. TimeDate modules (2.21)

Many of the more common date/time/calendar related Perl modules have been grouped into a bundle similar to the MySQL modules bundle. This bundle is stored on the CPAN under the name TimeDate. The component module we're most interested in is the Date::Format module, but installing all of them is probably a good idea anyway.

CPAN Download Page: http://search.cpan.org/dist/TimeDate/
PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/TimeDate.zip
Documentation: http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm

### 4.1.6.4. DBI (1.32)

The DBI module is a generic Perl module used the MySQL-related modules. As long as your Perl installation was done correctly the DBI module should be a breeze. It's a mixed Perl/C module, but Perl's MakeMaker system simplifies the C compilation greatly.

CPAN Download Page: http://search.cpan.org/dist/DBI/
PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBI.zip
Documentation: http://dbi.perl.org/doc/

### 4.1.6.5. MySQL-related modules

The Perl/MySQL interface requires a few mutually-dependent Perl modules. These modules are grouped together into the the Msql-Mysql-modules package.

The MakeMaker 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.

A host of 'localhost' should be fine and a testing user of 'test' with a null password should find itself with sufficient access to run tests on the 'test' database which MySQL created upon installation.

CPAN Download Page: http://search.cpan.org/dist/DBD-mysql/
PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBD-Mysql.zip
Documentation: http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pod

### 4.1.6.6. File::Spec (0.82)

File::Spec is a perl module that allows file operations, such as generating full path names, to work cross platform.

CPAN Download Page: http://search.cpan.org/dist/File-Spec/
PPM Download Page: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/File-Spec.zip
Documentation: http://www.perldoc.com/perl5.8.0/lib/File/Spec.html

### 4.1.6.7. File::Temp (any)

File::Temp is used to generate a temporary filename that is guaranteed to be unique. It comes as a standard part of perl

CPAN Download Page: http://search.cpan.org/dist/File-Spec/
PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/File-Spec.zip
Documentation: http://www.perldoc.com/perl5.8.0/lib/File/Temp.html

### 4.1.6.8. Template Toolkit (2.08)

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.

CPAN Download Page: http://search.cpan.org/dist/Template-Toolkit/
PPM Download Link: http://openinteract.sourceforge.net/ppmpackages/5.6/Template-Toolkit.tar.gz
Documentation: http://www.template-toolkit.org/docs.html

### 4.1.6.9. Text::Wrap (2001.0131)

Text::Wrap is designed to proved intelligent text wrapping.

CPAN Download Page: http://search.cpan.org/dist/Text-Tabs+Wrap/
Documentation: http://www.perldoc.com/perl5.8.0/lib/Text/Wrap.html

### 4.1.6.10. GD (1.20) [optional]

You need the GD library 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.6.11. Chart::Base (0.99c) [optional]

The Chart module provides Bugzilla with on-the-fly charting abilities. It can be installed in the usual fashion after it has been fetched from CPAN. Note that earlier versions that 0.99c used GIFs, which are no longer supported by the latest versions of GD.

CPAN Download Page: http://search.cpan.org/dist/Chart/
PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/Chart.zip

### 4.1.6.12. XML::Parser (any) [optional]

XML::Parser is used by the `importxml.pl` script. You only need it if you are going to be importing bugs (such as for bug moving). XML::Parser requires that the `expat` library is already installed on your machine.

CPAN Download Page: http://search.cpan.org/dist/XML-Parser/
Documentation: http://www.perldoc.com/perl5.6.1/lib/XML/Parser.html

### 4.1.6.13. GD::Graph (any) [optional]

In addition to GD listed above, the reporting interface of Bugzilla needs to have the GD::Graph module installed.

CPAN Download Page: http://search.cpan.org/dist/GDGraph/
PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDGraph.zip
Documentation: http://search.cpan.org/dist/GDGraph/Graph.pm

### 4.1.6.14. GD::Text::Align (any) [optional]

GD::Text::Align, as the name implies, is used to draw aligned strings of text. It is needed by the reporting interface.

CPAN Download Page: http://search.cpan.org/dist/GDTextUtil/
PPM Download Page: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDTextUtil.zip
Documentation: http://search.cpan.org/dist/GDTextUtil/Text/Align.pm

### 4.1.6.15. MIME::Parser (any) [optional]

MIME::Parser is only needed if you want to use the e-mail interface located in the `contrib` directory.

CPAN Download Page: http://search.cpan.org/dist/MIME-tools/
PPM Download Link: http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/MIME-tools.zip
Documentation: http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm

### 4.1.6.16. PatchReader (0.9.1) [optional]

PatchReader is only needed if you want to use Patch Viewer, a Bugzilla feature to format patches in a pretty HTML fashion. There are a number of optional parameters you can configure Patch Viewer with as well, including cvsroot, cvsroot_get, lxr_root, bonsai_url, lxr_url, and lxr_root. Patch Viewer also optionally will use cvs, diff and interdiff utilities if they exist on the system (interdiff can be found in the patchutils package at http://cyberelk.net/tim/patchutils/. These programs' locations can be configured in localconfig.

CPAN Download Page: http://search.cpan.org/author/JKEISER/PatchReader/
Documentation: http://www.johnkeiser.com/mozilla/Patch_Viewer.html

## 4.1.7. Configuring Bugzilla

Once checksetup.pl has run successfully, Bugzilla should start up. Proceed to the correct URL and log in with the administrator account you defined in the last checksetup.pl run.

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.

Prev | Home | Next
Installation | Up | HTTP Server Configuration