Sunday, May 24, 2009

Installing FogBugz on Ubuntu 9.04

Joel Spolsky is a notable netizen in the technology industry for a variety of reasons, including his blog, Joel on Software, his articles for Inc. magazine, his speeches at many industry conferences, and co-founding the Stack Overflow programmers' website.

Joel's day job is as CEO of Fog Creek Software, and Fog Creek's flagship product is FogBugz, an inexpensive web-based issue tracking system with some other nice features like an integrated wiki.

When my wife and I switched from Mac OS 9 to Mac OS X for day-to-day productivity work, we'd been using Seapine's TestTrack for bug tracking, but it became less and less viable for us. So she did a search for alternatives, and liked FogBugz the best. The commercial bug tracking systems were pretty expensive, and there weren't any open-source equivalents with good documentation at the time.

FogBugz is still quite reasonable for a small team that doesn't have IT staff: it's pretty cheap, and pretty good, and pretty functional, and pretty bug-free, and doesn't take a lot of administration or maintenance. Some of the open-source alternatives like Trac have probably caught up with it on features and ease of installation and administration. But FogBugz costs only $36.50 per programmer per year for a maintenance contract, so it' s not worth it to us to switch.

However, in my opinion, FogBugz has one big flaw. While it runs on Windows, Mac OS X, Linux, and Unix servers, the FogBugz documentation and support is heavily Windows-oriented. If you want to install on a non-Windows platform, Fog Creek's instructions are decidedly not turnkey and not updated even yearly. Their tech support people are nice, and happy to transfer licenses or point you to hard-to-find documentation URLs, but if you're having an unusual problem on a non-Windows platform that their documentation doesn't cover, they are of limited help.

Anyway, I decided to upgrade our FogBugz server from an older version of Ubuntu to 9.04 (Jaunty Jackalope), and did so by wiping the hard drive and re-installing everything, including FogBugz. So here are the general steps, after you've installed Ubuntu. This also is not exactly turnkey - you should be a reasonably knowledgeable Ubuntu user and know when to sudo things, for instance - but it should help keep you from running into roadblocks.


Review a few URLs

You should at least skim these, and may want to print them out.

Here are some Fog Creek pages, but don't take them for gospel truth. I'm writing this post to correct and expand upon them: Getting Your Unix Server Ready For FogBugz and Unix System Requirements.

You should also look at ApacheMySQLPHP on the Ubuntu site, which has some slightly dated background on other components you'll need to install and configure.


Install a LAMP stack

The FogBugz documentation's list of packages to install is very dated and incomplete. You don't need to install mono because it's included with Ubuntu 9.04 desktop. But you need to install a lot of other packages so that the Apache, MySQL, and PHP parts of a LAMP stack will work correctly with FogBugz. Here's what I eventually wound up installing via Synaptic:
  • apache2
  • php5
  • php5-cli
  • php5-imap
  • php5-dev
  • mysql-server
  • mysql-client
  • curl
  • php5-mysql
  • php-pear
  • mono-gmcs
  • mono-devel
  • php5-curl
When you install mysql, you'll have to give it an administrator account name and password. Remember these! You'll need them later.

And then these two are just handy:
  • mysql-query-browser
  • mysql-admin

Configure Networking, Apache, and PHP

If your server has a static IP address, edit /etc/hosts, and make sure your local and fully-qualified machine names (both foo and foo.example.com) are associated with that IP address.

Edit /etc/apache2/httpd.conf and add a server name line:
ServerName foo.example.com

Make sure all the PHP modules are enabled, and then restart the Apache web server:
sudo a2enmod php5
sudo /etc/init.d/apache2 restart

Set up a test page for your PHP extensions: edit /var/www/test.php and fill it with the PHP test info from here. Then open http://localhost/test.php in Firefox and make sure the XML, imap, mysql, and iconv lines all have a 1 at the end.


Install eAccelerator

eAccelerator is a caching system for PHP that FogBugz highly recommends. I do, too - when you're working with the FogBugz database from a client machine over a network, if you don't have eAccelerator installed, you'll be going on a lot of coffee breaks.

Unfortunately, Ubuntu doesn't supply an eAccelerator package, so you have to build it from sources. The official page on how to do this is here, but I didn't find it very helpful on Ubuntu. This page is a lot more accurate and detailed for Ubuntu installation.


Configure MySQL

First, you'll need to get a MySQL prompt. You did write down your administrator name and password above, right?
mysql -u your_administrator_name  -p
and enter the password when prompted.

Then, you'll need to follow the instructions here.

I populated my FogBugz database by a simple directory copy of an old version, so I didn't run into this today. But from an earlier installation, I knew that FogBugz is not compatible with the most recent MySQL password scheme. That means if you're doing an initial installation or you're populating the database via export/import, you'll have to follow some further instructions to tell MySQL to use an older password scheme.


Install FogBugz

Download and unpackage the FogBugz tarball, and follow the Unix Setup Steps instructions. Unlike the instructions, I ran install.sh as superuser. When you run the install, it will ask if you want to install various Pear files; just type "y" for all of them.

Eventually, you'll get to a web-based FogBugz configuration screen. You still do remember that MySQL administrator account information, right? Here's what I used:
Server: localhost
...
Database name: fogbugz
FogBugz user account: fogbugz

Then the web screen will ask you for your Fog Creek order number and email address, and try to validate it with the Fog Creek license server. If you're doing a new installation, after this, you should be up and running.

I was transferring the database and license from a previous installation. That confused the Fog Creek license server and it wanted me to call in to get my installation count incremented. However, I had done a straight backup of /var/lib/mysql/fogbugz on the older installation, so I:
  1. Closed the web browser page that was telling me to call Fog Creek.
  2. Shut down mysql
  3. Did a cp -pr from the backup into my new installation
  4. Did a chown/chgrp of the copied files to mysql, and
  5. Restarted mysql
And at that point, FogBugz was back in operation.

It all took a few hours, and would certainly have been a lot quicker if I'd had this post!

Update (16 July 2009)

David Llopis remarked in the comments: I think if you install "apache2", Ubuntu defaults to installing "apache2-mpm-worker" rather than the "apache2-mpm-prefork" that you should use.

You do need prefork for PHP to run correctly, and David is correct if you do something like just go into Synaptic and select the "apache2" package and hit the "Apply" button.. However, if you don't hit the "Apply" button right away, and select the "php5" package, that will deselect the worker package and select the prefork package. Anyway, you should definitely double-check that you're installing prefork, particularly if you're installing in a different Ubuntu version than 9.04.

Also, Chris Lamb posted instructions on installing FogBugz into Debian Lenny; they contain a few configuration tweaks that might be worth a look.