Phillip Smith

Okay, I admit it: Bricolage CMS -- the open-source enterprise-class content management system -- takes a few hours to install. The upside? A well-deserved sense of accomplishment.

Seriously, as someone who works with Bricolage regularly and likes to contribute to the project (when time permits), it's incredibly helpful to be able to have it running locally on my laptop from the latest Github source.

Unfortunately, the Bricolage installation documentation for OS X needs some serious love. There are at least three contradictory resources at the moment: David Wheeler's post "My Adventures with Mac OS X" from 2002 (OS X 10.1), the README.MacOSX that Bricolage comes with, and the "Installing Bricolage on Mac OS X wiki page on Github, which only covers OS X 10.3. Thankfully, Theory (David Wheeler) is easy to find in the #bricolage channel on irc.perl.org and can be cajoled into providing helpful install hints.

All that said, installing Bricolage 2.0 on the current version of OS X -- 10.6.4 "Snow Leopard" -- was actually quite straightforward. So, before diving into updating all of the install documentation, I wanted to capture the basic process here and get some feedback on next steps. If you want to help with feedback, just jump to the Questions section at the end of this post.

Before you begin

Quoting from a Bricolage wiki page:

Xcode Tools (formerly Developer Tools): As of OS X 10.3, all of the development libraries, compilers, etc. are included in Xcode Tools. In 10.2 and prior, they were included in the Developer Tools. In order to compile anything on OS X, you need to install Xcode Tools. These are available for free from the Apple Developer Connection website. It is currently a 600+ MB download, so go make yourself something to eat while you wait.

So you'll need to download Xcode, or install it from your Snow Leopard DVD.

Installing the pre-requisites

Bricolage is a big application and it requires a non-trivial list of prerequisites to be installed. Notably a bunch of Perl modules, Expat, and libapreq. And, given that Bricolage is a modperl application, you'll also require Apache, modperl, and also a database like Postgres or MySQL.

Personally, I like to just run the latest version of just about everything, and my sense is that what many other folks will want to do also, so I elected to skip anything relating to Apache 1.3 or mod_perl 1.

So, referring to the three documents mentioned above, I got underway with the prerequisites as follows:

gdbm: I skipped installing gdbm on Theory's recommendation.

Expat: Pretty straightforward. Download the latest source (expat-2.0.1 in my case), untar it and enter directory, run './configure' and then 'make', 'make test', and 'sudo make install'.

Perl: This is a topic for a longer post, but quickly: OS X comes with Perl v5.10.0 these days, however many recommend installing a newer version in /usr/local/ for any serious Perl fun. Compiling your own Perl also helps to ensure that you don't mess up the system's Perl installation, and that future upgrades to the OS won't mess up your Perl.

I already had Perl v5.12.1 built on my laptop, but -- if you need to do that -- the basic steps to build and install Perl with all of the defaults are: download the latest source, untar the source, enter the source directory and type 'sh Configure -de', then 'make', 'make test', and 'sudo make install'. It's very straightforward. After it's installed, be sure to add something like 'export PATH=/usr/local/bin:$PATH' to your .profile or similar to use the new Perl by default.

Apache 2: I took the lazy route here and just used Theory's Apache 2 installation script. He's got some fancy Capistrano set-up that uses the above linked script to download, unpack, and compile Apache 2 in one step. If you want to do it manually, just follow the steps in that script.

Remember that you'll now have two versions of Apache 2 installed on your system -- the one installed by OS X, and the one you've just installed -- thus you'll want to update your .profile or similar to use it be default with something like 'export PATH=/usr/local/apache2/bin:${PATH}'.

A nice side-effect of using Apache 2 is that it there's no need to separately download and install mod_ssl, as it's already included. Same goes for OpenSSL, as it ships with OS X these days. So a few steps are saved there.

libapreq: You'll also need this library installed and loaded in Apache 2. However, to build libapreq you'll need to first install ExtUtils::XSBuilder. I did that quickly via CPAN. Similar to Apache 2 above, I took the easy route and used Theory's fancy little install script to install libapreq for Apache 2.

mod_perl2: This was a bit tricky, as there were various sources of conflicting advise on the best way to configure mod_perl2 on OS X. In the end, I went with the following: download the latest source, untar and enter source directory, and 'perl Makefile.PL', 'make -j8', make test (some tests fail), sudo make install.

After the successful install, make sure to follow the instructions presented and add the 'LoadModule perl_module modules/mod_perl.so' line to your Apache 2 httpd.conf file.

Testing everything so far

At this point, I wanted to ensure that everything was working smoothly before I proceeded. To do that, I started up Apache 2 with 'apachectl start' and confirmed that Apache 2 was running, and then ran 'apachectl -M' to list all of the loaded modules and looked to confirm that 'perl_module' was there.

If you want to do one step further, you can also follow the mod_perl documentation to test that you can successfully serve a .pl file.

Postgres or MySQL

Installing PostgreSQL was dead simple. I just followed Mark H. Nichols' write up, which included the manual steps to create a new user and group for Postgres now that Apple no longer ships the Netinfo Manager application.

For MySQL, there are lots of articles on installing it from source, or you can use the handy one-click binary installer.

Perl modules

If you're using Perl regularly, you'll probably have a bunch of the Perl modules installed already. If not, I would recommend something like Task::Kensho as a great way to install a set of "Enlightened Perl" modules that ease day-to-day development with Perl. Either way, here's a list of the modules that you'll want to install first:

• XML::Parser
• DBD::Pg
• Test::File
• Imager

And, also, most of the modules listed in Bundle::Bricolage. I used the bundle, even though it's a bit outdated and I didn't need mod_perl1 obviously, as I was already using mod_perl2. I had also installed libprereq in the steps above, so didn't need to install Apache::Request. You can decide which way you want to go.

In any case, using CPAN or the new cpanm to install the required modules, or the bundle, should get you 90% of the way to having Bricolage installed and running on your Mac or Hackintosh.

Installing Bricolage

Now you have two ways to go here. You can either download a distribution or get the latest source via Github. If you're going to do any development on Bricolage itself (patches greatly welcome!), you'll want to go the Github route. If you just want to get it running and/or don't have Git installed, you can skip some of these steps by downloading a distribution. Here's how I did it:

Cloned the public git repository with 'git clone git://github.com/bricoleurs/bricolage.git' and entered the 'bricolage' directory and ran 'perl Makefile.PL'.

If you're using the git source, you'll need to run 'make dist' to create a distribution from the source and enter the distribution directory that was created. From there, things are the same regardless of how you got the source.

Run 'make', 'sudo make test & make install' and answer the questions that the installer asks. If you followed the steps above, most of the questions should have sensible / usable defaults suggested and you can just accept them. I answered 'no' for SSL, as I wasn't planning to use it.

If successful, you should see the following:

Bricolage Installation Complete

You may now start your Bricolage server with the command (as root):

/usr/local/bricolage/bin/bric_apachectl start

If this command fails, look in your error log for more information:

/usr/local/bricolage/log/error_log

Once your server is started, open a web browser and enter the URL for your server:

http://your-local-host-name:8080

Login in as "admin" with the default password "change me now!". Your first action should be changing this password. Click "Logged in as Bricolage Administrator" in the top right corner of the browser window and change the password.

Pointers for documentation and lots of getting started advice are in the main README file in the unpacked distribution directory.

Open a browser, navigate to the URL provided and you should see the Bricolage log-in screen.

If you want to do some Bricolage hacking, you'll also want to run 'make dev' with the proper options from your source directory to link up the /usr/local/bricolage files to your git-managed files. (More on that shortly.) Ignore this for now. I'll do a separate post about it. Update: Here's the post.

Questions

So, after all that, I must task myself with cleaning up the installation documentation. However, before I do, my questions are:

1. I think most of this should simply be in README.MacOSX file and not in a separate Wiki page, or elsewhere. Sensible?

2. Should information still be provided on how to install Bricolage using the OS X-supplied version of Apache 2? Given the curious way that OS X lays out the various configuration files and how easy it is to install a /usr/local/ version, I don't see many advantages of supporting this approach -- do you?

3. Now that Bricolage supports Apache2 and modperl2, should the instructions still provide information on installing Apache 1.3 and modperl1? In the past, the Bricolage team has made a Herculean effort at providing information on almost any supported configuration, but I wonder if it would make sense to provide more detailed and regularly updated information on a "recommended configuration" vs. every possible configuration. Thoughts? My own thinking is -- given how painless it was to install with the more recent releases of Apache and mod_perl -- that the README.MacOSX should present the path of least resistance, and we can have supplemental pages in the wiki for other configurations.

Pending answers to the above, the next steps are to:

• Update the README.MacOSX to provide the most pain-free path possible
• Replace the "Installing Bricolage on Mac OS X" wiki page with a pointer to the above README
• Move alternate installation methods to a separate wiki page that can be appended as folks work through those configurations

If you've read this far, you must have something to say! So drop a note in the comments below or follow me on Twitter here.