This is a follow-up post to Installing BugZilla on Windows Server 2003 and IIS, which I posted back in April of 2008.
Upgrading BugZilla on Windows: gotchas
Recently, having gotten sick of seeing the blurb about new versions of BugZilla every time I logged in, having gotten bored with the somewhat plain-vanilla look, and having heard something about new features, I decided to see about upgrading to the latest-and-greatest version of BugZilla—3.6.2 as of this writing.
36 hours of frustration [largely self-induced] later, I am here to save you the time I wasted!
This is vital. Do not skip this step.
I am assuming you used mySQL here, because that’s the usual approach. Do not simply copy the “data” directory under the mySQL directory, or the ‘bugs’ directory. If you do this you will be unable to get mySQL to properly recognize the database when you copy it back—or at least, I wasn’t able to. Instead, do a “proper” backup using the mysqldump command.
Next, “stop” BugZilla
You “stop” BugZilla by going into the Administration section, clicking the “Parameters” link, on later versions clicking the “General” link, then placing any text or HTML into the shutdownhtml parameter. I usually use something like “<h1>BugZilla is down for maintenance. Please try back later.</h1> “, but it really doesn’t matter.
Important: don’t close the browser window you did this in! If you do, you’ll be locked out of BugZilla. You can usually get back in by adding “editparams.cgi” to the end of your base BugZilla URL in your browser, after the slash; for example,
However, at some point in the process of upgrading, I lost the connection. Trying editparams put me in an endless loop of being asked to log in, logging in, then being dumped back to the main screen, which happily told me BugZilla was down. I finally discovered that you can directly edit the parameters: there is a textfile named “params” that lives under the “data” subdirectory of the BugZilla directory. Just remove the text in the shutdownhtml parameter.
Warning: if you do this, use WordPad instead of Notepad to edit the file, as it understands UNIX-style line endings without extra steps. Make sure you remove any file extensions if WordPad adds them, but it shouldn’t.
The various, and “recommended”, methods of upgrading on Windows
I spent quite a bit of time trying the different methods of upgrading BugZilla. There is the “download the tar-ball” method; the “apply the diff patches” method”; the “update from the CVS repository” method; and, unbeknownst to me until after I had completed the upgrade, there is even—finally!—an .MSI-based installer. Yes, that’s right, a standard-on-Windows-for-years-now-but-never-supported-by-BugZilla-until-now Windows installer! Yay, right? Well, maybe. It is still “unofficial”, and there are some caveats that would have made it unsuited to my situation. I will discuss these later.
I had issues with all of the first three methods mentioned above. First, I tried to download and un-tar the tar-ball. Okay, now what? There are no directions for how to proceed when you have an existing installation you want to replace. Simply un-tarring the tar-ball into the existing directory, which made sense to me as a way of maintaining the old settings, did nothing to get the new version up and running. Next, I looked at using the patch method, but quickly decided it was way too much work. Finally, in desperation, I tried the “recommended” update-from-CVS approach. It took quite a long time, during which several error messages scrolled past the screen—so many that the buffer in my command window quickly overflowed, leaving me unable to read them, as the hundreds of lines of new text quickly replaced the older ones.
In retrospect, I should have used output redirection from the command line to save the text into a file for later viewing. For example:
Obviously, you would replace [cvsUpdateCommand] with the actual CVS update command.
In any event, after watching the text scroll by for 10 minutes or so, this also failed to give me a working BugZilla installation. Whether it would have been different if I’d been able to read—and fix—the warnings/errors, I don’t know; but there is a much easier way.
My recommended method—that works!
It’s easy enough. Download the tar-ball, and expand it—into a new directory alongside the old one. Do not expand it into the existing one! Then, simply go into the IIS manager, right-click the BugZilla website and choose “Properties”, and point the website to the new directory instead of the old one.
Very Important: you’ll need to set the ACLs on the new directory to match the old ones. This one threw me for longer than I want to admit; I plead exhaustion and frustration! Open Windows Explorer/My Computer, right-click the directory, choose “Properties”, click on the “Security” tab, and set up the access rights to match the old folder.
Next, you will need to do the usual BugZilla setup stuff: edit the localconfig file in the new directory to enter your database name, username, and password, etc.; restart IIS to get BugZilla to re-read the config file, then open a command prompt, cd to the BugZilla directory, and run perl checksetup.pl. For details, see my earlier post, Installing BugZilla on Windows Server 2003 and IIS.
At this point, you may find that you need to update your installation of Perl. I decided to do it when I got a large number of errors from BugZilla. As before, I used ActiveState’s ActivePerl. I had some trouble upgrading it; perhaps I wouldn’t have if I had found, and followed, the upgrade instructions from ActiveState. Make sure you Stop IIS—which I did not do, to my regret– before you uninstall the old version and install the new one. I had some odd error messages that cropped up afterward, complaining that perl58.dll couldn’t be found. After searching the Registry and Environment Variables fruitlessly for a value I could fix, I finally changed the Windows File Association for .pl files to point to the new Perl installation, which seems to have gotten rid of the worst of the errors and allowed me to continue.
Next, you will almost certainly have to update the Perl Packages which BugZilla depends on; running perl checksetup.pl will tell you which packages, in no uncertain terms! If you have chosen ActivePerl, you will find a GUI Perl Package Manager in your Start Menu; just remember to follow the instructions from checksetup.pl to add the recommended Repository to the Package Manager. Go ahead and update all the packages to their most recent versions; there are generally bug fixes in the later versions.
You may have some issues with checksetup.pl insisting you have not installed packages which you definitely have, and have updated; this seems to be related to a package dependency interrelation. I solved it more or less by trial and error, Checking, re-installing or repairing the packages it complained about. It was a bit frustrating.
At some point, flailing about with error messages and getting desperate, I decided upgrading mySQL from 5.0 to 5.1 would solve all my problems! Well, actually, Not So Much. It didn’t break anything, though. And my old version, 5.0, is no longer being actively developed/supported; mySQL recommends all users upgrade. Just be sure you have backed up your database! You’ll want to follow the instructions on the mySQL site to Stop the old mySQL service, remove it, then install the new version side-by-side in a new directory. Then, restore the backed-up database, and run mysql_update to upgrade the database tables; follow the mySQL instructions on the BugZilla site to configure the database and re-create the ‘bugs’ user and give it the proper permissions.
The .MSI installer
I promised I would mention some of the caveats to the .MSI installer. Other than the relatively unsupported status, the main one is such that it is unsuited to upgrades: it cannot make use of existing installations of Perl, and it will not use IIS, nor an existing installation of Apache. It fresh-installs new copies of both Perl and Apache. If you have not yet installed BugZilla or any of its dependencies, it becomes very attractive; but we are discussing upgrades here, for which it is, as noted, not suited.
That should get you through the worst of it, without struggling like a fish on a hook, as I did!
Oh, and the new features in BugZilla? Well worth the effort, if your previous version was as old as mine was!