How-To: Installing BugZilla on Windows Server 2003 and IIS

Update, Oct. 13, 2010: I have just added a post on updating BugZilla to v3.6.2 from the below-mentioned version.

Recently, I found myself in need of a bug-tracking solution. Never having used one, I decided to try the open-source BugZilla to get a feel for how these kinds of programs work and what the features are.

On Windows, BugZilla gives you the choice of running in the open-source Apache webserver, or Windows’ built-in webserver, IIS. I chose to set BugZilla up to use IIS because I am already running it for web development, and I wanted to keep things relatively simple.

After a near-all-nighter, and another day of hair-pulling frustration, I got BugZilla up and working on IIS. It was not fun. It occurred to me that, considering the difficulties I had, and the fact that the information that is available is spread out over the Internet, and much of the crucial information is not out there at all, it might be a service to the community to post what I found out.

NOTE: this information was accurate when I posted it, for my system; I take no responsibility for any issues you may experience, and I can’t guarantee these steps will work for you. They worked for me, though.

Downloading the required software

BugZilla has a page that will at least get you started installing BugZilla on Windows. For simplicity’s sake, from now on I will refer to this page as “the BZ IIS page“.

Start there, and follow their directions to download BugZilla itself: version 3.0.3 is the latest stable release at the time of this writing. They start with instructions for downloading BugZilla from CVS; I recommend that you don’t do this. Instead, scroll down to the instructions under the heading “Installing BugZilla From the TarBall“, and follow them. The instructions boil down to extracting the files into a directory; WinZip will handle the extraction (there is a free evaluation version available at that link) if you don’t already have a utility that handles TarBalls. The directions suggest that you create, and extract the files into, C:\Bugzilla; I second the recommendation. It makes it a lot easier to follow the directions if you do this. Note that, by default, when the TarBall is extracted, it will create a sub-directory under C:\Bugzilla with the version number. I strongly recommend that you move all the files and sub-directories under this sub-directory—on my system it was C:\Bugzilla\bugzilla-3.0.3—directly under the C:\Bugzilla directory. Again, it will make the later steps easier to follow.

Once that’s done, the BZ IIS page then directs you to download and install ActiveState Perl.
WARNING!! There is a HUGE “Gotcha” here! The directions state “Download the ActiveState Perl 5.8.1 or Higher. . .”. What they don’t tell you is that the latest version of ActiveState Perl available at the time of this writing — 5.10.x —  is NOT COMPATIBLE with BugZilla! To be specific, most of the Perl add-on modules required by BugZilla are not available for ActiveState Perl 5.10.x!! Don’t download v5.10.x!! Instead, download the previous version, 5.8.x. If you download the wrong version, you will not be able to install the required modules to get BugZilla working. You will simply be told that the modules you need were not found.

Go ahead and follow the instructions to install Perl, and to create the C:\Temp directory and set the permissions. To simplify things, I gave System, NETWORK_SERVICE, and IUSR_<machinename> write permission to this directory. Be sure to Log out, and Log back in, after installing Perl, because the PATH Environmental Variable was set by the Perl installation, and you need to Log out & back in to get the change picked up by Windows. We’ll need the variable set for the next step.

Install the Perl modules

Continuing with the directions from the BZ IIS page, we next need to install the modules. You can do this from the command line by opening a Command Prompt and typing, IIRC, “ppm.bat” (without the quotes). I used the module-installing GUI, which you open simply by typing “ppm”(without the quotes) at a command prompt. HOWEVER- there is another “Gotcha” here. Before attempting to install the modules, you need to add the BugZilla module repository to your installation! If you fail to do this, once again, Perl will be unable to find the modules you need. If you are using the GUI, add http://landfill.bugzilla.org/ppm as a Repository, with the name “Bugzilla”. If you use the command line, type: repo add Bugzilla http://landfill.bugzilla.org/ppm. Note: you may come across instructions indicating that you need to follow this by repeatedly typing a command that includes “rep up[…]”. THIS IS NOT NECESSARY in this version of Perl and will result in an error.
Follow the rest of the instructions for installing the modules.

Configure IIS

You do not need to download Apache, because we are using IIS instead. At this point, follow the provided link for instructions on configuring IIS for BugZilla: do everything listed in 2.2.4.2, and note that there is no space between the “-x” and the path to BugZilla in the script mappings. Do all the optional steps except the Microsoft Knowledge Base steps. At that point, stop and go no further. DO NOT go on to 2.2.5 and try to start BugZilla; it won’t work yet.

Instead, you need to do a few other things: open up the IIS manager: type this into START->RUN:
%SystemRoot%\system32\inetsrviis.msc –this will open the IIS Manager. In the left pane, click the + sign to expand your server, then click “Web Service Extensions”. If you don’t see the “Allow”, “Prohibit” and “Properties” buttons, click the “Extended” tab at the bottom.
You will need to Allow “All unknown CGI Extensions”, in spite of the warning it gives you;  BugZilla just won’t run without this setting.

Next, make sure all of the following are listed, and are Allowed: Perl CGI Extension, Perl ISAPI Extension, Perl Scripts, PerlEx ISAPI Extension.
If you need to Add any of them, click on the hyperlink “Add a new Web service extension…” on the left of the pane. The “Extension Name” is simply the name as noted above: “Perl CGI Extension”, or “Perl ISAPI Extension”, or…etc. You then select, or browse to, the
proper .EXE or .DLL file. For “Perl CGI Extension” you need to add some parameters; you’ll enter C:\Perl\bin\perl.exe “%s” %s . For
“Perl ISAPI Extension” you’ll enter or browse to C:\Perl\bin\perlis.dll; and for “Perl scripts”, it’s simply C:\Perl\bin\perl.exe.
Finally, for PerlEx ISAPI Extension, it’s c:\Perl\bin\PerlEx30.dll. NOTE: all of the above assumes you have installed Perl to the default of C:\Perl.
If not, you’ll need to adjust the paths. Also, the name of the PerlEx30.dll may be different if you have a later version of Perl than mine.

Configure BugZilla

Go back to the BZ IIS page and pick up after all the steps for configuring Apache. You should be at the heading “Configure BugZilla”. Note that the command you need to run starts with “perl“: you should type perl checksetup.pl after changing to the Bugzilla directory (which should be “C:\Bugzilla”, or ”
C:\Bugzilla\bugzilla-3.0.3″, if you followed recommendations). If you are told that you need to install more modules, go ahead and follow the instructions, remembering that you can scroll the command-line window up to see the text that has scrolled off the screen.

Once checksetup.pl has run without telling you there are required modules missing, you should see the text that tells you that localconfig was created. Localconfig does not exist until it is created by checksetup.pl; and checksetup.pl won’t create the file until checksetup.pl runs without finding any missing modules.
Localconfig is a text file in the Bugzilla directory that contains various settings; the one we’re concerned with right now is the password for the MySQL database. Follow the instructions to enter the password in the localconfig file. WARNING! VERY IMPORTANT: if you use Notepad as your editor, when you Save the file, change the file type from “Text documents(.TXT)” to “All files(*.*)” and make sure the Encoding is “ANSI”. This tripped me up for hours and caused a CGI error in the web browser! If you use another editor, be careful when saving! Once you’ve edited and saved the localconfig file, run perl checksetup.pl from a command prompt again.

At this point, you will likely get an error stating you could not connect to the MySQL database. For some reason, this seems to occur even if you have correctly entered the password in localconfig. To fix this, you need to reset the password. Open a command prompt window and log in to the MySQL database as root; there is a picture of the required commands at the top of the BZ IIS page; of course you will need to enter the password you used when first setting up MySQL, rather than the one shown in the picture. Once you are logged into MySQL, enter the following command, replacing ‘sockmonkey’ with the password you set when you set up the bugs account in MySQL: set password for ‘bugs’@’localhost’ = OLD_PASSWORD(‘sockmonkey’); [enter the single quotes, exactly as shown].

Now, run checksetup.pl again from a command prompt using the same command: perl checksetup.pl

This time, it should create the tables for you, exactly as shown in the first set of instructions. Once that finishes, it’s worth checking your server configuration: open a command prompt window and enter: perl testserver.pl http://localhost/Bugzilla — assuming your IIS virtual directory was named “Bugzilla”. If not, change the command accordingly. The test should run successfully; at this point, you can go back to the BZ IIS page and take care of entering the parameters and setting up the scheduled tasks. In order to enter the parameters, you will need to run BugZilla in a browser. Open up your web browser, on the same computer on which you installed BugZilla. Assuming your IIS virtual Directory was “Bugzilla”, you would type the following into your browser:
http://localhost/Bugzilla.
“Gotcha” – if you get a “HTTP 400 – Bad Request” error message at this point, you probably have not set up your loopback adapter. Go to this page at the Microsoft Knowledge Base: http://support.microsoft.com/kb/842693 and follow the instructions under the following section:

Windows Small Business Server, Premium Edition

To resolve this problem, set the loopback IP address for the default Web site in IIS[…]

Once you’ve done that, the error will go way. Finish up the instructions on the BZ IIS page, then come back here for the final step.

Final step- Run BugZilla – Error??

You should now be able to connect to BugZilla.

But — you may see an Error, right at the top of the page! If you do, and it starts with “Use of uninitialized value in substitution (s///) at (eval[…]“, it is caused by a bug in the 3.12 version of Perl’s CGI.PM module. It’s fixed in the 3.33 version, which is at
http://search.cpan.org/src/LDS/CGI.pm-3.33/; you can try downloading the entire directory structure and following the directions
in the README file, but what worked for me was to copy the CGI.pm file over the previous version in my C:Perllib directory.
Simply download the file to the C:Perllib directory and say “Yes” when Windows asks if you want to overwrite the existing file.

That’s all, folks!

Yes, I really did go through all the steps and errors noted above, and found the workarounds mentioned. My apologies if I failed to credit the first person to locate a given fix, but frankly, I didn’t keep track of it as I went, as I was trying everything I could think of and seeing what worked.

It’s sad, but this is typical of the installation process for an open-source application. In fact, this was easier than some, as many require you to download the source code and compile it yourself! And some even require you to use a source-control app like CVS to get the source code! I’m a developer, with 15+ years of experience as a Computer Consultant on top of it, and look at the trouble *I* had! I can’t even imagine what misery the typical end-user would have gone through trying to install an app like this…you could respond that this is an app aimed at developers, but the fact is, I’ve seen this over and over in hundreds of open-source apps, intended for end-users as well as developers.

In my search for help on this installation, I saw a lot of glib responses along the lines of “that’s why you shouldn’t use IIS!  Use Apache[an open-source web server] on Linux!” This is a poor attitude. We’re told that the app runs on IIS; if so, it should just RUN– or tell us it doesn’t! This kind of sarcastic, Linux/Open-source-fanboy response doesn’t help. And it ignores the fact that many users either have their web server choice dictated by management, or just simply don’t have the time or desire to get yet another PC, running yet another web server, running. Open-source apps like this are just not going to get wide acceptance until they do something about their installations. This situation is something like the experience installing apps 15 years ago on DOS/Windows 3.1- miserable. I recall all sorts of issues with missing runtimes, “DLL Hell”, etc. But Microsoft did fix it, for the most part. There is a long-time standard for installing apps under 32-bit Windows, which almost every closed-source app uses – Windows Installer [most developers use third-party, or Visual Studio’s built-in, tools that create Windows Installer .MSI files, rather than using Windows Installer directly]. In fact, ActiveState Perl itself uses Windows Installer , and it makes installing their product much easier. There are free and open-source install makers, many of which can create .MSI files, as well. Most of these tools are capable of creating installers that install all required libraries and other apps, using Merge Modules or similar functionality.

There just is no excuse for this kind of amateur-hour installation process; it doesn’t serve these apps well (no pun intended). I’s a shame that these apps don’t have modern installers, because they have a lot to offer; but most users are just not going to suffer through these kinds of drawn-out, poorly documented installations. Just look at the amount of information I had to compile here!

OK, I’ll get off my soapbox now. I’m still looking forward to trying BugZilla out. Perhaps I’ll post my impressions later…

Troubleshooting

I’m sorry to say I don’t have the time to help much if you post questions. All I can say is, if you follow the instructions above, in the exact order I posted them, you shouldn’t have trouble. Especially pay attention to setting permissions on the various directories; make sure whichever user your IIS is running under has access to all the Perl folders. I also need to note that later versions may have fixed some of the above issues…or created others. I can only say that what I wrote above is an accurate representation of what I went through.