Bric::Admin - Bricolage System Administration Guide.


This guide is intended for the system administrator in charge of installing, configuring, or tuning a Bricolage system.

Quick Installation Instructions

For the really impatient you can just download a VMWare image with Bricolage already set up for you running under Ubuntu. See the announcement for more details.

There are lots of hints and tips for installation at the Bricolage Wiki, along with other tutorials and useful bits.

Don't forget to read the README for your OS first for known issues and helpful tips. These can be found in the root of the unpacked Bricolage tarball.

  1. Install Perl 5.8.0 or greater.

  2. Install Apache 1.3.34 or greater -- or Apache 2.0.55 or greater -- with mod_perl, mod_log_config, mod_mime, mod_alias.

    On Apache 2 you will also need to install mod_apreq and make sure that it and all the modules above appear in the list in the mods-enabled directory in your apache2 base directory. You will also need to use the prefork mpm rather than the threaded worker mpm in Apache 2.

    For SSL also install mod_ssl or (on Apache 1 only apache-ssl).

  3. Install PostgreSQL 8.1 or greater or MySQL 5.0.3 or greater.

  4. In the Bricolage source directory:

    perl Makefile.PL
    make test

    And then as root:

    make install

If you run into problems then read below for the details.

In order to prevent the Bricolage installer from asking any questions, simply set the environment variable $INSTALL_VERBOSITY to "QUIET":

make test

Bricolage will do its best to discover most information by itself, and exit with an error when it cannot. Default values will be selected from the appropriate defaults file for your system. See inst/defaults for a list of supported systems. inst/defaults/standard contains all of the default values, and other system-specific files can override those values.

Installation Variables

You can override many of those values during the install by passing the appropriate environment variables to make. The supported environment variables include:


Bricolage requires a lot of other components to be installed; here's a list of them:


Follow these instructions to prepare your system for Bricolage. If you're upgrading from an older version of Bricolage see the "UPGRADING" section below.


The standard Perl installation should apply with no problems. If your system comes with a package manager (ex. Redhat Linux RPM, FreeBSD ports, etc.) then you can use that to install Perl.

Here is how to install Perl from source:

OpenSSL (optional)

You'll need to install OpenSSL if you want to use Bricolage's SSL support to run a more secure server, otherwise you can skip this step. Installation of OpenSSL follows the usual conventions. Here's an example:

make install generally isn't necessary because the sources will be compiled into Apache, but may be necessary to generate your own test certificates or certificates to be signed by a public certificate authority.

Apache SSL Support (Optional)

You'll need to install mod_ssl or apache_ssl if you want to use Bricolage's SSL support to run a more secure server; otherwise you can skip this step.

Apache Interface to OpenSSL (mod_ssl)

Installation of mod_ssl follows the usual conventions. Here's an example:

make and make install aren't necessary because the sources will be compiled into Apache.


Apache/Perl (mod_perl)

Installation of mod_perl follows the usual conventions for installing Perl modules. It does require a number of Makefile.PL parameters, however. The most important parameter is APACHE_SRC, which points to the Apache sources. You will need to have already downloaded, gunzipped, and untarred the Apache sources before compiling mod_perl. Here's the routine:


Before continuing, consult the README.configure file that comes with the Apache distribution. It contains a very helpful (and short) bit of documentation and covers a lot of good information, particularly with respect to DSO use (a topic not covered here).

By now you've downloaded Apache and gunzipped and untarred its sources. There are a lot of Configure commands supported by Apache. We recommend that you use the following for Bricolage:


This option selects the classical Apache path layout.


This option prevents incompatibilities between Apache's implementation of the Expat XML parser, and that used by Perl's XML::Parser module.

--enable-module=ssl (optional)

If you're including SSL support via mod_ssl, this option compiles it in.


This option enables the mod_rewrite module that ships with the Apache sources. While mod_rewrite is not currently used in Bricolage, it may be in future versions.


This option compiles in mod_perl. The library it points to was installed by the mod_perl make process.


This option ensures that mod_perl will be statically compiled into Apache, rather than as a DSO.

And you're done! You can test the installation by calling

/usr/local/apache/bin/apachectl configtest


PostgreSQL is an integral part of Bricolage: it's where all of your assets are stored! Its installation is pretty straight-forward and typical, but it requires a number of extra steps that one might not expect.

If you're using Redhat Linux you may already have Postgres installed. If so, all you need to do to get it ready for use with Bricolage is edit your postgresql.conf file (run locate postgresql.conf to find it) and turn on the tcpip_socket option:

tcpip_socket = true

Otherwise, here are the installation details:

And now PostgreSQL is ready to go!

Perl Modules

There are quite a few Perl modules required by Bricolage (see "PACKAGES" above for a list). The easiest way to install them all is to let Bricolage's installation system handle it using the module (see below for details).

Another option is to use yourself to download the latest Bundle::Bricolage package and use it to install all the required packages:

perl -MCPAN -e 'install Bundle::Bricolage'

However, this is unlikely to succeed without manual intervention since some of the modules required by Bricolage have problems with

Finally, manual installation of each of the required modules follows the usual perl module installation process:


With the 1.4.0 release, Bricolage now can be installed using the new installation system.

If you run into a problem, the fastest way of getting help is to search the bricolage-general archive. Failing that, please send an email to the mailing list itself at Please make sure that you describe your problem as concisely as possible. Questions like "My installation fails, please help" will not help other users to help you. If other uses confirm that the problem you're experiencing is a bug and suggest that you send a bug report, file it via our bug tracker. Include a copy of all *.db files generated by the Makefile as well as a complete description of where the process failed. Then, either wait for us to fix the problem or try the manual installation instructions below.

If the installation procedure completes successfully you'll receive a message describing how to start the Bricolage server.

Bricolage (Manual Installation)

Here's how to install Bricolage manually.

htmlArea (Optional)

To install htmlArea, an optional application that offers WYSIWYG editing in the Bricolage UI, simply download it, decompress the files, and move them to the comp/media/wysiwyg/htmlarea directory in your Bricolage root.

As of 2005-03-25, there is a bug in htmlArea regarding form handling that requires a patch. After installing, apply the patch while in your Bricolage root: patch -p0 < inst/patches/xinha.diff

You will also need to enable the ENABLE_WYSIWYG and WYSIWYG_EDITOR bricolage.conf directives (see UI Configuration).

Xinha (Optional)

To install Xinha, an optional application that offers WYSIWYG editing in the Bricolage UI, simply download it, decompress the files, and move them to the comp/media/wysiwyg/xinha directory in your Bricolage root.

You will also need to enable the ENABLE_WYSIWYG and WYSIWYG_EDITOR bricolage.conf directives (see UI Configuration).

For Bricolage 2.0 you will need Xinha release 0.91beta or higher.

FCKeditor (Optional)

To install FCKeditor, an optional application that offers WYSIWYG editing in the Bricolage UI, simply download it, decompress the files, and move them to the comp/media/wysiwyg/fckeditor directory in your Bricolage root.

You will also need to enable the ENABLE_WYSIWYG and WYSIWYG_EDITOR bricolage.conf directives (see UI Configuration).

If you intend to use FCKeditor's SpellerPages support for spellchecking, you'll need to change two files in the FCKeditor source to get it to work with Bricolage. First in comp/media/wysiwyg/fckeditor/editor/dialog/fck_spellerpages/spellerpages/spellChecker.js, change this line:

this.spellCheckScript = 'server-scripts/spellchecker.php';

To this:

this.spellCheckScript = 'server-scripts/';

And second, in comp/media/wysiwyg/fckeditor/editor/dialog/fck_spellerpages/spellerpages/server-scripts/, you will likely need to change this line:

my $aspell_cmd = '"C:\Program Files\Aspell\bin\aspell.exe"';

To point to the correct loation of aspell:

my $aspell_cmd = '/usr/bin/aspell';

Execute which aspell on your system if you're not sure where aspell is. You will also need to modify a couple of lines from this file (although a patch has been submitted to the SpellerPages project, so it may be fixed by the time you read this). Change these lines:

print <<EOF;
Content-type: text/html; charset=utf-8


To these:

print header, <<EOF;

And finally, you might also need to make the file executable:

chmod +x comp/media/wysiwyg/fckeditor/editor/dialog/fck_spellerpages/spellerpages/server-scripts/

JS-Quicktags (Optional)

To install JS-Quicktags, an optional JavaScript libary that off buttons to make adding tags to text eadier in the Bricolage UI, simply download it, decompress the files, and move them to the comp/media/wysiwyg/js-quicktags directory in your Bricolage root.

You will also need to enable the ENABLE_WYSIWYG and WYSIWYG_EDITOR bricolage.conf directives (see UI Configuration).

GNU Aspell (Optional)

To use the spell-checking feature of htmlArea, the GNU Aspell library must be installed, along with the appropriate distionaries. These must be installed before the Text::Aspell module is installed from CPAN. Download GNU Aspell and the associated dictionaries.


If you're upgrading an installation of Bricolage that was previously installed via make install, then simply upgrade using make upgrade. If, however, you're upgrading an older installation of Bricolage that didn't have a build system, or it was simply used as-is from Git, you'll need to follow the directions below.

To upgrade a manual installation of Bricolage, first set the $BRICOLAGE_ROOT environment variable to the root of your Bricolage installation if it's something other than the default (/usr/local/bricolage), e.g.:

export BRICOLAGE_ROOT=/opt/bricolage

Next, stop the server:

$BRICOLAGE_ROOT/bin/bric_apachectl stop

Save copies of your bricolage.conf and httpd.conf files, so that you don't overwrite them:

cp $BRICOLAGE_ROOT/conf/bricolage.conf $BRICOLAGE_ROOT/conf/bricolage.conf.old
cp $BRICOLAGE_ROOT/conf/httpd.conf $BRICOLAGE_ROOT/conf/httpd.conf.old

Install the latest Bundle::Bricolage from CPAN to make sure that you have all the needed modules (or read through the list of required modules above and do it yourself).

Delete all existing Mason object files and temporary files:

rm -rf $BRICOLAGE_ROOT/data/obj/bric_ui/*
rm -rf /tmp/bricolage/*

Run the upgrade scripts needed for upgrading to the new version. The upgrade scripts are in the inst/upgrade/ directory. Run each script in all of the version number directories in the order given in inst/versions.txt. For example, to upgrade from 1.6.13 to 1.8.1, run each of the scripts in 1.6.13/, 1.7.5/, 1.6.14/, 1.8.0/, and 1.8.1/ -- in that order. Furthermore, the scripts within each directory are run in alphabetical order.

Next, copy in the new sources from the distribution into your Bricolage directory. Be sure not to copy example templates, as they may overwrite your own templates. You're best off moving the contents of data/ out of the way.

mv data /tmp/bric_data_tmp
cp -r /path/to/new/bricolage/* $BRICOLAGE_ROOT/
mv /tmp/bric_data_tmp data

Now edit the new bricolage.conf file to match your old settings using the bricolage.conf.old settings you saved as a guide. Do the same thing with httpd.conf. Don't just copy the old settings back into place -- there may be new configuration variables that you'll need to set for the new version. See the "CONFIGURATION" section below for details.

Now, start up Bricolage and enjoy the new features!

$BRICOLAGE_ROOT/bin/bric_apachectl start

Switching to Apache 2

As of version 2.0, Bricolage supports the Apache 2 Web server. If you'd like to upgrade your existing, Apache 1-powered Bricolage install to run on Apache 2, first install Apache 2, mod_perl 2, and Apache2::Request (apreq 2). Then, just run make upgrade as usual, but select "apache2" instead of "apache". Once the upgrade has finished, just execute these commands:

mv httpd.conf httpd.conf.orig
cp httpd.conf.def httpd.conf
mv bricolage.conf bricolage.conf.orig
cp bricolage.conf.def bricolage.conf

If you've customized your httpd.conf or bricolage.conf settings, you will likely have to edit the new files to sync up with your original settings. Once that's done, just start Bricolage and you'll be good to go on Apache 2.


Configuration of Bricolage is handled via two interfaces. The first is the user interface, where application administrators can set preferences such as Time Zone and Date Format. The second interface -- and the one of interest to us here -- is the Bricolage configuration file, which you'll find at /usr/local/bricolage/conf/bricolage.conf. This file is designed for system configuration, and thus to be edited by system administrators -- in other words, the audience of for this document.

The Bricolage configuration file contains a number of configuration options, each of which falls roughly into a number of categories, described below. Edit this document to tweak the functionality of Bricolage. The vast majority of configuration issues can be resolved by editing this document alone.

Note: Bricolage uses the BRICOLAGE_ROOT environment variable to determine where to find all of its libraries and configuration files. If this environment variable is not defined in the shell before starting Bricolage, Bricolage will default to '/usr/local/bricolage'. If you have installed Bricolage in any other location, you will need to set this environment variable before you start Bricolage or use any of its tools. The value of this environment variable is important for many of the configuration directives, as well. You will find it represented in this document as $BRICOLAGE_ROOT.

And now, on with the descriptions of the Bricolage configuration directives.

Apache Configuration

These settings relate the similarly-named Apache run-time configuration directives. (In fact, the descriptions here are largely cribbed from the Apache documentation.) Read the Apache documentation for more information on these and other Apache directives. Depending on your environment, changing some of these may help improve performance.

Note: These configuration settings are used directly in the Apache configuration file. Thus, advanced users can configure Apache themselves by editing the httpd.conf file directly. This is not recommended in most cases, however, as Bricolage uses Perl to configure Apache, and some of the configurations are used elsewhere, too. If you decide to edit the httpd.conf file yourself, however, be sure to also update the bricolage.conf file, so that the settings stay in sync.

Database Configuration

The database configuration directives tell Bricolage where to find its data, and how to get it. Specifically, you want to assign to these directives the values you passed to the -d and -m arguments of pgimport (see above).

System User Configuration

This is the name and group of the system user as whom Bricolage and Apache run.

Temp Directory Configuration

Mason Configuration

There are two parts to the Mason configuration. The first is for the Bricolage UI environment, and thus it needs to point to the Bricolage UI Mason elements. The second is for the Bricolage Publish environment, which is a separate environment from the Bricolage UI environment. The directives for the Publish environment will need to point to the directories where Bricolage Templates are stored.

Burner Configuration

Authentication Configuration

These directives set rules for Bricolage user authentication.

LDAP Configuration

These directives only need to be configured if you intend to use LDAP configuration with Bricolage, and have thus included "LDAP" in the list of authentication engines in the AUTH_ENGINES directive.

Note that if you use LDAP authentication, changing your password in Bricolage will not change your password in the LDAP server. If you're also using Internal authentication, the Bricolage password will be changed. But if you're not using Internal authentication with LDAP authentication, then no password will be changed at all.

Furthermore, when you use LDAP authentication, the users must already exist in Bricolage with the same unique username as in the LDAP database. When you login to Bricolage with LDAP support enabled, the user object is first instantiated by looking it up by username. Then the authentication is sent to the LDAP server. If a user exists in the LDAP server but not in Bricolage, she will not be able to authenticate.

You can further limit who can authenticate to Bricolage by adding their user DNs to a single LDAP group. See the LDAP_GROUP and LDAP_MEMBER_ATTR directives below for more information.

Distribution Configuration

These directives affect the how distribution is handled by Bricolage. There are two basic ways to handle distribution. The first, default approach is to let the Bricolage application server also handle distribution. In this case, the same Apache processes that handle the UI will also handle distribution responsibilities. The second approach is to set up a separate Apache server just to handle distribution. That server will need access to $BRICOLAGE_ROOT/stage in order to read the files there and distribute them elsewhere. Making $BRICOLAGE_ROOT/stage an NFS mount will do the trick.

UI Configuration

Media Configuration

UI Configuration

Language Configuration

Bricolage offers full support for editing documents in multiple languages and character sets. These directives can help Bricolage to be more efficient in its use of Language resources.

Time Zone Configuration

Alert Configuration

The Bricolage alerting system allows users to receive notifications upon the triggering of certain events within the system (see Bric::Util::AlertType and Bric::Util::Alert for the Alert API documentation). There are a few system-level directives that affect Bricolage Alerting.

Image Thumbnail Configuration

As of Bricolage 1.8.0, media documents based on an element with its associated element type set to "Image" can have associated thumbnail images. These thumbail images will then be displayed in the "Find Media" interface in the Bricolage UI. This is an optional feature. To use the thumbnail feature, the Imager module must be installed from CPAN, along with any requisite image libraries (libpng, libjpeg, libgif, etc.). Consult the Imager README file and documentation for details.

File Naming Configuration

All files burned to the file system during publishes and previews must be named (of course!), and they're named for the "File Name" and "File Extension" properties of the Output Channel they're getting burned to. You can give these properties whatever values you want (as long as they're legal on your file system!), but here you can set some defaults that all Output channels will start with.

Relateds POD Tag

Story URI configuration

Perl Loading Configuration

Virtual FTP Server Configuration

Bricolage includes a virtual FTP server that can be used to allow access to Bricolage templates. This may provide a more comfortable development environment for programmers working on templates. Many editors provide FTP modes that make editing files via FTP almost as easy as editing files locally (ange-ftp for Emacs, for example).

Whenever a user uploads a template via the FTP server, the template is checked out to her and put on her workspace and in her sandbox for testing. Repeated uploads of the template merely save it and redploy it to her sandbox. Once a user is satisfied that a template is ready for production and she wishes to deploy it, she merely has to upload it via the FTP server with the string ".deploy" appended to the file name. This behavior allows users to safely make changes to a template and test those changes without interfering with the publication of live documents until a user is sure a template is ready for production.

There are security risks to consider with the Bricolage virtual FTP server: FTP sends passwords unencrypted over the network. If you are running Bricolage behind a firewall this might not be a problem.

To enable the FTP server you'll need to install the Net::FTPServer Perl module. After that you can configure the FTP server with the following options:

Next you'll need to start the FTP server as the same user that Apache runs as. For example, if you run Apache as "nobody" you would use this command to start the FTP server:

su nobody -c "/usr/local/bricolage/bin/bric_ftpd -S"

The -S option to ftpd runs the FTP server in the background. For other possibilities see the documentation for Net::FTPServer.

Once the server is up and running connect to it with an FTP client and start editing templates. For more information see Bric::Util::FTP::Server.

Directory Permissions

As noted above, you need to supply the user and group names under which Bricolage will run. It's important that this user have permission to write to certain directories, as Bricolage will store some data files on the file system. So be sure to grant to SYS_USER and/or SYS_GROUP the necessary permissions to write to the directories identified by the MASON_DATA_ROOT, BURN_ROOT, and BURN_DATA_ROOT configuration directives. Also, Bricolage stores Media asset files in $BRICOLAGE_ROOT/data/media, so be sure the necessary permissions are set on that directory as well. If you're using the default configuration settings, then you'll only need to ensure that the following two directories are fully writable by SYS_USER, since the directives point either to one of these directories or to a subdirectory of these directories:


Installation Issues

The following addresses a number of installation issues you might face.

Building SSL Certificate

If you choose to create your own SSL certificate and act as your own certificate authority rather than use a known certificate authority such as VeriSign, it's possible that you'll run into issues getting the server to start up with the certificate properly. If so, you'll see errors in the Apache error log that look like this:

[Wed Jul  4 10:48:25 2001] [error] OpenSSL: error:14094412:SSL
routines:SSL3_READ_BYTES:sslv3 alert bad certificate [Hint: Subject CN in
certificate not server name or identical to CA!?]

This issue can be resolved by simply making sure that you enter different values for the "Organization Unit Name" for the certificate authority certificate and the server certificate.

If you're facing this issue, here's how to manually build a new certificate:

  1. Shut down Apache if it's running:

    /usr/local/bricolage/bin/bric_apachectl stop
  2. Delete the existing installation of Apache:

    rm -rf /usr/local/apache*
  3. Change directories into /usr/local/src/bricolage/apache_build/apache_1.3.xx.

  4. Execute the following command:

    make certificate TYPE=custom

    You will be prompted as you were during the initial installation. Follow the same instructions, but be sure to use different values for the "Organization Unit Name" in the two certificates. When you're prompted to encrypt the CA and Server keys, enter "n" to avoid having to enter a passphrase every time you start Apache, but enter "y" if you really don't trust your system users.

  5. Execute the following command:

    make install

    This will install Apache and the new certificate.

  6. Start Apache again:

    /usr/local/bricolage/bin/bric_apachectl start

System Administration

Bricolage is a big application, with big system needs. Thus it's a good idea to give some thought to system management, including disk partitioning and file maintenance.


By default, the Bricolage database is stored where all PostgreSQL databases are stored -- /usr/local/pgsql/data by default. Depending on the needs of your environment, the database can become quite large. We therefore recommend you place this directory on a separate partition. Better yet, place it on its own disk in order to optimize disk access time by preventing database access from competing with other disk processes.

A great deal more maintenance is important for the database. See Bric::DBA for more detail.


Bricolage stores all of its application files -- including the UI elements and Perl libraries -- in $BRICOLAGE_ROOT. Bricolage will make a lot of disk accesses to MASON_DATA_ROOT, which is where all of the UI elements are compiled and stored. The Perl libraries are stored in $BRICOLAGE_ROOT/lib, although mostly they will only be read on startup.

Bricolage creates a great many files on the filesystem, too, however. The $BURN_ROOT/comp directory houses the templates that are used to format stories - you'll want to be sure to back it up regularly. The $BURN_ROOT/stage and $BURN_ROOT/preview directories will get burned files written to them upon publish and preview, respectively. These will be good targets for periodic cleanup if you need to reclaim disk space, as generally the files stored there will not be much accessed after they're created. If you decide to clean some of them out to reclaim file space, just be sure not to delete any files for which there are executing distribution jobs, otherwise the distribution jobs will fail!

The $MASON_COMP_ROOT/data/preview directory gets formatted story files copied to it from $BURN_ROOT/preview if the PREVIEW_LOCAL directive is set to true. This directory doesn't need backing up, as these files are used only for previewing purposes.

The $BRICOLAGE_ROOT/comp/data/media directory gets all media asset files written to it. This last directory is perhaps the most important, from a system administration perspective, because if Bricolage is used to manage large documents (e.g., QuickTime movies), this directory will start to use a lot of space -- and especially if the media files themselves are versioned. Thus in environments where many large media assets will be managed, it might make sense to put this directory on its own partition or disk, as well. And remember to back it up to prevent the loss of all of your media assets -- they aren't stored anywhere else!

Bricolage also creates temporary files for caching user session data and application data. These files are stored in subdirectories of the directory specified by the TEMP_DIR configuration variable. Session files are stored in TEMP_DIR/bricolage/session and TEMP_DIR/bricolage/lock. These directories should stay relatively free of cruft, as the session files are regularly deleted when users logout or their login sessions expire and they attempt to log back in. (However, in some cases we've noticed a buildup of files in the lock directory.)

Bricolage also uses a cross-process caching mechanism to share data between Apache processes and applications. The data for this cache is stored in TEMP_DIR/bricolage/cache.

Bricolage comes with a script that cleans out old temporary files. You can use this by adding a line to the crontab for the web server user (often "nobody") like this:

0 2 * * * /usr/local/bricolage/bin/bric_clean_tmp

This will run nightly at 2AM and clean out all files older than 12 hours. See bric_clean_tmp for more details.

Cloing an Installation

Bricolage includes the ability to clone an existing Bricolage system. This is useful if you've developed a working Bricolage and need to copy the system into a production enviornment. Of course, you could setup a new, empty Bricolage and then use Bric::SOAP to copy over your templates, categories, elements and content, but that would still leave a lot of work left to do - users, preferences, distribution settings, workflow, etc.

Instead, you can clone an installation, which produces a distribution tar-ball that you can install on the destination server. This tar-ball includes all the contents of the Bricolage database, all files created by Bricolage and all configuration settings.

To clone an installation, first open up a fresh source distribution for the version that is installed. Then enter the source directory and type:

make clone

This will ask you for the BRICOLAGE_ROOT for the target install. It also asks you to name your clone. The name is used to generate the filename for the generated tar ball. When "make clone" completes it will leave a file create "bricolage-NAME.tar.gz", where NAME is the name you chose.

To install a cloned distribution, just take the generated tar-ball to the target machine and install it as usual:

tar zxvf bricolage-NAME.tar.gz
cd bricolage-NAME
make install

That's all there is to it! Now your new installation will be an exact replica of the original.

There is a make devclone option that does the same as 'make clone' but removes all of the locally previewed files, the obj files, staging and sandboxes. This means a large saving in download / install size of cloned high usage systems. Be warned that you will need to repreview assets like images, stylesheets etc as required.

Installation/Startup Problems

Some of the most common problems with Bricolage installation are discussed in Bric::FAQ which is distributed together with your Bricolage instllation. To see it, do perldoc lib/Bric/FAQ.pod in your Bricolage source or installation directory.

There is also an on-line copy.


David Wheeler <>

See Also