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:
then pass out from sleep deprivation. Exact details follow.
Download & Unpack
- Download the latest stable release of Bugzilla here
http://www.bugzilla.org/download/#stable
- Double click the archive file ("bugzilla-3.6.tar.gz" in my case) to unzip/untar it
- Move the resulting directory ("bugzilla-3.6" in my case) to /usr/local
- Create a symlink in /usr/local
sudo ln -s bugzilla-3.6 bugzilla
- Create symlink in /usr/bin pointing to /usr/local/bugzilla
cd /usr/bin; sudo ln -s /usr/local/bugzilla bugzilla
- Do the same in the Apache document root
cd /Library/WebServer/Documents; sudo ln -s /usr/local/bugzilla bugzilla
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
- Run the Bugzilla script to check your Perl setup
cd /Library/WebServer/Documents/bugzilla; sudo ./checksetup.pl --check-modules
- 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
- Run CPAN (from an administrator account)
sudo CPAN
- 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"
- 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/
- 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!
- After those commands are done, choose a database (we use MySQL) and install it's module
install DBD::mysql
- Exit CPAN and re-run the check setup script(step #7, above) to verify that you addressed all required commands
- Rejoice, you're almost done!
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.
- 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.
- 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
- 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>
- Note that the +FollowSymLinks option needs to be set for this to work.
- 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
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:
- 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:
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::MIMEwhich, 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:
- Open a fresh terminal window
- 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
- 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
- Grep the file to sift out text related to missing modules
They often generate errors along the lines ofError: 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
- Identify statements in a form similar to:
Params/Validate.pm
Email/Simple.pm
Email/Date/Format.pm
- Install the corresponding modules:
sudo CPAN
install Params::Validate
install Email::Simple
install Email::Date::Format
- Rerun the installation commands
- Run the checksetup.pl script again to verify that the required modules no longer appear in the list
- 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.
