Install Bugzilla on Mac Pro or MacBook Pro Running OS X 10.5 Leopard or 10.6 Snow Leopard

NOTE: I've added a troubleshooting section at the very bottom to address additional problems I encounter. If you have trouble with installation, check there for great tips.

Bugzilla on a Mac? Installing it shouldn't have been so hard. I guess it wasn't "hard," it was just really, really tedious. Almost, a "throw your laptop out the window" kind of tedious. I should know: I did it twice (installation, that is--not PC homicide). It felt like getting in line for the most crowded ride at Disney, waiting for hours to get to the front, only to arrive and realize it's NOT the front AT ALL--it's just a corner!! And once you turn it, 60 more minutes of wait time smack you in the face!

I guess that's why they invented the "FastPass." Well, lucky for us, each time I installed Bugzilla (on a MacBook Pro and a Mac Pro), I took meticulous notes, which I've summarized, below. Enjoy your FastPass to Bugzilla on a mac:

NOTE: I'd like to credit the blog I followed at Circles of Archimedes titled Installing Bugzilla on Mac OS X Server. It was, by far, the clearest, simplest, most accurate blog I could find on this topic. However, it is geared toward OS X Server and I have a Mac Pro running standard Leopard. Thereby, several steps were different. Much different.

Bugzilla on a Mac/MacBook Pro
(Leopard/Snow Leopard)

These are the exact steps I took to get it to work (twice). Basically, I had to:

• download Bugzilla
• copy it to the proper folder
• create symlinks
• configure Perl
• configure Apache
• configure MySQL
• configure Bugzilla
• troubleshoot problems

then pass out from sleep deprivation. Exact details follow.

Download & Unpack

1. Download the latest stable release of Bugzilla here http://www.bugzilla.org/download/#stable
2. Double click the archive file ("bugzilla-3.6.tar.gz" in my case) to unzip/untar it
3. Move the resulting directory ("bugzilla-3.6" in my case) to /usr/local
4. Create a symlink in /usr/local

   sudo ln -s bugzilla-3.6 bugzilla

5. Create symlink in /usr/bin pointing to /usr/local/bugzilla

   cd /usr/bin; sudo ln -s /usr/local/bugzilla bugzilla
   

6. Do the same in the Apache document root

   cd /Library/WebServer/Documents; sudo ln -s /usr/local/bugzilla bugzilla

Perl

Now it's time to get Perl situated. I'm not a perl guy, so I make no assumptions about your perl knowledge. Just do everything below and it should work.

Identify What's Missing

1. Run the Bugzilla script to check your Perl setup

cd /Library/WebServer/Documents/bugzilla; sudo ./checksetup.pl --check-modules

2. Scroll down until you get to a section that looks like this

YOU MUST RUN ONE OF THE FOLLOWING COMMANDS (depending on which database you use):

PostgreSQL: /usr/bin/perl install-module.pl DBD::Pg

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

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



COMMANDS TO INSTALL REQUIRED MODULES (You *must* run all these commands and then re-run checksetup.pl):

/usr/bin/perl install-module.pl DateTime::TimeZone

/usr/bin/perl install-module.pl Template

/usr/bin/perl install-module.pl Email::Send

/usr/bin/perl install-module.pl Email::MIME

/usr/bin/perl install-module.pl Email::MIME::Encodings

/usr/bin/perl install-module.pl Email::MIME::Modifier 

Essentially, these are all the problems (dependencies) you must fix before the bugzilla Perl code can function. I used CPAN to get that done. This is MUCH easier than typing the commands listed above because 1) CPAN exists, natively, on the Mac and 2) it takes care of all the stupid dependencies of dependencies for you! I'm not a Perl guy so maybe there are better ways to do this. All I know is, this worked (twice):

Install Missing Modules

1. Run CPAN (from an administrator account)

sudo CPAN

2. If this is your first time using CPAN on your machine, walk through all the configuration options.

The defaults work well. So most times, you can just press enter to select the default option. Toward the end, they'll ask you questions and tell you what the "Typical frequently used setting" is. Generally, I went with their suggestion. For example, when it said:

Parameters for the 'make install' command?

Typical frequently used setting:

UNINST=1         to always uninstall potentially conflicting files

Your choice:  []

I typed in "UNINST=1"

3. When you reach the end, it will prompt the following:

Please enter your CPAN site: []

After some Googling, I chose a few sites from the mirror list at mirrors.cpan.org to accomplish that I...

• chose my country and "Show Mirrors" on the side
• searched for , -5 to find all instances of my timezone
• grabbed a couple mirrors... used the HTTP sites too, for fun

This was my output in that section:

Please enter your CPAN site: [] http://cpan-du.viaverio.com/

Enter another URL or RETURN to quit: [] http://mirrors.ccs.neu.edu/CPAN/

Enter another URL or RETURN to quit: [] ftp://mirror.cogentco.com/pub/CPAN/

Enter another URL or RETURN to quit: [] ftp://perl.secsup.org/pub/perl/

Enter another URL or RETURN to quit: []

New set of picks:

http://cpan-du.viaverio.com/

http://mirrors.ccs.neu.edu/CPAN/

ftp://mirror.cogentco.com/pub/CPAN/

ftp://perl.secsup.org/pub/perl/

4. Once CPAN is ready to go, you can begin installing the Perl modules by executing the commands in the section titled, "COMMANDS TO INSTALL REQUIRED MODULES." For example, my commands were

install DateTime::TimeZone

install Template

install Email::Send

install Email::MIME

Note that the last command took care of the other Email dependencies I needed!

5. After those commands are done, choose a database (we use MySQL) and install it's module

install DBD::mysql

6. Exit CPAN and re-run the check setup script(step #7, above) to verify that you addressed all required commands
7. Rejoice, you're almost done!

Apache

This is the part I was telling you about, where it feels like you're at the end of the line . . . only to realize, you've got a ways to go. Next up, is the Apache & MySQL stuff.

One site I read somewhere mentioned that, briefly, Apache will be vulnerable while modifying some of these settings. Ideally, you should turn off your web server, first (sytem preferences -> sharing -> enable web sharing checkbox)--or better yet, disconnect from the internet entirely.

Admittedly, I did neither. I guess I'm a rebel.

1. Modify your bugzilla localconfig file *NOTE: it seems this file isn't created until checksetup.pl passes

edit:

/usr/local/bugzilla-3.6/localconfig

- set $webservergoup = '_www'

- set $db_pass = 'yourPassword'

Obviously, replace 'yourPassword' with a valid password for the 'bugs' user.
2. Change the owner on all your bugzilla files and symlinks

sudo chown -R _www:_www /Library/WebServer/Documents/bugzilla

sudo chown -R _www:_www /usr/local/bugzilla-3.6

sudo chown -R _www:_www /usr/local/bugzilla

3. Edit your Apache config file

edit:

/private/etc/apache2/httpd.conf

add the following after the closing tag for <Directory "/Library/WebServer/Documents"> (after <Directory>):

#

# Bugzilla

#

<Directory "Library/WebServer/Documents/bugzilla">

AddHandler cgi-script .cgi

Options +Indexes +ExecCGI +FollowSymLinks

DirectoryIndex index.cgi

AllowOverride Limit

</Directory>

4. Note that the +FollowSymLinks option needs to be set for this to work.
5. Also, I had to do something funky to get CGI pages to stop loading as text. I don't have that documented but I believe it's just the +ExecCGI Option, above. I may have needed to load this module in the "LoadModule" section near the top:
LoadModule cgi_module libexec/apache2/mod_cgi.so

MySQL

Now comes the fun with MySQL. Basically, all you need to do is create the bugs database, create the bugs user (with the proper password). Of course, I assume you already have MySQL (if not, follow this post to install MySQL on Mac OS X). Then do the following to configure the bugzilla database:

1. Run the following SQL (or copy it to a file named bugzilla.sql and run: mysql -u root -p < bugzilla.sql)

use mysql;
create database if not exists bugs;

CREATE USER 'bugs'@'localhost' identified by 'yourPassword';

CREATE USER 'bugs'@'127.0.0.1' identified by 'yourPassword';

CREATE USER 'bugs'@'%' identified by 'yourPassword';



GRANT ALL PRIVILEGES ON bugs.* TO 'bugs'@'localhost' WITH GRANT OPTION;

GRANT ALL PRIVILEGES ON bugs.* TO 'bugs'@'127.0.0.1' WITH GRANT OPTION;

GRANT SELECT, INSERT, UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* TO 'bugs'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Obviously, replace 'yourPassword' with a valid password for the 'bugs' user on the database. Also, granting ALL privileges is, of course, probably NOT the best thing to do . . . feel free to restrict the privilages on localhost if you like. I just wanted to be sure it would work. Plus, our DB is only connected to our intranet. Likewise, you don't need to grant privileges to all domains (i.e. the line containing 'bugs'@'%' could be omitted).

Home Stretch

Now that all this is set, and your bugs database has GRANT privileges, run the checksetup.pl script (as administrator) :

sudo /usr/local/bugzilla/checksetup.pl

Once Perl is completely setup, this script sets up your Database tables & data and applies a few other settings. There will be several prompts to respond to but all the answers are straight-forward. Be sure to TAKE NOTE OF WHAT YOU SET YOUR EMAIL/PASS TO! (I forgot mine and it was a hassle)

Bugzilla Settings

By now, all the difficult things are done. The only thing left is to run Bugzilla. So, fire up Apache (sytem preferences -> sharing -> enable web sharing checkbox) and visit the bugzilla directory on your server (for me it's, http://our.server.address/bugzilla) and celebrate!

From there, login at the top and begin setting the required paramaters (namely, urlbase). Here's a quick list of some of the things I typically change on every installation:

• Required Settings > urlbase > http://our.server.address/bugzilla
• Bug Fields > usebugaliases > On
• Bug Fields > defaultpriority > Normal
• Bug Fields > defaultseverity > Normal
• Bug Fields > defaultplatform > Macintosh
• Bug Fields > defaultopsys > Mac OS
• User Matching > confirmuniqueusermatch > Off

---

Troubleshooting

Ok. So we upgraded our server to Snow Leopard and, somehow, that impacted the Perl environment thereby messing up Bugzilla. In the process of fixing this issue, I hit SO MANY roadblocks that it prompted me to add this Troubleshooting section--just for my own sanity.

Below, I will organize the bugzilla problems I encountered into Problem/Symptom/Solution sections and link each topic below:

Topics:

• General Perl Troubles
• Installation of Email::MIME module failed
• Installing DateTime fails with an error mentioning "Singleton"
• General errors that mention "DateTime" or "Locale"
• install DBD::mysql fails
• How To Re-Run CPAN setup
• can't login to bugzilla / Forgotten admin password / reset or add an admin

Problem

Installation of Email::MIME module failed

Symptom

received the following error:

make test had returned bad status, won't install without force

Solution

The suggestion at the bottom of this forum post recommended running
force install Email::MIME
which, in fact, did forcefully install the module. Whether that's good or bad, I can't say. I did continue looking for the root problem (which was, basically, to find and install all missing modules).

---

Problem

Problem description: Perl. That's it, just Perl. Perl + Bugzilla = headache

Jokes aside, every issue I've had installing Bugzilla always boils down to deducing the missing Perl module and installing it. Installation is easy. It's the "figuring out which module" part that will get you, every time!

Symptom

received errors during Perl configuration such as:

#   Failed test 'use Email::Send;'
#   at t/foreign-mailer.t line 7.
#     Tried to use 'Email::Send'.
#    Error:  Can't locate Email/Simple.pm in @INC ... 

or
BEGIN failed--compilation aborted at ...
or
DIED. FAILED tests
or

#     Error:  Attempt to reload Email/MIME.pm aborted.
#     Error:  Base class package "Email::Simple::Creator" is
empty.

Solution

The best process I've found for solving most bugzilla installation errors is:

1. Open a fresh terminal window
2. Attempt to install every module required in the "checksetup.pl" script. (run the commands in step 4, above.)
Execute every installation command once, ignoring any errors
3. Copy all output into a file
I used CPAN, which has it's own shell and thereby wouldn't let me pipe output into a file. So I just chose "Select All > Copy" in that fresh terminal window (in step 1) and pasted it into a temporary file
4. Grep the file to sift out text related to missing modules
They often generate errors along the lines of

Error:  Can't locate Email/Simple.pm in @INC (@INC contains ...

So I used some variation of the following:
cat tempFile.txt | grep @INC | awk -F"@" '{ print $1 }' which takes the file, pulls out every line with "@INC" in it, then lazily uses awk to split each line around the "@" symbol and print the first segment. This produced crude information on missing modules such as:

t/19local-win32......Can't locate Params/Validate.pm in 
t/20local-subclass......Can't locate Params/Validate.pm in 
t/abstract-msg.......Can't locate Email/Simple.pm in 
#     Error:  Can't locate Email/Simple.pm in 
t/classic............Can't locate Email/Simple.pm in 
t/email-send-test....Can't locate Email/Simple.pm in 

5. Identify statements in a form similar to:

   Params/Validate.pm
   Email/Simple.pm
   Email/Date/Format.pm

6. Install the corresponding modules:

   sudo CPAN
   install Params::Validate
   install Email::Simple
   install Email::Date::Format

7. Rerun the installation commands
8. Run the checksetup.pl script again to verify that the required modules no longer appear in the list
9. Celebrate!

Typically, this process fixes the problem. I go over the initial output (the temp file created in step 3) with a fine-toothed comb and install everything that seems to be missing. The list above contains everything I installed this time, except YAML (for that just run: install YAML).

---

Problem

General errors that mention "DateTime" or "Locale"

Symptom

errors such as:

Attempt to reload DateTime.pm aborted

BEGIN failed--compilation aborted at /usr/local/share/perl/
5.10.0/DateTime/Locale/Base.pm line 8.
Compilation failed in require at /usr/local/share/perl/5.10.0/
DateTime/Locale.pm line 10.
BEGIN failed--compilation aborted at /usr/local/share/perl/
5.10.0/DateTime/Locale.pm line 10.
Compilation failed in require at lib/i486-linux-gnu-thread-
multi/DateTime.pm line 46.
BEGIN failed--compilation aborted at lib/i486-linux-gnu-thread
-multi/DateTime.pm line 46.

Solution

Many users on this forum found it helpful to run

install DateTime::Locale

---

Problem

install DBD::mysql fails

Symptom

running the command generates the following error:

Running install for module 'DBD::mysql'
Running make for C/CA/CAPTTOFU/DBD-mysql-4.014.tar.gz
  Has already been unwrapped into directory /Users/svn/.cpan/
  build/DBD-mysql-4.014-jZi5O8
  '/usr/bin/perl Makefile.PL' returned status 512, won't make
Running make test
  Make had some problems, won't test
Running make install
  Make had some problems, won't install

Solution

Verify that the command "mysql" works from the terminal. If not, install mysql. Verify that you can connect to mysql as user "root." If not, grant permissions to your root account.

---

Problem

You need to re-run the initial CPAN setup wizard, for whatever reason (maybe to reset your URL mirror sites)

Symptom

None the URLs you have seem to work, or maybe there's one that needs deleting (in my setup the first one would fail and take like 3 minutes to timeout).

Perhaps, you don't trust your CPAN installation settings and you want to rule that out during troubleshooting (I wanted to rule this out)

Solution

Re-run the initial CPAN setup with the folowing command (note: the first character is an 'o' -- not a bullet):

o conf init

To choose new URLs (or edit existing ones) run:

o conf init urllist

Be sure to commit your configuration after making changes. I believe the command is:

o conf commit

---

Problem

Need to reset bugzilla admin password

Symptom

The admin password is lost or forgotten

The admin login credentials are lost or fogotten

Another admin account needs to be added (but you can't login)

Solution

This forum post provides lots of help on recovering a forgotten admin password or account.

There are several ways to address this issue

• run checksetup.pl with the --make-admin option:
./checksetup.pl --make-admin=yourEmail@domain.com
• copy the profiles.cryptpassword for a known user account to the administrator account, OR add your account to the admin group:

SELECT @myusr := userid FROM profiles WHERE login_name="PUT YOUR EMAIL HERE"; 
SELECT @admin := id FROM groups WHERE name="admin"; 
INSERT INTO user_group_map (user_id,group_id,isbless,grant_type) VALUES 
(@myusr,@admin,0,0);

• Throw your computer out the window
That fixes everything.

---

Problem

Installing DateTime fails with an error mentioning "Singleton"

Symptom

Errors such as:

• t/37local-add.t ......... Can't locate Class/Singleton.pm in @INC (@INC contains: /Users/svn/.cpan/build/DateTime-0.55-ilncRa/blib/lib /Users/svn/.cpan/build/DateTime-0.55-ilncRa/blib/arch /Library/Perl/Updates/5.10.0/darwin-thread-multi-2level /Library/Perl/Updates/5.10.0 /System/Library/Perl/5.10.0/darwin-thread-multi-2level /System/Library/Perl/5.10.0 /Library/Perl/5.10.0/darwin-thread-multi-2level /Library/Perl/5.10.0 /Network/Library/Perl/5.10.0/darwin-thread-multi-2level /Network/Library/Perl/5.10.0 /Network/Library/Perl /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level /System/Library/Perl/Extras/5.10.0 .) at /Library/Perl/5.10.0/DateTime/TimeZone/America/Chicago.pm line 14.
• BEGIN failed--compilation aborted at /Library/Perl/5.10.0/DateTime/TimeZone/America/Chicago.pm line 14.
• t/38local-subtract.t .... Can't locate Class/Singleton.pm in @INC (@INC contains: /Users/svn/.cpan/build/DateTime-0.55-ilncRa/blib/lib /Users/svn/.cpan/build/DateTime-0.55-ilncRa/blib/arch /Library/Perl/Updates/5.10.0/darwin-thread-multi-2level /Library/Perl/Updates/5.10.0 /System/Library/Perl/5.10.0/darwin-thread-multi-2level /System/Library/Perl/5.10.0 /Library/Perl/5.10.0/darwin-thread-multi-2level /Library/Perl/5.10.0 /Network/Library/Perl/5.10.0/darwin-thread-multi-2level /Network/Library/Perl/5.10.0 /Network/Library/Perl /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level /System/Library/Perl/Extras/5.10.0 .) at /Library/Perl/5.10.0/DateTime/TimeZone/America/Chicago.pm line 14.
• BEGIN failed--compilation aborted at /Library/Perl/5.10.0/DateTime/TimeZone/America/Chicago.pm line 14.
• Compilation failed in require at (eval 906) line 3.
• t/41cldr_format.t ....... Can't locate Class/Singleton.pm in @INC (@INC contains: /Users/svn/.cpan/build/DateTime-0.55-ilncRa/blib/lib /Users/svn/.cpan/build/DateTime-0.55-ilncRa/blib/arch /Library/Perl/Updates/5.10.0/darwin-thread-multi-2level /Library/Perl/Updates/5.10.0 /System/Library/Perl/5.10.0/darwin-thread-multi-2level /System/Library/Perl/5.10.0 /Library/Perl/5.10.0/darwin-thread-multi-2level /Library/Perl/5.10.0 /Network/Library/Perl/5.10.0/darwin-thread-multi-2level /Network/Library/Perl/5.10.0 /Network/Library/Perl /System/Library/Perl/Extras/5.10.0/darwin-thread-multi-2level /System/Library/Perl/Extras/5.10.0 .) at /Library/Perl/5.10.0/DateTime/TimeZone/America/Chicago.pm line 14.
• Result: FAIL
• Failed 11/43 test programs. 3/2864 subtests failed.

Solution

The Singleton module is missing. For me, this also meant that the DateTime::TimeZone module hadn't been installed (because it depends on Singleton). To solve this, either

• execute install DateTime::TimeZone
and choose [yes] when prompted about the Unsatisfied dependency on Singleton. This will automatically install the missing Singleton module.

OR


• execute install Class::Singleton

Whichever solution you use, make sure to run install DateTime and install DateTime::TimeZone to ensure that both of these modules are now installed properly.