HOWTO: Install Habari on Mac OS X Leopard, From Scratch

Installing Habari isn’t really that complicated, however getting OS X up and running ready for the installation requires a bit of work.

Mac OS X 10.5 (aka Leopard) conveniently comes with Apache 2 and PHP 5, so most of the work in setting up a MAMP server has already been done for you. Sure there are other ways to get a MAMP setup: you can build Apache, MySQL and PHP from sources, you can use MacPorts or you can use pre-built packages like MAMP or XAMPP.

I prefer to use as much of what is supplied with the OS as possible as there’s no point having duplicate applications on a system. It also makes keeping them up-to-date much easier - it becomes Apple’s job, not mine.

Anyway, in order to get all the way through this article there are a couple of requirements:

1. You have XCode installed
2. You’re fairly comfortable in using the command line.

This last requirement isn’t strictly true as I will provide all the commands you need to run anyway.

The rest of this post assumes you’ve not configured PHP, Apache or MySQL on OS X at all yet. If you have, don’t worry, I’m sure you’ll be able to easily pick things up.

NOTE: There is one caveat with this approach: Apple’s updates may require you to redo any one of the steps below as it may replace files you’ve modified or provide newer incompatible versions of software.

Update: You can find details on installing gd on OS X as a universal binary for 32-bit and 64-bit here.

The Web Server

Apache already comes pre-configured to work using /Library/WebServer/Documents as the document root, however it’s not configured to load the PHP module, so you’ll need to do this yourself.

It’s also running in 64-bit mode, which is a not really necessary for general usage, especially for testing a local Habari installation. It also over complicates the MySQL pdo_mysql creation process.

So first things first, lets force Apache to run in 32-bit mode.

1. Make a copy of the system launch daemon plist file:

   $ sudo cp /System/Library/LaunchDaemons/org.apache.httpd.plist \
/Library/LaunchDaemons/org.apache.httpd.plist

2. Open this file and change…

   <array>
           <string>/usr/sbin/httpd</string>
           <string>-D</string>
           <string>FOREGROUND</string>
   </array>

   … to …

   <array>
   	<string>/usr/bin/arch</string>
   	<string>-i386</string>
           <string>/usr/sbin/httpd</string>
           <string>-D</string>
           <string>FOREGROUND</string>
   </array>

3. Reboot. Once you’re system has rebooted, it should be running in 32-bit mode.
4. To enable PHP support, uncomment the following line in /private/etc/apache2/httpd.conf:

   LoadModule php5_module libexec/apache2/libphp5.so

   If you’re going to install Habari into the main document root (/Library/WebServer/Documents), you’ll need to find “AllowOverride None” within the section of this file and change it to “AllowOverride All” so that the .htaccess file used by Habari will work.

   If you’re going to install Habari into a user’s “Sites” directory, you’ll need to make the same change in the user’s /private/etc/apache2/users/[username].conf file.

   After making changes, restart Apache using one of the following methods (remember this as we’ll be doing this agan later):
   
   GUI: Go to System Preferences > Sharing and disable and enable Web Sharing
   CLI: $ sudo apachectl restart

   Now you have the Apache and PHP running.

You can confirm it’s working and the check the PHP settings by creating a file (eg phpinfo.php) containing <? phpinfo(); ?> either in /Library/WebServer/Documents or a user’s Sites directory and browse to that file using http://localhost/phpinfo.php or http://localhost/~username/phpinfo.php respectively.

This is probably a good idea so you can see what PHP settings required by Habari have already been enabled.

The Database

You’ve got a choice here. If you’re just looking for a simple Habari installation and aren’t really too concerned about the database backend, then you can go with SQLite. It’s supplied and enabled by default on OS X, so there’s nothing more to do on the database side of things.

However, if you want to use MySQL, then you’re in for a bit more work as sadly MySQL isn’t supplied with OS X. Unfortunately, I know very little about PostgreSQL at the moment, so I’ve not documented this. Maybe one day in the future .

So time to make a choice:

SQLite: Nothing more to do here, skip to the Enabling GD Extension section below.

MySQL: Read on.

The easiest option is to download and use the pre-compiled 32-bit binaries from mysql.com. As with Apache, there’s really no point running 64-bit binaries, so you’ll need the 32-bit binaries as we’ve forced Apache to run in 32-bit mode above.

Once downloaded, install the mysql-*.pkg file. Then if you want MySQL to start automatically on boot, install MySQLStartupItem.pkg. There’s also a Preferences pane that you can use to stop and start MySQL from the Preferences. To install this copy MySQL.prefPane to /Library/PreferencePanes.

Once MySQL has been installed, start it and set appropriate passwords as they’re all blank by default. The ReadMe.txt file that comes with the MySQL download details how to start MySQL.

Once started, you can set the root password as follows:

$ /usr/local/mysql/bin/mysqladmin -u root password {new-password}
$ /usr/local/mysql/bin/mysqladmin -u root -p{new-password} -h localhost password {new-password}
$ /usr/local/mysql/bin/mysqladmin -u root -p reload

MySQL should now be up and running and ready for access using your new root password.

Enabling the GD Extension

If you have no intentions of using the Habari Media Silo (used for uploading images etc to Habari via the admin interface) within your local Habari installation, you can skip this step and move straight onto configuring Enabling the PDO_MYSQL Driver section.

If you want to use the silo plugin, then unfortunately things start to get tougher now, though not too tough, as this is where we start to compile code.

Once again, OS X is a bit limited by what it supplies, and in order to get the GD extension built, we need to install libjpeg first.

1. Download the Libjpeg source code and extract the tarball:

   $ cd /tmp
$ curl -O http://www.ijg.org/files/jpegsrc.v6b.tar.gz
$ tar zxf jpegsrc.v6b.tar.gz


2. Compile and install libjpeg:

   $ cd jpeg-6b
$ cp /usr/share/libtool/config.* .
$ sudo mkdir -p /usr/local/include \
/usr/local/bin \
/usr/local/lib \
/usr/local/man/man1
$ ./configure –enable-shared
$ make
$ sudo make install

   Once libjpeg has been installed, we can finally move onto building the GD extension.

3. Download the PHP source of the version your Mac is running (the phpinfo() used above will tell you), probably PHP-5.2.6, and extract the tarball:

   $ cd /tmp
$ curl -O http://uk3.php.net/distributions/php-5.2.6.tar.bz2
$ tar xjf php-5.2.6.tar.bz2

4. Then move to the expanded directory and execute the following commands to prepare for the compilation of the extension:

   $ cd php-5.2.6/ext/gd
$ phpize

5. We can now compile the GD extension:

   $ MACOSX_DEPLOYMENT_TARGET=10.5 \
CFLAGS="-O3 -fno-common -arch i686" \
LDFLAGS="-O3 -arch i686" \
CXXFLAGS="-O3 -fno-common -arch i686" \
./configure --with-zlib-dir=/usr \
--with-jpeg-dir=/usr/local/lib \
--with-png-dir=/usr/X11R6 \
--with-freetype-dir=/usr/X11R6 \
--with-xpm-dir=/usr/X11R6
$ make
$ sudo make install

   NOTE: You will need to change “i686” to suit your architecture. i686 is for Macs with Intel CPUs.

6. Now the extension has been compiled and installed, you’ll need to tell PHP about it by making the necessary changes to you /private/etc/php.ini file.

   Check to see if you have a /private/etc/php.ini file:

   $ ls -l /private/etc/php.ini

   If you get no output, you’ll need to make a copy of the default file:

   $ sudo cp /private/etc/php.ini.default /private/etc/php.ini

   Once you’ve got a php.ini file, edit it and change the “extension_dir” to point to /usr/lib/php/extensions as follows:

   extension_dir = "/usr/lib/php/extensions"

   Now locate the “Dynamic Extensions” section of the file and add the following line just above the line that reads “; Windows Extensions”:

   extension=gd.so

   The location of this line in the file isn’t too important, however putting it here keeps things tidy and easy to locate later, if needed.

7. We’re almost done telling PHP about the GD extension, all we need to do is make sure it can find it in the directory we’ve specified by creating a symbolic link to the gd extension:

   $ sudo ln -s /usr/lib/php/extensions/no-debug-non-zts-20060613/gd.so /usr/lib/php/extensions/gd.so

8. Restart Apache and check in the phpinfo that GD is now loaded. You can also verify from the command line too:

   $ /usr/bin/php -i | grep gd
gd
$

Enabling the PDO_MYSQL Driver

If you’ve reached this section, then you’re intent on getting Habari working with MySQL.

As OS X doesn’t ship with MySQL, it doesn’t ship with the PDO driver needed by Habari to connect to MySQL, so we’ll create the driver outselves.

1. We’ve already got the PHP source downloaded from enabling the gd extension, so move to the expanded directory and execute the following commands to prepare for the compilation of the PDO driver extension:

   $ cd /tmp/php-5.2.6/ext/pdo_mysql
$ phpize

2. Once this completes, it’s time to compile the extension for your system by running the following commands:

   $ MACOSX_DEPLOYMENT_TARGET=10.5 \
CFLAGS="-arch i686 -g -Os -pipe -no-cpp-precomp" \
CCFLAGS="-arch i686 -g -Os -pipe" \
CXXFLAGS="-arch i686 -g -Os -pipe" \
LDFLAGS="-arch i686 -bind_at_load" ./configure --with-pdo-mysql=/usr/local/mysql
$ make
$ sudo make install

   NOTE: You will need to change “i686” to suit your architecture. i686 is for Macs with Intel CPUs.

3. Now the extension has been compiled and installed, you’ll need to tell PHP about it by making the necessary changes to you /private/etc/php.ini file.

   As we did above in the GD section, add the following line to the “Dynamic Extensions” section:

   extension=pdo_mysql.so

4. We’re almost done telling PHP about the pdo_mysql extension, all we need to do is make sure it can find it in the directory we’ve specified by creating a symbolic link to the pdo_mysql extension:

   $ sudo ln -s /usr/lib/php/extensions/no-debug-non-zts-20060613/pdo_mysql.so /usr/lib/php/extensions/pdo_mysql.so

5. The last thing we need to do is tell PHP about the socket location for MySQL. PHP is compiled to look in a different place to where MySQL actually puts it’s socket file. To get PHP looking in the right place, locate the “mysql.default_socket = ” line in the php.ini file and change it look as follows:

   mysql.default_socket = /tmp/mysql.sock

6. Restart Apache and confirm PHP had loaded the pdo_mysql module successfully. As with the gd extension, you can verify this with the phpinfo() output, or from the command line:

   $ /usr/bin/php -i | grep pdo_mysql
pdo_mysql
$

That’s it for the hard work.

Installing Habari

Once you’ve gone through all the above, you should find installing Habari a walk in the park. For these steps, I’ll turn you over to the official Habari installation instructions.