This document describes what the install process does when you install FogBugz 6 for Macintosh. It is intended to help system administrators understand how the system is modified, and should help you understand how FogBugz is set up so that you can diagnose and correct problems. Although we don't recommend setting up FogBugz manually, it is possible to do so by following the instructions in this document.
The installer supports any configuration in which the PHP you want to use is on the path, and specifically looks for the entropy.ch php installation, as well as the MacPorts default location (/opt/local). If you have PHP5 installed at /usr/local/php5/bin/php, we use that one first, then we check in /opt/local/bin, otherwise we check the one `which php` says is in use.
For more specific information, all of the install scripts are accessible inside the FogBugz package -- you have to use the Terminal to get to them:
(in /Volumes/fogbugz/fogbugz.pkg/Contents/Resources):
(in /Library/WebServer/fogbugz):
The InstallationCheck checks for PHP>5.1, curl, PHP IMAP libraries, PEAR, and Mono>1.2.3, so the installer can die early if you don't have one of the base dependencies.
The postflight script runs install.sh, and also installs and starts the FogBugz Maintenance Service for Mac.
The install.sh script rechecks the FogBugz requirements, copies the FogBugz files to the appropriate directory while backing up your old installation, and then does the following steps:
1. Install Certain PHP Modules
The script uses PEAR, the "PHP Extension and Application Repository," to install the latest versions of four PHP modules. (pear must be in your path. 'which pear' will tell you if it is or not). The versions shown below in parentheses are the versions we tested at the time FogBugz for Mac was originally released; later versions will probably work but have not necessarily been tested.
Mail_Mime (1.2.1)
XML_Tree (2.0b2)
Auth (1.2.2)
Auth_SASL (1.0.1)
2. Add a Custom PHP Module, fogutil.so
FogBugz relies on a small custom PHP module called fogutil.so to provide certain functionality. This module, shipped in the Accessories directory, is a binary file compiled for your particular operating system.
fogutil.so is copied to the php modules directory, then chmod'ed to 755. The install script adds the line extension=fogutil.so to the php.ini file, a change which will probably require that you restart Apache.
3. Setting Permissions
The install script sets ownership and permissions for various files and directories so that the user account under which Apache is running has permission to access everything it needs:
chown -R $FB_USER $INSTALL_DIR
chmod u+x "$INSTALL_DIR"
chmod -R o-wx "$INSTALL_DIR/Website"
chmod -R u-w "$INSTALL_DIR/Website"
chmod -R o-wx "$INSTALL_DIR/Accessories"
chmod 554 "$INSTALL_DIR/Accessories/fogbugzmaintd"
chmod 444 "$INSTALL_DIR/Accessories/fogbugzmaintd.php"
chmod 664 "$INSTALL_DIR/Accessories/application.data"
4. Adding a Directory to httpd.conf
Apache is configured so that the http://.../FogBugz URL points to ../Website/default.php on disk by adding this section to the httpd.conf file:
Alias /FogBugz "/path/to/FogBugz/Website"
<Directory "/path/to/FogBugz/Website">
Options
AllowOverride All
DirectoryIndex default.php
</Directory>
5. Restart Apache
The install script attempts to restart apache to get it to reload its settings and php extensions.
Note: Understanding the File Layout
When you untar FogBugz you'll see three directories. Website contains the PHP source code and is the only directory which is served up by your web server. FileUploads was used by FogBugz 2.0 and 3.0 to hold copies of files which have been uploaded as bug attachments; now, in FogBugz 4.x and above, these files are moved to the database. If you are upgrading these files will trickle into the database slowly, although this is completely transparent. The Accessories folder contains any and all other sundry files shipped with FogBugz .
For security reasons, neither FileUploads nor Accessories should be in a directory that is served by the web server!