Recently in Web Management Category

Bricolage Configuration Directives

In my previous article, I provided a guided tour of the Bricolage installation process. If you followed along, you should now have a nice, functioning installation of Bricolage 1.8 all ready to go. But as Mr. Popeil used to say, "But wait, there's more!"

Like many other applications, Bricolage comes with a runtime configuration file. This file, named bricolage.conf, lives in the conf subdirectory of your Bricolage root. It contains a list of settings that tell Bricolage how to find things, how to connect to the database, which optional features to include, and other good stuff. This article provides a guided tour of all of the configuration settings in bricolage.conf to enable you to configure things exactly the way you need them, so that you can manage your sites more effectively with Bricolage.

Configuration Format

The format of bricolage.conf, derived from the Perl Cookbook, is quite simple. A directive appears on a single line, followed by a space, an equal sign, and then the value. Anything after a pound sign (#) is a comment. Typical entries look like this:

APACHE_BIN   = /usr/local/apache/bin/httpd
APACHE_CONF  = /usr/local/bricolage/conf/httpd.conf
SSL_PORT     = 443

Most bricolage.conf configuration options are one of two types: Boolean values or strings. A Boolean configuration directive can be either enabled or disabled, but you have several ways in which to do so. To enable a Boolean directive, simply set its value to Yes, On, or 1 (the number one). To disable it, set it to No, Off, or 0 (zero). String values follow the equal sign. They can be as long as necessary, but cannot break across lines.

Apache Configuration

The first section of bricolage.conf configures Bricolage to use the Apache web server. Because Bricolage runs on top of Apache but uses its own startup scripts, it needs to know where to find Apache resources so that it can configure and start Apache properly. Bricolage's default method of dynamically configuring Apache therefore relies on these directives. The installation sets many of them for you, but not all, so it's worth it to have a look to see if you need to tweak any of them:


This directive tells Bricolage where to find your Apache httpd executable, which it uses to start itself up.


This directive points to the httpd.conf file. This, of course, is the famous Apache configuration file. It, too, needs configuration to run Bricolage (the Bricolage installer configures the default httpd.conf in the conf subdirectory of your Bricolage root directory), and Bricolage, in turn, uses this directive to tell httpd where to find the configuration file when it starts up.


This is the TCP/IP port on which Bricolage will listen for requests. It uses the HTTP standard port 80 by default, but you can change Bricolage to use another port if you already have another server listening on port 80.


This is the TCP/IP port on which Bricolage will listen for secure sockets layer (SSL) requests. It defaults to the standard HTTP SSL port 443, but again, you can change it to another port if something else is already using port 443. SSL is disabled by default, however, so read on for details on how to turn it on.


This directive turns on SSL support. You must have either mod_ssl or Apache-SSL installed and properly configured in your Apache server. Not quite a Boolean configuration directive, the possible values for SSL_ENABEL are No (or Off or 0 [zero]), mod_ssl, or apache-ssl. SSL is a useful feature for keeping communications encrypted between the server and users' browsers.


By default, an SSL-enabled Bricolage installation uses SSL only for logging in to Bricolage and in the user profile (where users can change their passwords). Users can elect to encrypt all communications by checking the Always use SSL checkbox when logging in, but some security policies may require the encryption of all communications. In such cases, enable this Boolean directive to force the encryption of all communications between the Bricolage server and users' browsers.


These directives specify the location of your SSL keys. If you've configured mod_ssl or Apache-SSL, you should already be familiar with these files. They help to encrypt and decrypt requests between the server and the browser. If you use make certificate to generate your SSL certificate during the Apache build process, by default your server key file will be server.key in the conf/ssl.key subdirectory of your Apache root directory, while the server public key file will be server.crt and in the conf/ssl.crt subdirectory. Bricolage uses these directives to set the Apache SSLCertificateKeyFile and SSLCertificateFile directives, respectively, in its dynamic configuration of Apache.


This directive roughly corresponds to the Apache httpd.conf NameVirtualHost directive. Set it to the IP address on which the Bricolage Apache server will listen for requests. If you have only one IP address on your server, the simplest thing to do is to leave this directive set to *, which applies to all IP addresses. Again, Bricolage uses this directive in its dynamic configuration of Apache.


This is the virtual host name under which to run Bricolage. Bricolage requires a full host or virtual host to run and will use this directive to configure the virtual host dynamically. Leave it set to _default_ to use the default host name set in your httpd.conf file.


Bricolage uses Apache::ReadConfig to configure the httpd daemon. There is no httpd.conf include file. If you want to take control of your Bricolage Apache server by manually configuring it, enable this Boolean directive. It will generate a file, bric_httpd.conf, in the bricolage subdirectory of your temporary directory (see the TEMP_DIR directive for the location of the temporary directory). This file will contain all of the Apache configuration directives that Bricolage uses to configure Apache dynamically. Restarting Bricolage will rewrite this file, but if you want to use it and edit it manually, copy it to the conf subdirectory of your Bricolage root directory, disable the MANUAL_APACHE directive, and then change the section of the httpd.conf file that configures Bricolage from:

PerlModule Bric::App::ApacheConfig


Include /usr/local/bricolage/conf/bric_httpd.conf
PerlModule Bric::App::ApacheStartup

Here /usr/local/bricolage/conf/bric_httpd.conf is the full path name to the newly generated bric_httpd.conf file. You can now tweak this file to your heart's content. Just be sure to generate a new one after each upgrade of Bricolage, as certain directives may change between releases.


These directives configure the system user and group used by Bricolage. They should contain the same value as the User and Group httpd.conf directives, usually nobody or www. Any files written to the file system by Bricolage will be owned by this user and group.

Database Configuration

The next major section of the Bricolage configuration file configures the database. Bricolage uses PostgreSQL 7.3 or later for its data store. Connecting to that database requires several attributes, not least of which are the username and password. These are all set during installation, but it's worth being familiar with them in case things change down the line.


The name of the database that stores Bricolage's data. The installer will set this for you. The default value, bric, works well in most situations, but it might be set to a different name if you entered one during installation, perhaps because you already had another database named bric; Why would you want to do that? Perhaps you have multiple Bricolage installations on the same host. Another reason it might be different is that your ISP provides you with a single database that they name according to their own naming conventions. At any rate, you're unlikely to need to change the value of this directive.


The username that Bricolage will use when connecting to the database. Again, you are unlikely to need to change this directive, especially because, when Bricolage creates the database, it specifically assigns permissions for this user to access the appropriate tables, sequences, and such. Note that, for security reasons, you should never use the PostgreSQL superuser for this directive.


The password for the DB_USER to use to connect to the PostgreSQL database. You'll need to change this directive if the password ever changes in the database. Depending on your PostgreSQL server's security model, it might not matter what the password is. For example, if the PostgreSQL is on the same host as your Bricolage server and trusts local users (the default configuration), it will ignore the password. Consult your PostgreSQL authentication settings (in the server's pg_hba.conf file) or check with your PostgreSQL DBA if you have questions.


This is the host name of your PostgreSQL server. If it's on the same host as your Bricolage server, it will likely be commented out, thereby letting Bricolage default to localhost. Otherwise, it will be a different host name or IP address. Change this setting if ever your PostgreSQL server moves to a different host or has its host name or IP address changed.


The TCP/IP port on which your PostgreSQL server listens for connections. This directive will be commented out if you've installed PostgreSQL locally and you're using Unix sockets instead of TCP/IP for its connectivity (a good idea for security-conscious environments). It will also be commented out if Bricolage should use the default PostgreSQL port of 5432. Otherwise, if Bricolage must connect to the PostgreSQL server via TCP/IP on a port other than 5432, set this directive to the appropriate port number.

Directory Settings

Bricolage stores a lot of files on your server's file system, generally in well-named directories below your Bricolage root directory. Sometimes you may want them installed elsewhere, perhaps for the purposes of conserving disk space or distributing I/O between different partitions. If you want to move any of these directories to a location other than that set by the installer, copy over any existing files to ensure that Bricolage continues to operate correctly.


Bricolage creates several temporary files as it runs, for its cache, user sessions, and the like. If you selected the multi option when installing Bricolage, this directive will point to a directory named tmp under your Bricolage root. Otherwise, it will point to your system's global tmp directory.


The Bricolage UI uses HTML::Mason. All of the components to power the UI live in this directory, generally a subdirectory of your Bricolage root named comp. However, media files uploaded to Bricolage also go in this directory, which means that it can become quite large if you manage a lot of media documents. It might be useful, therefore, to move this directory to a separate partition.


Mason compiles the Bricolage UI components into object files and stores them in this directory. For the most part you don't need to worry about where these files live (the default is the data directory under the Bricolage root directory), although Bricolage will read from it quite a lot as it loads the object files into memory, so disk I/O is important. It's unlikely to grow too except...


This directive tells Bricolage where to store formatting templates, object files, and burned files that are ready for distribution. As such, it can also grow quite large, especially if you've published or previewed a lot of documents. Bricolage never deletes these files so that you always have a canonical directory of the distribution files output by Bricolage. However, the default location for the BURN_ROOT is under the directory specified by the MASON_DATA_ROOT directive. If you encounter disk space problems, you might want to move this directory to another partition.

XML::Writer Configuration

The Bricolage Mason burner is responsible for pushing documents through Mason formatting templates. If you're writing templates that output XML (and I'll demonstrate writing templates in a later article, so hang in there!), you might want to simplify things by using an XML::Writer object to generate the XML. Bricolage simplifies things by providing these directives to create a globally available XML::Writer object for use in all Mason templates.


Enable this Boolean directive to tell Bricolage to create an XML::Writer object that's globally available as $writer to all Mason templates. Bricolage is smart enough to configure the XML::Writer object to output XML to Mason's buffer, so that you can even mix standard Mason output in your templates with XML::Writer output.


Use this directive to specify a list of options to pass to the XML::Writer constructor when INCLUDE_XML_WRITER is enabled. This directive is a string containing a Perl expression to pass to XML::Writer. The XML::Writer documentation has the full list of possible parameters. Common parameters include NEWLINES to trigger the output of new lines between XML elements, and DATA_INDENT to indent nested XML elements by a certain number of characters.

Authentication Configuration

Several configuration directives affect the behavior and security of the Bricolage authentication system. Bricolage handles its own authentication, storing passwords in the database as MD5-encrypted hashes and recording authentication in a browser cookie. In a security-conscious environment, it pays to be familiar with these directives and even to review their settings periodically.


This directive specifies the time-to-live, in seconds, for an authentication session. Each time an authenticated user sends a request to the server, the elapsed time resets to zero. You could therefore set AUTH_TTL to 3600 seconds for a one-hour time-to-live, and a user would be able to use Bricolage all day, as long as each request was less than an hour apart (but she might have to re-authenticate after lunch). This directive is especially useful in environments where users access Bricolage from public workstations and forget to log out. The default value of 28800 (eight hours) is probably too long in a production environment.


Bricolage stores the user authentication session locally and keys it off of an MD5 string stored in a browser cookie. The MD5 string comes from the browser's IP subnet, the expiration time, the user name, and the last access time. Because such a string is potentially replicable by someone trying to crack the system, Bricolage also uses a random string of characters to salt the MD5 string. AUTH_SECRET is the string used for this purpose. The installer generates it for you, but you might want to change it now and then, in order to keep it random and meet the specifications of your security policy. All users will need to re-authenticate after you change AUTH_SECRET and restart Bricolage.


This directive specifies a minimum user name length. Each user must have a user name of at least this number of characters. The default, 5, is generally adequate, and allows the default admin user name to work properly.


This directive corresponds to the LOGIN_LENGTH directive, but applies to passwords. The password length in Bricolage is unlimited, but it's generally a good idea to ensure that they all contain a minimum number of characters. The default is 5.

Distribution Configuration

When Bricolage previews or publishes documents, it pushes them through formatting templates (written in Mason, Template Toolkit, or HTML::Template) and writes the resulting files to disk. It then distributes those files to the appropriate servers specified in the destination manager in the user interface. (A later article will explain more of the Bricolage administrative interface.) Many run-time configuration directives affect the behavior of the Bricolage distribution server.


This Boolean directive enables Bricolage distribution. The only reason to disable distribution is if you set up a separate distribution server. To my knowledge, no one has actually done this, even though Bricolage supports it. The QUEUE_PUBLISH_JOBS directive is more popular to reduce Bricolage server overhead.


Bricolage distributes files via file system copy, FTP, SFTP, or WebDAV—depending on your destination configuration. We all know that failures can occasionally occur. Bricolage will attempt to distribute a file after a failed distribution and will do it multiple times. Set the DIST_ATTEMPTS directive to the number of times it should attempt to distribute a file before giving up.


This Boolean directive enables Bricolage's internal preview server. This is just a URI in the Bricolage UI that knows to serve previewed content rather than the UI. This is handy for evaluating Bricolage, but be sure to disable it in a production environment, especially if your front-end server needs to serve something other than static HTML. The recommended approach is to set up a separate preview server that is identical to your production server and configure a destination to distribute and redirect previews to that server.


With the PREVIEW_LOCAL directive enabled, if the content you're generating includes Mason calls, you can enable this boolean directive to make Bricolage's internal preview server evaluate the Mason code before serving documents.


This string directive identifies the default media type (also called a MIME type) of files for which Bricolage cannot determine the media type. The default value, text/html, covers a lot of typical files in a Web content management environment, such as .php or .jsp files. To add new types for Bricolage to recognize, use the media type manager in the UI.


By default, Bricolage does not support distribution via secure FTP (SFTP). If you need it, install the required Net::SFTP module, enable this directive, and restart Bricolage.


If you've enabled SFTP distribution, use this directive specify a home directory for SFTP to use, especially if you want to use public and private SSH keys. Consult the Net::SFTP documentation for details.


Enable this directive to prefer SSH2 support for SFTP distribution. You'll also need to install more Perl modules from CPAN. Consult the Net::SFTP documentation for details.


Net::SFTP uses the Net::SSH::Perl module to handle the SSH side of things. This module supports multiple encryption ciphers. If you prefer one, specify it via this directive.


Bricolage also supports distribution via WebDAV, a standard for distributing documents via the HTTP protocol. DAV, as it is also known, has support in multiple web servers including Microsoft's IIS and Apache 2. If you'd like to distribute document files to your production server or servers via DAV, install the HTTP::DAV module, enable this Boolean directive and restart Bricolage.


By default, when a user schedules a document to publish immediately, the Bricolage server will immediately execute the distribution. If users publish a lot of documents or you're bulk publishing large sections of your site at once, this can really slow down the Bricolage UI for other users. This is even true even if you've scheduled a bulk of documents to publish at a future date and time, because the way the default bric_dist_mon script works is to tickle the Bricolage server to distribute documents.

The way around this problem is to enable the QUEUE_PUBLISH_JOBS boolean directive and then use the bric_queued program instead of bric_dist_mon. With QUEUE_PUBLISH_JOBS enabled, the Bricolage server will never burn and distribute documents, even if a user schedules them to publish yesterday. Instead, bric_queued handles all of the burning and distribution itself, without having the Bricolage server expend resources on the task. With this approach, be sure to run bric_queued from a fairly aggressive cron job.


When Bricolage distributes files via FTP, it uploads them with a temporary file name, and then, when the transfer is complete, it renames the file to the final name. However, if an earlier version of the file is already present, the rename might fail. (This depends on your FTP server, but Microsoft's IIS is the server that led us to add this feature.) In such a case, enable this directive and Bricolage will delete any existing instance of the file before renaming the temporary file.

Alert Configuration

Bricolage has an interface for sending alert emails when it logs events that meet certain criteria against objects. Bricolage needs to know a few things before it can send the alerts.


Bricolage uses an SMTP server to send alert email messages. The default value for this directive, localhost, is fine if you use a Unix system with sendmail (or some other SMTP server) running locally. If your organization has a dedicated SMTP server or if your Bricolage host has none of its own, change the value of this directive.


Set this directive to an email address that you want to appear in the From header of alert emails. I typically set it to something like Bricolage Admin <>, but use whatever is appropriate for your organization. If your users are inclined to reply to alert emails, you may want to set up a special ALERT_FROM email address that has an auto-responder to let the user know that the reply will go unread.


This string directive indicates which header to use for specifying alert recipients in email alerts. The possible values are To and Bcc.

User Interface Configuration

Some configuration directives enable you to affect how the Bricolage user interface works in subtle ways. If you haven't used the Bricolage browser-based interface much yet, some of these won't make much sense just now. Feel free to come back and look again when you're you've had some experience with the Bricolage interface and want to make it behave more according to your own notions of correctness.


By default, when you search for objects in the Bricolage admin interfaces, or for stories, media, or templates in the asset library, the Bricolage UI appends a wildcard character to the end of your search string. Thus if you search for foo, the search will return results for all records that start with foo. If, however, you set the FULL_SEARCH Boolean directive to a true value, all searches in the Bricolage UI will become substring searches. So a search for foo will return all records where foo appears anywhere in a record.

The downside to this approach is that it prevents PostgreSQL from using its database indexes. In principal, this is only a problem if you have a large number of objects in Bricolage. If, say, you had 100,000 stories in Bricolage, you would notice that story searches would be noticeably slower with FULL_SEARCH enabled than with it disabled. Leave it disabled if you expect to manage a lot of documents. Your users can always manually prepend the wildcard character (%) to the front of search queries if they want a substring search.


Bricolage workflows are made up of a series of desks. In general, workflows have their own desks, but desks can appear in more than one workflow. In such a case, documents moved to such a shared desk in one workflow will be visible on the same desk in another workflow. This is great for managing common tasks across workflows, such as translation or legal review. The upshot is that, by default, a document placed on a desk in one workflow cannot be transferred from that desk to another desk in a different workflow. Users can only move it to other desks in the workflow in which it originated. Set the ALLOW_WORKFLOW_TRANSFER Boolean directive to a true value to remove this constraint, so that a document placed on a desk in one workflow can be moved from that desk to other desks in other workflows that the desk is in.


When managing multiple sites in Bricolage, the user interface will display a site context select list. Only the workflows for the selected site will be displayed. If you want to allow users to see all of the workflows for all of the sites that they have permission to access, set this Boolean directive to a true value to add an All Sites option to the Site context select list. But beware! If you have access to a lot of sites, you'll have access to a bewildering number of workflows when you select this option!


For the input of dates in Bricolage, the user interface offers select lists for the day, month, and year. By default, the years available in the Year select list have a limit of the ten years before and after the value for the year or the current year. If you need more years in your select list, set these directives to the number of years before and after the current value or current year. For example, if you manage a site of historical photographs with Bricolage, you might need to select years that range back over 100 years. In such a case, set YEAR_SPAN_BEFORE to 100. A science fiction book review site, on the other hand, might need years much farther in the future. For such a case, set YEAR_SPAN_AFTER to the appropriately high number.


The file names generated for story documents are set on a per-output channel basis. The user interface offers default values for these settings in the output channel profile. The default file name is index, and the default file name suffix is html. If, say, you were outputing content to an IIS server, you might want to set the DEFAULT_FILENAME directive to default and the DEFAULT_FILE_EXT directive to htm, instead. It's not a big deal either way, though, because you can actually set the values you need for each output in the user interface. These are just the displayed defaults, settable as directives for the ultimate in laziness.


Document models are associated with output channels in Bricolage. When you create a new document based on a model, it will automatically have the output channel associations defined by the model. If you'd like users to be able to change the associations—say, to assign output channels defined by the model to be optionally associated with documents based on that model—set this directive to a true value. If, however, the added complexity of output channel associations will only confuse your users, set this directive to a false value to remove the user interface for changing document output channel associations.


When editing a story document in Bricolage, you'll see a select list of all categories that you have READ permission to access to allow you to optionally add the story to a new category. Most of the time, however, you'll only add a story to one or two categories, and then never change these settings. Therefore, if you have a lot of categories in your Bricolage installation (and there are systems in production with over 2000 categories), it's wasteful to load them all every time you edit a story document when you'll never change them again.

In such a case, set the Boolean ENABLE_CATEGORY_BROWSER directive to a true value and restart Bricolage. This will change the story profile to offer a link to a category browser, which enables you to search for the category or categories to associate with a story. Now, not only will you no longer load all categories every time you access the story profile (and the story profile is, for content producers, the most commonly accessed page in the Bricolage UI), but you'll only load those you search for in the category browser. I highly recommend that every Bricolage admin to set this directive to a true value.

Document Management Configuration

These directives relate to how Bricolage manages documents.


Bricolage allows you to create relationships between documents. These can point to related stories or add images to a document, among other things. By default, when you publish a document, Bricolage will also try to publish any related documents. This will help to prevent 404s or broken image problems. In some cases, you might not want this behavior, so set the PUBLISH_RELATED_ASSETS Boolean directive to a false value.


Story documents in Bricolage must have unique URIs. URIs consist of a story's category and optionally other parts of the story, such as its cover date and its slug (a one-word description of a story). They do not, however, consist of the file name. This is in keeping with W3C suggestions. The idea is that the story has a directory URI, and there may be several forms of the story with different file names in that directory, such as index.html for HTML, rdf.xml for RDF, and index.pdf for PDFs.

However, some organizations have Website policies that demand the inclusion of file names in the URI. This is so that different documents can be in the same directory. A common example might be a About Us directory with separate /about/index.html, /about/contact.html, and /about/copyright.html documents. Such URIs are not possible by default in Bricolage, which requires that all stories have unique URIs, because each of these stories would have the same URI, namely /about. To get around this issue, set the STORY_URI_WITH_FILENAME Boolean directive to a true value. From then on, all stories will include their file names in their URIs. Be careful, though! Existing stories will not have their URIs changed. Decide how you want to set this directive when you start using Bricolage, and never change it.


The URIs for story documents are determined by patterns specified on a per-output channel basis. There are two different URI formats in each output channel, one for fixed documents and one for non-fixed documents. Non-fixed documents typically use parts of the cover date in their URIs, while fixed URIs do not. Each document model has a flag set to indicate whether documents based on the model will use the fixed for non-fixed URI patterns. The result is that, for non-fixed stories, you might have URIs like /reviews/books/2004/12/23/princess_bride. Here the URI format includes the slug, a one-word summary of the contents of a story (the princess_bride part of this example). However, slugs are optional in stories, even non-fixed stories. If you want to force all non-fixed stories to include the slug in order to guarantee the creation of more meaningful URIs, set this Boolean directive to a true value.


This Boolean directive complements the ALLOW_SLUGLESS_NONFIXED directive. If you want to keep the slug optional but generate one when a user neglects to type one in, set AUTOGENERATE_SLUG to a true value. This will cause Bricolage to generate a simple slug based on the title of the story. For example, a story with the title Essential Perl 6 would have the slug essential_perl_6 generated for it.

Apache::SizeLimit Configuration

Bricolage is a large application that includes many CPAN modules as well as its own 120,000+ lines of code. When you start it up, its processes can take up 30MB of memory or more. In general this isn't a problem, because Apache shares that memory between child processes. As each process handles requests, however, its size can swell independent of other processes. If you're performing resource intensive activities, such as publishing a lot of documents at once, the process that handles the request can become quite large. Because Perl (and, by extension, mod_perl) does not return memory to the system, this can give the appearance that you have a memory leak.

The solution to this problem is to use the Apache::SizeLimit module distributed with mod_perl to check your mod_perl processes periodically and kill them when they exceed a certain size. Bricolage has integrated support for Apache::SizeLimit that these directives can quickly enable and configure.


This Boolean directive turns on the Apache::SizeLimit support. After you set it to a true value and restart Bricolage, it will use the settings in the following directives to decide how often to check your processes and to kill them when they get to be too big.


This is the maximum size, in bytes, that processes can reach before Apache::SizeLimit will kill them.


This directive determines how often Apache::SizeLimit will check the size of your mod_perl processes. If you set it to 5, it will check a process after every fifth request handled by that process. The default is 1.


This directive indicates the minimum amount of shared memory the process must employ to avoid being considered a candidate for termination. Consult the Apache::SizeLimit documentation for more information. The default is 0, meaning that all Apache mod_perl processes will have their sizes checked.


This directive sets a limit on the amount of unshared memory a process may consume to not be a candidate for termination. You can use this directive to tweak your settings if you find that Apache::SizeLimit terminates processes while they are still mainly using shared memory. The default is 0.

Virtual FTP Server Configuration

Bricolage pushes story documents through formatting templates to generate output when you preview or publish them. Formatting templates can use Mason, Template Toolkit, or HTML::Template. If you have a lot of different types of story documents, or just elements of story documents, you'll likely end up with a lot of templates to manage. Editing templates in the browser interface's textarea fields can be a pain. A better approach is to use the Bricolage virtual FTP server, which provides access to all Bricolage templates via FTP. If the security of your password isn't a serious consideration (because FTP sends passwords in the clear, and maybe you work behind a firewall or over a virtual private network), enable the virtual FTP server and edit Bricolage templates from within your favorite FTP-enabled editor (Emacs, Vim, HomeSite, etc.). Here's how.


This boolean directive enables the virtual FTP server. Set it to a true value, tune the other FTP directives, reboot Bricolage, fire up the bric_ftpd application, and get to work! Just connect to your Bricolage FTP server on the port specified by the FTP_PORT directive, login with your Bricolage username and password, and you can browse templates by site, output channel, and category.


This directive specifies a TCP/IP port on which the Bricolage virtual FTP server will listen for connections. The default is 2121.


If your host has more than one IP address, specify one of them here to have the virtual FTP server to listen for connections on that IP address only. By default, the FTP server will listen on all of your host's IP addresses.


The location of the virtual FTP server log. By default, it will be in the log subdirectory of your Bricolage root directory.


Specify the location of the PID file for the Bricolage FTP server. bric_ftpd will use this file to record the PID of the server when you start it and to stop the server when you execute bric_ftpd -k. The default is to store the PID file in the log subdirectory of your Bricolage root directory.


As of Bricolage 1.8 and later, the Bricolage FTP server will save templates to your private sandbox when you upload them. This means that they will be checked out to you, appear in your personal workspace in the UI, and execute when you (and only you) preview stories that use them. To check in and deploy a template to use in production when other users preview and publish documents, simply append the string .deploy to the end of the file name when you upload it and Bricolage will do the rest.

Prior to version 1.8.0, the Bricolage virtual FTP server checked out, updated, checked in, and deployed templates on every upload. If for some reason you prefer this approach (and to be honest, I can't imagine why anyone would!), set the FTP_DEPLOY_ON_UPLOAD directive to a true value and restart bric_ftpd.


If for some reason the virtual FTP server isn't behaving the way you expect, set this Boolean directive to a true value and restart bric_ftpd. Then tail the FTP log (specified by the FTP_LOG directive) to diagnose the problem.

Preloading Configuration

Because Bricolage runs on Apache 1.3, the parent process loads all of its code at startup time, before it forks off any children. This is memory efficient, because most modern operating systems use a copy-on-write forking design. This means that the children all share memory with the parent until they write to that memory, at which time the kernel copies that memory to the child process.

When loading a lot of code, children never overwrite much of it. It's highly advantageous to load as much code as you think you'll need into the parent process at startup time, to prevent each of the children from loading it themselves and taking up that much more memory. These directives help you to do just that.


This string directive can be any Perl code you like, as long as it's all on one line in the bricolage.conf file. Bricolage will execute this code at startup time, in the namespace used by the Mason burner. This is very useful for loading Perl modules that your templates use, so that you're not loading them in each child process. The default value loads Apache::Util, which has many useful HTML output utility functions, and Bric::Util::Burner, which exports several constants that you can use in templates to tell what type of burn is being executed (preview or publish). Other common modules you might want to load here include or XML::RSS to assist with HTML and RSS output, respectively. You can load anything here, really.


Bricolage has localizations for multiple languages, including German, Portuguese, Italian, Cantonese, Mandarin, and Russian. The localization libraries are Perl modules loaded at server startup time. For the most efficient use of memory, load the languages you expect to use most often by specifying the appropriate language codes (such as en for English, pt_pt for Portuguese, de_de for German, etc.) in a space-delimited list via the LOAD_LANGUAGES directive.


This directive functions just like the LOAD_LANGUAGES directive, except that it loads the libraries that convert to and from UTF-8. Bricolage allows individual users to use different character sets when accessing the Bricolage UI, including ISO-8859-1, ISO-8859-2, Big5, ShiftJIS, GB-2312, and others. To save memory overhead, specify each character set that you expect your users will need to use day-to-day in Bricolage in a space-delimited list in the LOAD_CHAR_SETS directive.

Thumbnail Configuration

As of Bricolage 1.8.0, Bricolage can generate thumbnail versions of image files uploaded for media documents. All you need to do is install the Imager module from CPAN (along with the necessary libraries for the image formats you use—see the Imager README file for details) and configure thumbnail support via these directives.


Set this Boolean directive to a true value and restart Bricolage to have thumbnails generated for all image files in Bricolage. You must have Imager installed, of course. You might also want to consider installing media type icons specific to particular types of non-image files. See the README file and script in contrib/copy_gnome_icons in the Bricolage sources for information on which icon files to use and how to install them using the copy_gnome_icons script.


Set this directive to the maximum dimension of thumbnail images, in pixels. Bricolage will use this number to constrain the size of the thumbnail so that its greatest dimension does not exceed this number. For example, if THUMBNAIL_SIZE has its default value, 75, and you upload a 150 x 100 pixel image file, Bricolage will generate a 75 x 50 pixel thumbnail.

htmlArea Configuration

Bricolage 1.8.0 added support for WYSIWYG (what you see is what you get) editing via the htmlArea JavaScript editor, though it has this feature disabled by default. To enable it, download and install htmlArea 3.0 (in beta release as of this writing) in the comp/media/htmlarea directory under your Bricolage root. Then configure it via these directives and restart Bricolage. You will then be able to specify a WYSIWYG field type in document element definitions, and content editors can take advantage of htmlArea's WYSIWYG features when editing content in those fields.


Set this Boolean directive to a true value to enable Bricolage's htmlArea support. You must have htmlArea installed in the comp/media/htmlarea directory under your Bricolage root.


The htmlArea editor offers a lot of WYSIWYG features as controls (buttons) in its interface. The controls handle tasks such as copy, paste, italicize, boldface, link, etc. By default, Bricolage enables only a subset of these controls. The subset excludes layout type features such as font selection and color, line justification, and the like. The idea is to provide only the tools needed for users to easily add semantically meaningful markup rather than layout markup, so as to keep content independent of presentation. If you really need to allow your users to use six different type faces in twelve colors, you can enable the htmlArea controls for these features via the HTMLAREA_TOOLBAR directive. The value of the directive is a comma-separated list of single-quoted strings with brackets at either end. See the htmlArea documentation for a complete list of supported controls.

Up Next

Now you have all the information you need to configure how Bricolage operates to your heart's content. My next article will explore the nitty-gritty of defining document models in Bricolage.

Installing Bricolage

Now that Content Management with Bricolage has piqued your interest, you might be wondering what you need to do to install it. I'll be the first to admit that installing Bricolage is not trivial, given that it requires several third-party applications and modules to do its job. That said, the installer tries hard to identify what pieces you have and which ones you don't, to help you through the process. Even still, it can help to have a nice guide to step you through the process.

This article is here to help.

Packaging Systems

First off, depending on your operating system, you may be able to install Bricolage via the supported packaging system. If you run FreeBSD, you can install a recent version from the Free BSD ports collection. To do so, update your ports tree, and then:

% cd /usr/ports/www/bricolage
% make
% make install

A Debian package is also available. To install it, add these lines to your /etc/apt/sources.list file:

# bricolage
deb /
deb-src /

Then you can install Bricolage using apt-get:

# apt-get install bricolage-db
# apt-get install bricolage

The packaged distributions of Bricolage are great because they handle all of the dependencies for you, making installation extremely easy. The downside, however, is that there is frequently a lag behind a new release of Bricolage and the updating of the relevant packages. For example, the current stable release of Bricolage is 1.8.2, but the FreeBSD ports package is currently at 1.8.1. The Debian port is at 1.8.0. Furthermore, as of this writing, neither packaging system supports upgrading an existing installation of Bricolage, which may require database updates.

Building Bricolage

The alternative is to compile and install Bricolage and all of its dependencies yourself. This is not as difficult as it might at first sound, because Bricolage is a 100% Perl application and therefore requires no compilation. Many of the dependencies, however, do require compilation and have their own histories of successful installation on a given platform. For the most part, however, they have solid histories of success, and in the event of trouble, there are lots of resources for help on the Internet (see, for example, my articles on building Apache/mod_perl on Mac OS X). The platform-specific README files that come with Bricolage also contain useful information to help with your installation.

The next few sections of this article cover manual installation of Bricolage. If you're happy with a package install, this information can still be very useful for understanding Bricolage's requirements. If you're antsy, skip to the end to find out where to go next.


First: did you read the README file for your platform?

The most important prerequisites for Bricolage are:


What kind of article wouldn't have this requirement? Bricolage requires Perl 5.6.1 or later, but if you're going to work with any kind of non-ASCII characters in your content, I strongly recommend Perl 5.8.3 or later for its solid Unicode support. All text content managed by Bricolage is UTF-8, so for sites such as Radio Free Asia the newer versions of Perl are a must.

Experience has also shown that some vendor versions of Perl don't work too well. Red Hat's Perl, in particular, seems to have several problems that just go away once a sys-admin decides to compile her own. Caveat Perler.


Bricolage doesn't serve content, but it does require a web server to serve its interface. It requires Apache 1.3.12 or later, with a strong recommendation for the latest, 1.3.31. Bricolage does not yet support Apache 2, though the upcoming release of mod_perl 2 will lead to a port.


Speaking of mod_perl, Bricolage requires mod_perl 1.25 or later, with a strong recommendation to use the latest, 1.29. You can either statically compile mod_perl into Apache or, as of the recent release of Bricolage 1.8.2, compile it as a dynamically shared object library (DSO). However, in order to use mod_perl as a DSO, you must have compiled with a Perl that was configured with -Uusemymalloc or -Ubincompat5005. See this mod_perl FAQ for more details. Bricolage's installer will check this configuration against the Perl you use to run the installation and will complain if the installing Perl lacks these attributes. However, this check is only valid if the Perl running the installation is the same as the Perl used by mod_perl, so it pays to be aware of this issue.

As I said, Bricolage does not currently support mod_perl 2. However, now that mod_perl 2 is nearing release, there is greater interest in porting Bricolage to it (and therefore to Apache 2). Some work has begun in this area, and we hope to be able to announce mod_perl 2 support by the end of the year.


Bricolage stores all of its data in a PostgreSQL database. For those not familiar with PostgreSQL, it is an advanced, ACID-compliant, open-source object-relational database management system. I've found the compilation very easy on all platforms I've tried it on (although I have had to install libreadline on Mac OS X, first). Bricolage requires PostgreSQL 7.3 or later and recommends version 7.4. Bricolage will support the forthcoming PostgreSQL 8.0 around the time of its release, but to date no one has tested them together.

The one other recommendation I make is that you specify --no-locale or --locale=C when you initialize the PostgreSQL database. This is especially important if you will be managing content in more than one language, as it will prevent searches and sort ordering from being specific to one language and possibly incompatible with others. A Unicode and searching discussion on the pgsql-general mail list provides a broader perspective.

mod_ssl or apache-ssl

If you want encrypted communications between Bricolage and its clients, install either mod_ssl or apache-ssl. SSL is optional in Bricolage, but I recommend using it for security purposes. Bricolage can use SSL for all requests or just for authentication and password changing requests. Tune in for the next article in this series, Bricolage Runtime Configuration, for information on configuring SSL support.


Bricolage uses the XML::Parser Perl module, which in turn requires the Expat XML parser library. Most Unix systems have a version of Expat installed already, but if you need it, install it from the Expat home page.

CPAN Modules

Bricolage uses a very large number of CPAN modules. Most of those required in turn require still more modules. For the most part, we recommend that you let the Bricolage installer install the required modules. It will determine which modules you need and install them using the CPAN module. If you want to get ahead of the game, use the CPAN module to install them yourself, first. The easiest way to do it is to install Bundle::Bricolage. This module bundles up all of the required modules so that CPAN will install them for you:

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

There are also several optional modules. Install these all in one command by using the Bundle::BricolagePlus module:

% perl -MCPAN -e 'install Bundle::BricolagePlus'

Installing the Perl modules yourself can be useful if you expect to have trouble with one or more of them, as you can easily go back and manually install any troublesome modules. If you want to install them all yourself, without using the bundles, the INSTALL file has a complete list (copied from Bric::Admin). I don't recommend this approach, however; it will take you all night!

Note: Bricolage currently does not run on Windows. This situation will likely change soon, with the forthcoming introduction of PostgreSQL 8.0 with native Windows support as well as mod_perl 2. Watch the Bricolage web site for announcements in the coming months.


With all of the major dependencies worked out, it's time to install Bricolage. Download it from the Bricolage download page to the directory of your choice. Bricolage is distributed as a tarball like most Perl modules. Decompress it and then execute the usual Perl module commands to install it:

% wget
% tar zxvf bricolage-1.8.2.tar.gz
% cd bricolage-1.8.2
% perl Makefile.PL
% make
% make test
% make install

OK, to be fair, the process is actually more complicated than that, principally during make. Let's walk through the process.

Installation Configuration

The first step, perl Makefile.PL, doesn't really do what it does with your typical Perl modules. It's really just a wrapper around a custom Makefile to make sure that everything thereafter uses the Perl binary with which you executed Makefile.PL. If you're using an installation of Perl somewhere other than in your path, use it to execute Makefile.PL explicitly, such as /path/to/my/perl Makefile.PL.

The next step, make, will take the most time as the installer pauses to ask several questions. Let's take it step-by-step.

% make
/usr/bin/perl inst/

==> Probing Required Software <==

looking for PostgreSQL with version >= 7.3.0...
Found PostgreSQL's pg_config at '/usr/local/pgsql/bin/pg_config'.
Is this correct? [yes] 

The first thing the Bricolage installer does is to check for all of its dependencies. Here, it asks for the location of pg_config, the PostgreSQL configuration program. The installer will use this application to determine the version number of PostgreSQL, among other things. If you're using a package-installed version of PostgreSQL, make sure that you have the PostgreSQL development tools installed, as well (yes, I'm looking at you, Red Hat users!). Bricolage will look in several common locations for pg_config; if it doesn't find it, or if it finds the wrong one (because you have more than one installed), type in the location of pg_config. Otherwise, simply accept the one it has found.

Is this correct? [yes] [Return]
Found acceptable version of Postgres: 7.4.3.
Looking for Apache with version >= 1.3.12...
Found Apache server binary at '/usr/sbin/httpd'.
Is this correct? [yes] 

Next, the Bricolage installer searches for an instance of Apache 1.3.x. This time it's looking for the httpd executable. The same comments that applied to PostgreSQL apply to the Apache Web server; either accept the instance of httpd or type in an alternate. On my Mac, I never use Apple's Apache (an old habit because Apple's Apache uses a DSO mod_perl, whereas I always compile my own with a static mod_perl).

Is this correct? [yes] no
Enter path to Apache server binary [/usr/sbin/httpd] /usr/local/apache/bin/httpd
Are you sure you want to use '/usr/local/apache/bin/httpd'? [yes] [Return]
Found Apache executable at /usr/local/apache/bin/httpd.
Found acceptable version of Apache: 1.3.31.
Looking for expat...
Found expat at /usr/local/lib/

From here, the Bricolage installer continues looking for other dependencies, starting with the Expat XML parsing library. Then the installer probes for all of the required and optional Perl modules:

==> Finished Probing Required Software <==

/usr/bin/perl inst/

==> Probing Required Perl Modules <==

Looking for Storable...found.
Looking for Time::HiRes...found.
Looking for Unix::Syslog...found.
Looking for Net::Cmd...found.
Looking for Devel::Symdump...found.
Looking for DBI...found.
Checking that DBI version is >= 1.18... ok.

As I said, Bricolage requires quite a few Perl modules, so I'm truncating the list here for the sake of space. If any required modules are missing, the installer makes a note of it. If any optional modules are missing, it will prompt you to find out if you want to install them. Respond as appropriate.

Looking for HTML::Template...found.
Looking for HTML::Template::Expr...found.
Looking for Template...found.
Checking that Template version is >= 2.14... ok.
Looking for Encode...found.
Looking for Pod::Simple...found.
Looking for Test::Pod...found.
Checking that Test::Pod version is >= 0.95... ok.
Looking for Devel::Profiler... found.
Checking that Devel::Profiler version is >= 0.03... ok.
Looking for Apache::SizeLimit...found.
Looking for Net::FTPServer...found.
Looking for Net::SFTP...not found.
Do you want to install the optional module Net::SFTP? [no] [Return]
Looking for HTTP::DAV...not found.
Do you want to install the optional module HTTP::DAV? [no] [Return]
Looking for Text::Levenshtein...not found.
Do you want to install the optional module Text::Levenshtein? [no] yes
Looking for Crypt::SSLeay...found.
Looking for Imager...found.
Looking for Text::Aspell...not found.

Do you want to install the optional module Text::Aspell? [no] [Return]
Looking for XML::DOM...not found.
Do you want to install the optional module XML::DOM? [no] [Return]
Looking for CGI...found.

In this example, I've elected to install the Text::Levenshtein module, but no other optional modules not already installed.

Optional Perl Modules

Of course, if you previously installed Bundle::BricolagePlus from CPAN, you will have all of the optional modules installed. Let me provide a bit of background on each optional module so that you can decide for yourself which you need and which you don't. If you're just starting out with Bricolage, I recommend you don't worry too much about the optional modules; you can always add them if you decide that you need them later.

HTML::Template and HTML::Template::Expr

These two modules are necessary to create HTML::Template templates to format your content in Bricolage. Most Bricolage users use the required HTML::Mason module, but you should elect to install these modules if you're an HTML::Template user.

Template 2.14

Install the Perl Template Toolkit if you plan to write your content formatting templates in Template Toolkit rather than in Mason or HTML::Template.


The Encode module comes with and only works with Perl 5.8.0 and later. Install it you plan to support any character encodings other than UTF-8 in the Bricolage UI.

Pod::Simple and Test::Pod 0.95

These modules help to test the Bricolage API documentation, but are not otherwise necessary.

Devel::Profiler 0.03

This module can be useful if you experience performance problems with Bricolage and need to profile it to identify the bottleneck. You can always install it later if you need it.


This module is useful for busy Bricolage installations. Because Perl does not return memory to the operating system when it has finished with it, the Apache/mod_perl processes can sometimes get quite large. This is especially true if you use the SOAP interface to import or publish a lot of documents. Apache::SizeLimit allows you to configure mod_perl to kill off its processes when they exceed a certain size, thus returning the memory to the OS. This is the best way to keep the size of Bricolage under control in a busy environment.


This module is necessary to use the Bricolage virtual FTP server. The virtual FTP server makes it easy to edit Bricolage templates via FTP. It's a very nice feature when you're doing a lot of template development work, offering a more integrated interface for your favorite editor than the cut-and-paste approach of the UI. The downside is that FTP is an unencrypted protocol, so it sends passwords used to log in to the Bricolage virtual FTP server sent in the clear. This may not be so important if you're using Bricolage behind a firewall or on a VPN, and is irrelevant if you're not using SSL, because you're already sending passwords in the clear; but don't do that.

Net::SFTP 0.08

This module is necessary if you plan to distribute document files to your delivery server via secure FTP. Bricolage supports file system copying, FTP, secure FTP, and DAV distribution.


Install this module if you plan to distribute document files to your delivery server via DAV.


This module is an optional alternative to the required Text::Soundex module. Bricolage uses it to analyze field names and suggest alternatives for misspellings in the Super Bulk Edit interface. Either of these modules is fine, although many people consider Text::Levenshtein to have a superior algorithm. I'll show an example of how this works in the Super Bulk Edit interface in a later article.


Install this module if you plan to use SSL with Bricolage. It allows the SOAP clients to negotiate an encrypted connection to Bricolage.


This module is necessary if you plan to enable thumbnail images in Bricolage — why wouldn't you want that? You'll need to make sure that you first have all of the supporting libraries you need installed, such as libpng, libtiff, and libgif (or giflib). I'll discuss enabling thumbnail support in the next article.

Text::Aspell, XML::DOM, and CGI

These modules are necessary to use the spell-checking available with the optional HTMLArea module. I'll discuss HTMLArea support in the next article.

Back to Installation Configuration

After the Bricolage installer has determined which Perl module dependencies need to be satisfied, it moves on to checking the Apache dependencies, using the path to the httpd binary we provided earlier:

==> Finished Probing Required Perl Modules <==

/usr/bin/perl inst/

==> Probing Apache Configuration <==

Extracting configuration data from `/usr/local/apache/bin/httpd -V`.
Reading Apache conf file: /usr/local/apache/conf/httpd.conf.
Extracting static module list from `/usr/local/apache/bin/httpd -l`.
Your Apache supports loadable modules (DSOs).
Found Apache user: nobody
Found Apache group: nobody
Checking for required Apache modules...
All required modules found.

Your Apache configuration suggested the following defaults.  Press
[return] to confirm each item or type an alternative.  In most cases
the default should be correct.

Apache User:                     [nobody]

The most important settings relative to Apache are the Apache user, group, and port, as well as the domain name of your new Bricolage server. The Bricolage installer probes the default Apache httpd.conf file to select default values, so you can often accept these:

Apache User:                     [nobody] [Return]
Apache Group:                    [nobody] [Return]
Apache Port:                     [80] [Return]
Apache Server Name:              []

Here I've elected only to change the hostname for my Bricolage server. Because Bricolage requires its own hostname to run, I've just given it a meaningful name. Be sure to set up DNS as necessary to point to your Bricolage-specific domain name. You can also run Bricolage on alternate ports, which can be useful on a server running Bricolage in addition to an existing web server (see the Bricolage web site for more information on running Bricolage concurrent with another web server process).

Bricolage will also check to see if your Apache binary includes support for mod_ssl or Apache-SSL. If so, it will ask if you wish to use SSL support with Bricolage:

Do you want to use SSL? [no] yes
SSL certificate file location [/usr/local/apache/conf/ssl.crt/server.crt] [Return]
SSL certificate key file location [/usr/local/apache/conf/ssl.key/server.key] [Return]
Apache SSL Port:                 [443] [Return]

Here I've elected to use the default values. If your Apache server has both mod_ssl and Apache-SSL support, the installer will prompt to find out which you wish to use. The installer will pull the default SSL certificates from the Apache conf directory; type in alternatives if you want to use different certificates or if the installer couldn't find any.

Once it has all of the Apache configuration information in hand, the Bricolage installer moves on to gathering PostgreSQL information:

==> Finished Probing Apache Configuration <==

/usr/bin/perl inst/

==> Probing PostgreSQL Configuration <==

Extracting postgres include dir from /usr/local/pgsql/bin/pg_config.
Extracting postgres lib dir from /usr/local/pgsql/bin/pg_config.
Extracting postgres bin dir from /usr/local/pgsql/bin/pg_config.
Finding psql.
Finding PostgreSQL version.

In order to create the Bricolage database and populate it with default data, the installer needs access to the database server as the PostgreSQL administrative or Root user, usually postgres. Then it will ask you to pick names for the Bricolage database and PostgreSQL user, which it will create:

Postgres Root Username [postgres] [Return]
Postgres Root Password (leave empty for no password) [] [Return]
Postgres System Username [postgres] [Return]
Bricolage Postgres Username [bric] [Return]
Bricolage Postgres Password [NONE] password
Are you sure you want to use 'password'? [yes] [Return]
Bricolage Database Name [bric] [Return]

Here I've accepted the default value for the Postgres Root Username. I left the password empty because by default PostgreSQL allows local users to access the server without a username. Instances of PostgreSQL installed from a package may have other authentication rules; consult the documentation for your installation of PostgreSQL for details. The Postgres System Username is necessary only if you're running PostgreSQL on the same box as Bricolage. If so, then you'll need to type in the Unix username under which PostgreSQL runs (also usually postgres). If PostgreSQL is running on another box, enter root or some other real local username for this option.

You can give your Bricolage database and PostgreSQL user any names you like, but the defaults are typical. You must provide a password for the Bricolage PostgreSQL username (here I've entered password). Next, the Bricolage installer will prompt for the location of your PostgreSQL server:

Postgres Database Server Hostname (default is unset, i.e. local domain socket)
      [] [Return]
Postgres Database Server Port Number (default is local domain socket)
      [] [Return]

Here I've accepted the defaults, because I'm running PostgreSQL on the local box and on the default port. In fact, if you leave these two options to their empty defaults, Bricolage will use a Unix socket to communicate with the PostgreSQL server. This has the advantage of not only being faster than a TCP/IP connection, but it also allows you to turn off PostgreSQL's TCP/IP support if you worry about having another port open on your server. However, if PostgreSQL is running on a separate box, you must enter a host name or IP address. If it's running on a port other than the default port (5432), enter the appropriate port number.

Next, the Bricolage installer asks how you want to install its various parts:

==> Finished Probing PostgreSQL Configuration <==

/usr/bin/perl inst/

==> Gathering User Configuration <==


Bricolage comes with two sets of defaults.  You'll have the
opportunity to override these defaults but choosing wisely here will
probably save you the trouble.  Your choices are:

  s - "single"   one installation for the entire system

  m - "multi"    an installation that lives next to other installations
                 on the same machine

Your choice? [s] 

There are essentially two ways to install Bricolage: The first, single, assumes that you will only ever have a single instance of Bricolage installed on your server. In such a case, it will install all of the Perl modules into the appropriate Perl @INC directory like any other Perl module and the executables into the same bin directory as your instance of Perl (such as /usr/local/bin).

The second way to install Bricolage is with the multi option. This option allows you to have multiple versions of Bricolage installed on a single server. Even if you never intend to do this, I generally recommend taking this approach, because the upshot is that all of your Bricolage files (with the exception of the database, the location of which depends on your PostgreSQL configuration) will install into a single directory. This makes it very easy to keep track of where everything is.

Your choice? [s] m

Next, the Bricolage installer wants to know where to install Bricolage. The default option, /usr/local/bricolage, is the easiest, but you can put it anywhere you like. All of the other relevant directories will by default be subdirectories of this directory, but you can change them too. For example, you might prefer to have the error log file in the typical log directory for your OS, such as /var/log. Personally, I prefer to keep everything in one place.

Bricolage Root Directory [/usr/local/bricolage] [Return]
Temporary Directory [/usr/local/bricolage/tmp] [Return]
Perl Module Directory [/usr/local/bricolage/lib] [Return]
Executable Directory [/usr/local/bricolage/bin] [Return]
Man-Page Directory (! to skip) [/usr/local/bricolage/man] [Return]
Log Directory [/usr/local/bricolage/log] [Return]
PID File Location [/usr/local/bricolage/log/] [Return]
Mason Component Directory [/usr/local/bricolage/comp] [Return]
Mason Data Directory [/usr/local/bricolage/data] [Return]

If you elected for the single installation option, then your choices would look more like:

Bricolage Root Directory [/usr/local/bricolage] [Return]
Temporary Directory [/tmp] [Return]
Perl Module Directory [/usr/local/lib/perl5/site_perl/5.8.5] [Return]
Executable Directory [/usr/local/bin] [Return]
Man-Page Directory (! to skip) [/usr/local/man] [Return]
Log Directory [/usr/local/apache/logs/] [Return]
PID File Location [/usr/local/apache/logs/] [Return]
Mason Component Directory [/usr/local/bricolage/comp] [Return]
Mason Data Directory [/usr/local/bricolage/data] [Return]

Again, you can customize these as you like. That's it for the installation configuration!

==> Finished Gathering User Configuration <==


Bricolage Build Complete. You may now proceed to
"make cpan", which must be run as root, to install any
needed Perl modules; then to
"make test" to run some basic tests of the API; then to
"make install", which must be run as root.


Installing CPAN Modules

Whether you elected to install optional CPAN modules, the Bricolage installer still might have identified missing module dependencies, so it's a good idea to follow the helpful instructions and run make cpan. Of course, the cpan target will implicitly execute if you just moved on to make test, but it's a good idea to run it on its own to have more control over things and to identify any possible problems. My system had all of the dependencies satisfied already (I've done this once or twice before), but you'll recall that I had elected to install the optional Text::Leventshtein module. The Bricolage installer will therefore attempt to install it from CPAN.

% make cpan
/usr/bin/perl inst/
This process must (usually) be run as root.
Continue as non-root user? [yes] n
make: *** [cpan] Error 1

Whoops! Don't make the mistake I just made! make cpan must run as the root user.

% sudo make cpan 
/usr/bin/perl inst/

==> Installing Modules From CPAN <==

CPAN: Storable loaded ok
CPAN: LWP::UserAgent loaded ok


Found Text::Levenshtein.  Installing...
Running install for module Text::Levenshtein
Running make for J/JG/JGOLDBERG/Text-Levenshtein-0.05.tar.gz
Fetching with LWP:


Text::Levenshtein installed successfully.

==> Finished Installing Modules From CPAN <==

I've truncated the output here, but you should have the general idea. The Bricolage installer uses the Perl CPAN module to install any needed modules from CPAN. If you encounter any problems, you might need to stop and manually configure and install a module. If so, once you're ready to continue with the Bricolage installation, delete the modules.db file in order to force the installer to detect all modules again so that it notices that you now have the module installed:

% rm modules.db
% sudo make cpan

Running Tests

The next step in installing Bricolage is optional, but will help identify any pitfalls before going any further. That's running the test suite.

% make test                                    
PERL_DL_NONLAZY=1 /usr/bin/perl inst/
All tests successful, 7 subtests skipped.
Files=1, Tests=2510, 21 wallclock secs ( 8.83 cusr +  1.39 csys = 10.22 CPU)

Make it So!

Once all tests pass, you're ready to install Bricolage:

% sudo make install
/usr/bin/perl inst/
/usr/bin/perl inst/
All modules installed. No need to install from CPAN.
rm -f lib/Makefile
cd lib; /usr/bin/perl Makefile.PL; make install
==> Finished Copying Bricolage Files <==

If you happened to select a database name for Bricolage for a database that already exists, the installer will warn you about it:

/usr/bin/perl inst/

==> Creating Bricolage Database <==

Becoming postgres...
Creating database named bric...
Database named "bric" already exists.  Drop database? [no] 

Now you have a choice. If you elect to dropt the database, the Bricolage installer will drop it and then create a new copy — but it must have Root user access to the PostgreSQL server. In other situations you might want to continue with the installed database, as in the case when your ISP has created the database for you ahead of time. You will also receive a prompt if the PostgreSQL user for the Bricolage database already exists. Again, you can either opt to drop and recreate the user or continue with the existing username:

Database named "bric" already exists.  Drop database? [no] [Return]
Create tables in existing database? [yes] [Return]
Creating user named bric...
User named "bric" already exists. Continue with this user? [yes] [Return]
Loading Bricolage Database (this may take a few minutes). 

At this point, the Bricolage installer is creating the Bricolage database. On my Mac, it takes about a minute to create the database, but your mileage may vary. Once that ends, the installer grants the appropriate PostgreSQL permissions and the installation is complete!

Finishing database...
/usr/bin/perl inst/
Becoming postgres...
Granting privileges...
/usr/bin/perl inst/


                   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:


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

Login in as "admin" with the default password "change me now!". Your
first action should be changing this password. Navigate into the ADMIN ->
SYSTEM -> Users menu, search for the "admin" user, click the "Edit"
link, and change the password.


Start 'er Up and Login

That's it. Bricolage should start with the command helpfully provided by the installer:

% sudo /usr/local/bricolage/bin/bric_apachectl start
bric_apachectl start: starting httpd
bric_apachectl start: httpd started

If you set the Bricolage root directory to something other than /usr/local/bricolage, you'll need to set the $BRICOLAGE_CONF environment variable, first. For example, using Bash or Zsh, do:

% BRICOLAGE_ROOT=/opt/bricolage \
> sudo /opt/bricolage/bin/bric_apachectl start
bric_apachectl start: starting httpd
bric_apachectl start: httpd started

Once Bricolage successfully starts, point your browser to the appropriate URL and login as the admin user and change the password!

Up Next: Bricolage Runtime Configuration

Now that you have Bricolage up and running, you can start using it. Consult the documentation as directed in the README file to get started. Feel free to also subscribe to the Bricolage mail lists to ask any questions and to learn from the brave souls who have gone before you.

If you're interested in tuning your Bricolage installation, be sure to catch my next article, Bricolage Runtime Configuration, in which I'll cover all of the options when configuring Bricolage for added functionality and features.

Content Management with Bricolage

If you've ever had to manage a web site with tens of thousands of pages of content where many people need to be able to update that content, you've no doubt recognized the need for a content management system (CMS). Once you start to manage several such sites, the problem becomes even worse. Since you're reading this article on, I'm going to go out on a limb and guess that you're actually interested in Perl-based content management systems.

Well, you're in luck.

This article is the first in a series on introducing Bricolage, a Perl-powered, open-source, enterprise-class CMS currently in production for some of the most actively updated sites on the Internet today, including MacCentral, ETonline, and the World Health Organization. I start with a high-level overview (think executive summary) of the concept of content management, the nature of the content management ecosystem, and how Bricolage competes with other solutions in that ecosystem. Future articles will cover installation, document modeling, templating, and the Bricolage SOAP interface, among other topics. But first, the basics.

What is Content Management?

So much is made of the importance of web content management these days that the term, unfortunately, has been used to apply to just about any piece of software that somehow relates to the Web or to HTML. This trend has naturally eroded the meaning of the term content management. So I'm just going to punt on providing yet another definition, and focus instead on contrasting some of the categories of site-management software. In the process, I highlight where and how Bricolage fits into the CM ecosystem, and you get the benefit of determining what category of solution best fits your own content management needs.

Content Management vs. Community Building

First, there is the difference between content management systems and what I call community-building solutions, such as Slash and the various Nuke engines. These applications are ideal for setting up community-building and discussion sites, such as Slashdot,, or (my favorite) use Perl. The idea behind these solutions is to allow site users to register with the site and post comments about articles, content on other sites, or each other's comments.

True content management systems, on the other hand, are primarily designed to allow organizations to centrally manage and deliver content, such as articles, white papers, marketing materials, or what have you. The emphasis is not on discussion (and indeed, most content management systems -- including Bricolage -- don't offer discussion interfaces), but on assuring the consistency of content structure and formatting. Good examples of such systems include Bricolage, Plone, Vignette, and Interwoven TeamSite.

Application Framework vs. Turnkey Application

Next, there's the distinction between application frameworks and turnkey applications. Frameworks are not actual solutions, but provide the tools for you to create your own solutions. Anyone who has programmed in Java understands what a framework is; a content-management framework provides an array of tools and libraries that you can use (or pay high-priced consultants to use on your behalf) to create an application to meet your needs.

Many organizations have bought such frameworks, and in large, heterogeneous environments with six- and seven-figure budgets and years to implement a solution, it can make a lot of sense. Good examples of such frameworks are Vignette, TeamSite, and the Python-based Zope.

A turnkey application, on the other hand, is a complete application out of the box. It will still likely require a good deal of customization to implement a turnkey application-based solution in a complex environment, but we're typically talking weeks or, at the most, a few months. The downside to such a solution is that you're limited to the features that the developers of the application anticipated would be needed; only with open-source solutions do you have the possibility of adding your own. Fortunately, this category of content management is well represented in the open-source space, including such stalwarts as Bricolage, Plone (built on the Zope framework), and TYPO3.

Application Server vs. Document Management and Publishing

And finally, there is the difference between content management application servers and document management and publishing solutions. Application servers serve dual roles in life: they provide an interface for managing content, and they deliver that content to the final audience. This approach has advantages for some organizations, in that it requires only a single server, document updates are immediate, and you need deal with only one technology. Plone, Zope, and the various Wiki solutions for ad-hoc content management are typical content-management application servers. Blogging software tends to fall into this category, as well.

The downside to application servers is that, because they both manage and deliver content, your choice of delivery technology is limited to the technology choices of the software developers. With Plone, for example, you have to use Zope to serve content to the final audience. Furthermore, many of them provide templates for the output of content that limit how much you can customize the look and feel of your site. And finally, performance on a high-volume site can suffer, due to the overhead of the API and database, as well as the trickiness of distributing content across an array of application servers (think caching).

Document management and publishing systems, however, function entirely independent of delivery solutions. They focus on managing documents, moving them through workflow, ensuring the consistency of their structures, and publishing them to external systems for delivery to the end audience. Content is completely independent of presentation in these systems. Upon publication, they push content through templates to format it into one or more types of output (HTML, XML, RSS, Mason, PHP, etc.), and then distribute the resulting files to other servers (typically a web, file, or application server) for delivery to the final audience.

This separation allows the document management and publishing server to do what it does best, freeing up the delivery server to do what it does best: serve content. Bricolage is perhaps the best-known solution in this category. Another one is the recently introduced Krang, which is itself heavily based on Bricolage.

The downside to the document management and publishing systems is that, while you are free to use whatever delivery technology you wish (plain HTML, PHP, JSP, ASP, TT3, SSI, etc.), for security and scalability reasons the publishing server generally must run on its own hardware, independent of the delivery server. Furthermore, these solutions tend to have a broader set of features than their application-server cousins. Since they don't worry about serving content, they can provide other essentials such as document modeling, workflow, multi-site management, multiple output channels, etc. While such functionality increases the flexibility of the software, it can also increase the complexity of an implementation. The upshot is that the implementation of such a solution requires a good deal of forethought and planning.

Why Bricolage?

Now that you have a feel for where Bricolage fits into the content-management universe (see how it's grown beyond an "ecosystem" in the space of a few paragraphs?), let's take a look at why Bricolage is a good solution for the complex content-management needs of organizations with large volumes of content, many content contributors and editors, and/or multiple sites to manage. Essentially, this boils down to a brief overview of some of the more important features of Bricolage. Once you've read this section, you should have a good idea of whether Bricolage is right for your organization.

Browser-based Editing and Administration

Bricolage provides a complete browser-based interface. Designed to work with any standards-compliant graphical browser, you can handle nearly all configuration and administration tasks via the browser. All document editing can be carried out in the browser, as well. Content authors can create and edit content using up to four different interfaces, including separate fields for each block-level piece of content (paragraphs, headers, blockquotes, etc.), bulk editing of multiple fields at once, or WYSIWYG-style editing with htmlArea in Internet Explorer and Gecko-based browsers such as Mozilla and Firefox.

Document Modeling

The document-modeling features of Bricolage allow you to model the structure of your documents entirely via the browser-based interface. Once you've ascertained the different types of documents your organization needs to manage, and what their structures will be, you can model them in Bricolage. All documents created in Bricolage are based on such models, and as such, must adhere to the hierarchical definition of elements and fields that constitute their models. This approach assures the consistency of document structure.

Bricolage Element Profile

Bricolage's element-administration interface makes it easy to create new elements, add sub-elements, and create content fields.

Bricolage document models are built into a tree-like structure of elements and fields. Elements are the building blocks of content in Bricolage. They represent various parts of documents, such as pages; side bars; related media such as images, lists, related links; and the like. Every element can contain zero or more sub-elements, and together the hierarchy of elements make up the "branches" of the document model tree. Fields represent the "leaves", and are the containers into which content can be entered. Any kind of HTML field can be defined for use in the Bricolage UI, including text input fields, textarea fields, and select lists. Typical fields include "paragraphs," "headers," "list items," "teasers," and "URLs."

When an editor creates a document, it is based on a document model, and its structure must adhere to the model's element structure. Documents consist of a tree structure of elements, corresponding to the element structure of the document model, and in this way ensure the consistency of structure across documents. For more on Bricolage document modeling and elements, watch for the third article in this series, "Bricolage Document Modeling."

Separation of Content from Presentation

Since Bricolage document models are purely about structure, and a document's content will be stored in Bricolage in the same structured fashion as its model defines, no presentation information is generally included in a document. In other words, the content of a document is pure content, with little or no reference to formatting. Instead, it is a simple structural object representing the tree-like configuration of content elements.

The upside to this architecture is that highly structured content enables a virtually unlimited array of output options. The templates that format content can take advantage of the well-defined composition of a document model to grab the elements they need for the format they understand. Thus, a single document can be used to output a structured XML file, a set of HTML pages, an RSS feed, a PDF file, or whatever you require.

Done right, you get the Holy Grail of one canonical document and unlimited representations of that document. This capability is especially important in the fast-moving environment of the Internet, where new formatting standards are regularly introduced, demanding the creation of new templates to output existing content to satisfy the new standards.

Content Categorization

All Bricolage documents can be organized into one or more categories. These categories are hierarchical, and the hierarchies are used in part to create document URLs. This design allows you to store your documents in sensible locations on your web site, and provides them with legible URLs that search engines just love. Furthermore, it's easy to search for documents in a given category or set of categories using the Bricolage API, so that you can quickly create templates to generate category-specific directories of documents, such as RSS feeds.

Bricolage Category Manager

Bricolage allows you to create an unlimited number of hierarchical categories in which to file documents.

Meaningful URLs

In addition to categories, Bricolage document URLs can include the year, month, day of the month, and/or a slug — which is a short string describing the document, such as "bricolage-intro." Combined, these pieces of metadata generate meaningful URLs, such as /features/perl/2004/17/26/bricolage-intro for a Perl feature introducing Bricolage and published on 26 July 2004. Such URLs are very search-engine friendly, too, so they should greatly enhance your Google rankings, for example.


Bricolage documents can be associated with arbitrary keywords. These, too, can be queried via the Bricolage API, making keyword indexes a possibility. And of course, they're available in templates for outputting <meta> tags, Dublin Core Metadata, and the like.


Bricolage provides a workflow interface for managing your documents and templates. A workflow is a way to organize the process of creating a document. Typically, a document workflow defines areas of responsibility in the process of creating a document, such as writing, copy editing, legal review, and publishing. True to its original genesis among newspaper publishers, Bricolage workflows divide these responsibilities between desks. So one might have a workflow named "Document" for managing documents, with an "Edit Desk," a "Copy Desk," a "Legal Desk," and a "Publish Desk."

Bricolage Document Workflow

Bricolage workflows can be configured to reflect your organization's standard editorial processes.

You can create as many workflows as your organization requires, each with as many desks as you require. Desks can be shared across workflows — if you need certain parties to assume similar responsibilities in different workflows — and you can set up permissions such that certain users have access only to the documents in specific workflows and on specific desks. In short, you have a lot of flexibility to closely model the actual workflow in your organization, so that working with Bricolage is simply an extension of your users' standard editorial processes.

Output Channels

Output channels are collections of templates that output content in particular formats. Typical Bricolage solutions in production today have output channels for XHTML, RSS, WML, etc. Furthermore, output channels can include templates from other output channels. When Bricolage looks for a template, it looks in the output channel being published to, and then any output channels it includes. The search for the template resembles how Perl searches through the @INC array for a module. The upshot is that Bricolage makes it easy for you to create libraries of templates that can be used across output channels.

Bricolage templates correspond to document categories and elements, so that one element template outputs the content of a single element, or wraps the output of document-element templates for all documents in a category. Because a single element definition can be associated with different document models, this approach ensures the formatting of the content in elements based on that definition will be consistent across all documents.

Perl Templating

The templates in Bricolage output channels can be implemented in one of three templating architectures: Mason, Template Toolkit, or HTML::Template.

Yes, that's right, not only do you have three different choices for templating in Bricolage, but they're all Perl-based! In addition to being able to provide a familiar templating environment to tens of thousands of Perl programmers worldwide, the templating solutions can leverage the full power of Perl to generate output for your documents. That power of course includes CPAN, where you'll find modules to ease the generation of RSS feeds, HTML, XML, PDFs, or even Excel files!

Furthermore, Bricolage has a sub-classable templating architecture, which means that, with a little bit of work, you can add your own templating architecture. Anyone care to add support for Embperl, Apache::ASP, or XSLT?

For more on Bricolage templating, watch for the fourth article in this series, "Mason Templating in Bricolage."

Multi-site Management

More and more organizations are finding themselves managing more and more sites as part of their content-management responsibilities. As of version 1.8.0, Bricolage offers support for managing multiple sites from a single instance. Different sites can have their own categories, workflows (but share desks), output channels (but can include output channels from other sites), and distribution destinations. They can also share document models, so that different sites can manage the same types of documents but publish them with their own templates. This flexible multi-site management allows you to divide responsibilities appropriately while keeping all content centrally managed and accessible via a common interface.

Bricolage Site Profile

You can manage any number of different sites in Bricolage, each with its own documents, categories, templates, and workflows.

Document Aliasing

Once you have several departments in your organization managing their own sites, they might decide that they need to publish each other's content. Fortunately, if these sites are using the same document models, they can. Users with READ access to another site can create aliases to documents on that site. They can edit the title, URL, and keywords of the alias for the benefit of their own site, but the content remains in read-only form, so that editorial control remains in the hands of the originating site. Document aliasing thus provides a simple approach for sites to publish each other's content without violating one another's editorial integrity.

SOAP Interface

Bricolage features a robust and full-featured SOAP interface. The included bric_soap command-line client makes it easy to import and export documents, templates, and administrative objects, as well as bulk publish or update content. The ability to import content is especially important for organizations that wish to migrate their existing documents into Bricolage for management and publishing going forward. Watch for an article later in this series that highlights the flexibility and power of the Bricolage SOAP server.


Bricolage is designed to scale to the needs of the largest organizations. Its scalability manifests in three directions. Horizontal scalability is ensured by the ability to distribute the load between separate database, application, preview, and distribution servers. And remember, because Bricolage operates independent of the delivery of content to the final audience, your site's front-end servers can scale independently of Bricolage.

The browser-based interface provides Geographical scalability by allowing users to securely use Bricolage from anywhere in the world. Whether content editors are down the hall, across the country, or on the other side of the globe, if they have a browser and access to the Bricolage server's network, then they can be contributing content to your sites.

And finally, the Bricolage feature-set ensures organizational scalability, allowing for the centralized management of multiple sites, multiple types of documents, content categorization, and flexible templating across an organization and its sites. These features can be exercised as necessary as the needs of your organization evolve. In other words, Bricolage rapidly adapts to the changing requirements of your content-management environment.


Bricolage provides comprehensive security via encryption, user permissions, and its independence from your delivery servers. All communications with Bricolage can be encrypted over SSH/TLS to ensure secure use of the server from anywhere in the world. The same applies to the SOAP server, of course. At the access level, Bricolage provides a comprehensive permissions system to ensure that users get access only to the content and administrative objects relevant to getting their work done. And because Bricolage does not serve content to your final audience — it generally runs as a back-office application and often behind a secure firewall — your content library remains safe in Bricolage even if the security of your front-end servers becomes compromised.

Bricolage Permissions Administration

Bricolage offers a comprehensive permissions system to ensure users get access to only the objects they need to get their jobs done.


Bricolage's open-source licensing helps to ensure that it is fully buzzword compliant, in that you can achieve a much higher return on investment (ROI) than with competitive commercial systems. Furthermore, Bricolage runs exclusively open-source software, including Apache/mod_perl and the PostgreSQL RDBMS, so there are no hidden licensing costs, either. And finally, even organizations that decide to use <plug>professional consulting services</plug> for their Bricolage implementations find that the expense tends to be around half what it costs for the rollout of a commercial content-management solution.

Who Uses Bricolage?

Despite its genesis in the online news niche, Bricolage has managed it to go into production in a variety of settings. This success is a function of its broad feature-set, as well as the regard it has gained from the press. So who uses it?

And there are many other organizations quietly using Bricolage without publicly making that fact known.

Right for You?

If Bricolage sounds like a good fit for your organization's content-management needs, or if you're interested in how Bricolage really works, stay tuned to for my next article, "Bricolage Installation and Configuration," and we'll have you up and running in no time!


I'd like to thank Darren Duncan, James Duncan Davidson, and Rael Dornfest for providing valuable feedback on drafts of this article.

Visit the home of the Perl programming language:

Sponsored by

Powered by Movable Type 5.02