HowTo Install FogBugz 5 on Mac OS X 10.4 Tiger

Updated: 2007-09-22

Goals

What are we trying to do here? Basically, we just want to get FogBugz installed on the Mac. We’re using the regular client version of OS X and FogBugz 5.x. We want the email functions of FogBugz, but aren't really interested in the version control system integration. The email features can work with pretty much any email account, so we're not setting up an email server. All right. Now that we know what we're doing, let's get cooking!

Ingredients

The freshest version of each ingredient when we wrote this up is listed in the brackets.

  1. Mac OS X 10.4 Tiger Client. [10.4.11]
  2. XCode 2.x. [2.4.1]
  3. MySQL 5.x. [5.0.45]
  4. MySQL GUI tools. [5.0r12]
  5. PHP 5 from Entropy.ch. [5.2.4]
  6. FogBugz 5.x. [5.0.31] A version later than 5.0.25 is required to run on Intel Macs.
  7. eAccelerator. [0.9.5.2]

Preparation

  1. Wash your hands and put on your apron. It's time to barbecue!
  2. Turn on Personal Web Sharing in System Preferences. This enables the built-in Apache 1.3 web server.

Instructions

  1. Install Xcode from the package in the disk image. No special options are needed.
  2. Install MySQL server.
    1. Install the server from the package in the disk image.
    2. Install the StartupItem from its package in the disk image.
    3. Install the PrefPane from the disk image by double-clicking it. Choose to Install for all users of this computer.
    4. In the MySQL PrefPane that opens:
      1. Check Automatically start MySQL server on startup
      2. Click the button to start the MySQL server.
    5. Note: At this point, the MySQL root user does not have a password, which is not good for security. However, it makes the installation process easier if we add the password later, rather than now.
  3. Install MySQL GUI tools from the disk image.
    1. Drag the two applications, MySQL Administrator and MySQL Query Browser, to the Applications folder in the Finder.
    2. Install the MySQLHealth Widget by double-clicking it. Confirm that you want to install and keep it.
      Note: This only installs the Widget for the current user account.
  4. Install PHP from the package in the disk image. No special options are needed.
  5. Open a terminal window with an administrator account login.
    1. If your account is an administrator account, then just open a terminal.
    2. If your account is not an administrator account, then you need to su to an administrator login. For example, if you have a regular user account user and an administrator account admin, then execute su admin in the terminal to log in as admin. You will then need to type the password for the admin account. You can confirm your login by executing whoami in the terminal. In our example, you should see the response admin.
    3. The sudo command that we use below elevates your rights to superuser. It will require you to enter the password for your administrator account.
  6. Configure PHP. This is where things get interesting.
    1. In the terminal, change directory to /usr/bin and back up the built-in PHP commands.
      1. cd /usr/bin
      2. sudo mv php php.macosx
      3. sudo mv pear pear.macosx (you may see an error that this file doesn't exist, that's OK).
      4. sudo mv php-config php-config.macosx
      5. sudo mv phpize phpize.macosx
    2. Symlink the new PHP commands. The Entropy package installs PHP in /usr/local/php5, this makes the commands appear to be in /usr/bin where everyone expects them to be.
      1. cd /usr/bin
      2. sudo ln -s /usr/local/php5/bin/php php
      3. sudo ln -s /usr/local/php5/bin/pear pear
      4. sudo ln -s /usr/local/php5/bin/php-config php-config
      5. sudo ln -s /usr/local/php5/bin/phpize phpize
    3. Use PHP's recommended php.ini settings.
      1. cd /usr/local/php5/lib
      2. sudo mv php.ini php.ini.original
      3. sudo cp php.ini-recommended php.ini
    4. Test PHP.
      1. php -v
      2. Should display the version number that you just installed. 5.2.4 in our example.
    5. Test PHP in Apache.
      1. Note: The Entropy PHP package is installed with short_open_tags disabled. So, all PHP code needs to have an opening tag of <?php
      2. Use the sample file from the FogBugz Mac system requirements page we opened earlier.
        <?php
        echo PHP_VERSION . "<br>";
        echo "XML:" . extension_loaded('xml') . "<br>";
        echo "imap:" . extension_loaded('imap') . "<br>";
        echo "mysql:" . extension_loaded('mysql') . "<br>";
        echo "iconv:" . extension_loaded('iconv') . "<br>";
        phpinfo ();
        ?>
      3. Note: If you copy the above code, you must remove the space between "phpinfo" and "();" in the next to last line. The extra space is needed to allow WordPress to handle the content.
      4. Be sure that opening PHP tag is <?php and not just <?.
      5. Name the file test.php and put it into your /Users/username/Sites directory.
      6. Open a browser to http://localhost/~username/test.php and you should see the output of the test.php file in your browser.
  7. Configure PEAR in PHP.
    1. Upgrade PEAR to the latest and greatest.
      1. sudo pear upgrade
      2. sudo pear upgrade-all
    2. Install additional PEAR packages needed by FogBugz.
      1. sudo pear install --alldeps Mail
      2. sudo pear install --alldeps Mail_Mime
      3. sudo pear install --alldeps XML_Tree
      4. sudo pear install --alldeps Auth
      5. sudo pear install --alldeps Auth_SASL
      6. sudo pear install --alldeps HTTP
      7. sudo pear install --alldeps HTTP_Client
  8. Install FogBugz from the package in the disk image.
    1. The installation will open a page in Safari: http://localhost/fogbugz/install1.php?3535 (the numbers seem to vary from one installation to the next. Who knows what that's about?)
    2. Back to the installer for a moment: it should say the software was successfully installed. You can close the installer.
    3. install1.php in Safari will probably have a couple of warnings about php.ini
      1. set display_errors to Off
      2. set error_reporting to E_ALL & ~E_NOTICE
    4. Edit php.ini as suggested. Find and edit the settings as needed, and save the file.
      1. cd /usr/local/php5/lib
      2. sudo nano php.ini
    5. Stop and start Web Sharing from System Preferences to reload the PHP settings.
    6. Refresh the install1.php page in Safari. The warnings about php.ini should be gone. Click the I Agree link to continue.
    7. Install2.php should display in Safari. Enter the information to set up the FogBugz database. The defaults should be correct, just add the info for the FogBugz database user.
      1. Language: default = English
      2. MySQL server: default = localhost
      3. Database name: default = fogbugz
      4. Database admin account: default = root
      5. Database admin password: default = <blank>
      6. New FogBugz user account [this is the account FogBugz will use to log into the MySQL database with after it's created]: default = fogbugz
      7. New password: enter a password for the fogbugz MySQL account
      8. Click OK to continue.
    8. Install3.php should display in Safari with some warnings about php.ini settings that need to be changed for the fogbugzmaint service.
      1. max_execution_time = 600
      2. max_input_time = 600
      3. memory_limit = 50M (this was already 128M in my setup, I chose to leave it at the higher setting).
      4. upload_max_filesize = 50M
      5. post_max_size = 50M
    9. Edit php.ini as suggested. Find and edit the settings as needed, and save the file.
      1. cd /usr/local/php5/lib
      2. sudo nano php.ini
    10. Install3.php will also be displaying some warnings about the MySQL configuration file my.cnf.
      1. max_allowed_packet = 50M
    11. NOTE: The rest of install3.php about setting the fogbugzmaint service to auto start can be ignored. On Mac OS X, the installer sets this up automatically.
    12. Set up a my.cnf file with proper settings. Find and edit or add the settings as needed, and save the file.
      1. sudo cp /usr/local/mysql/support-files/my-large.cnf /etc/my.cnf
      2. cd /etc
      3. sudo nano my.cnf
    13. Stop and start MySQL from the MySQL Preference Pane.
    14. Confirm changes to MySQL configuration.
      1. Run the MySQL Query Browser
      2. Run the query select @@local.max_allowed_packet; The value should be somewhere around 52,427,776.
    15. Stop and start Web Sharing from System Preferences to reload the PHP settings.
    16. Refresh install3.php in Safari. The new php.ini settings should show up in the table, but there won't be any change in the MySQL info. Click the click here link at the bottom of install3.php
    17. Safari will display the FogBugz is being upgraded page. Click the link create the FogBugz database tables to create the FogBugz tables.
    18. Safari will redisplay the page with a note about which version of the FogBugz schema the database has been updated to.
      Click the OK link.
    19. FogBugz will display a page with two warnings:
      1. fogutil.so is being loaded by dll() instead of as an extension
      2. You really want to install a PHP accelerator
    20. Edit php.ini to load fogutil.so as an extension.
      1. cd /usr/local/php5/lib
      2. sudo nano php.ini
        1. Find the area with a bunch of extension= lines and add:
        2. extension=fogutil.so
        3. Save the file.
    21. Stop and start Web Sharing from System Preferences to reload the PHP settings.
    22. Refresh the FogBugz page in Safari. The warning about fogutil.so should disappear.
    23. Install eAccelerator from source.
      1. Move the zip file to /Users/Shared. NOTE: You want to use /Users/Shared to avoid
        permissions errors.
      2. Unpack the zip file from the command line. Again, to avoid permissions errors.
        1. cd /Users/Shared
        2. unzip eaccelerator-0.9.5.2.zip
      3. Build it, then install it.
        1. cd /Users/Shared/eaccelerator-0.9.5.2
        2. phpize
        3. ./configure
        4. make
        5. sudo make install
        6. Make a note of the full path of where this command says the extension library was installed. In my case it was /usr/local/php5/lib/php/extensions/no-debug-non-zts-20060613/
      4. Edit php.ini to load the eAccelerator extension. Loading as a Zend extension is preferred. Zend extensions must have the full absolute path listed.
        1. cd /usr/local/php5/lib
        2. sudo nano php.ini
          1. zend_extension="/usr/local/php5/lib/php/extensions/no-debug-non-zts-20060613/eaccelerator.so"
          2. eaccelerator.shm_size="16"
          3. eaccelerator.cache_dir="/var/run/eaccelerator"
          4. eaccelerator.enable="1"
          5. eaccelerator.optimizer="1"
          6. eaccelerator.check_mtime="1"
          7. eaccelerator.debug="0"
          8. eaccelerator.filter=""
          9. eaccelerator.shm_max="0"
          10. eaccelerator.shm_ttl="0"
          11. eaccelerator.shm_prune_period="0"
          12. eaccelerator.shm_only="0"
          13. eaccelerator.compress="1"
          14. eaccelerator.compress_level="9"
        3. Save file.
      5. Create cache directory for eAccelerator. (This may not be the best place to put the cache dir, but it's a reasonable choice, and works fine.)
        1. cd /var/run
        2. sudo mkdir eaccelerator
        3. sudo chmod 777 eaccelerator
      6. Test eAccelerator.
        1. Stop and start Web Sharing from System Preferences to reload the PHP settings.
        2. Go to the http://localhost/~username/test.php page in Safari.
          1. There should be a section of the phpinfo() output specifically for eAccelerator.
    24. Refresh the FogBugz page in Safari. The warning about a missing eAccelerator should be gone. http://localhost/fogbugz/default.php?pg=pgCheckDl In my case, the warning wouldn't disappear, but refreshing the test.php page showed hundreds of PHP scripts getting cached and optimized.
    25. Click the link Click here to continue to FogBugz to continue.
    26. Enter your email and order number to retrieve your license from Fog Creek and install it automatically.
    27. Configure FogBugz.
      1. From here on, you can use the FogBugz support info, or get a book (see below).
  9. Set a root password on MySQL.
    1. Open the MySQL Administrator.
    2. Click on Accounts in the toolbar.
    3. Click on root in the list.
    4. Enter and confirm a new password.

That's it! Now you're ready to start using FogBugz. There's a nice book by Mike Gunderloy about using FogBugz called Painless Project Management with FogBugz. I've got the first edition, which is suitable for FogBugz 4 and 5. But the even bigger and better 2nd edition is out and covers all the new features in FogBugz 6.0. I'll be updating the instructions here on the site for FogBugz 6 and Leopard when they come out.

Happy bug hunting!