Bric::FAQ - Bricolage Frequently Asked Questions $LastChangedRevision$ $LastChangedDate: 2004-06-21 09:57:14 -0700 (Mon, 21 Jun 2004) $ This document tries to answer questions asked frequently on the mailing list or other questions that people might have when starting out with or evaluating Bricolage.

Evaluating Bricolage
This section answers questions that someone evaluating Bricolage might have. Does Bricolage support databases other than PostgreSQL? Currently only PostgreSQL support is maintained. There is an Oracle driver, but it's old and not known to work. A port to MySQL 4.1 is reportedly underway. Is there any pre-compiled packages for Bricolage? There is a FreeBSD port for Bricolage 1.8. To use it, simply update your ports tree, and then: cd /usr/ports/www/bricolage make make install There is currently only a tentative start for a bricolage debian package, and unfortunately, it is rather out of date. The location of the package is <http://people.debian.org/~erich/bricolage>. To use this package, add the following line to your /etc/apt/sources.list file: deb http://people.debian.org/~erich/bricolage / Then update your package database and install bricolage using "dselect" or standard "apt-get" commands. As of this writing, the package downloads and installs all necessary packages, but you still need to read through the instructions in /usr/share/doc/bricolage/README.Debian to setup a usable Bricolage installation. Please also note that the debian package may be out-of-sync with the standard distribution. Are there any Bricolage System that runs directly from CD? There is currently an effort to make a KNOPPIX-style CD for Bricolage. Informally this CD is known as KNOPPIX with Bricolage. It is a CD that contains a Linux Distribution (Debian in this case) with Bricolage preinstalled. The system is self-contained on a CD and the user merely needs to boot an i386-compatible computer from the CD. The CD will not in any way alter the content of your hard disk. This CD is useful for evaluating Bricolage since it removes the hassle of installation. Although it is certainly possible to transfer the Bricolage installation on the CD to your hard disk, we do not expect this to be the standard procedure to install Bricolage after evaluation. Rather, it is better to download the Bricolage sources from sourceforge.net and install it. The KNOPPIX with Bricolage CD is based on Erich Schubert's Debian package, and was created by Mark Jaroski as a demonstration of Bricolage. as Brico-Knoppix. The CD is available here: <http://www.geekhive.net/~mark/brico-knoppix-1.0.iso> How well does Bricolage perform? As far as we know, no one has performed any benchmarks comparing Bricolage to other content management systems. But the performance of Bricolage is irrelevant to a public facing site. As a back office content management and publishing system, Bricolage does not host web sites or serve content. Rather, when documents are published in Bricolage, they are pushed through templates and the resulting files are distributed to your Web server. So if your Bricolage templates output static HTML, your public Web server should serve your content very fast indeed since performanc depends entirely on the scalability of your Web server. Advantages of using Bricolage The separation of the content management and publishing server from the front end Web server is one of the major strength of Bricolage: It makes it easy add more capacity to your site to meet increasing demand: just add another Web server and configure Bricolage to distribute files to it. It improves security, as a compromise of the front-end Web server does not compromise your data, which is stored on in the Bricolage database server on the back end, possibly behind a firewall. The overhead of serving user requests can be kept at the minimum. In fact, unless you explicitly write code for your Web server to access Bricolage, no Bricolage code actually runs when serving pages. Other advantages of Bricolage include: Great flexibility for customization. Bricolage is designed from ground up to give site creators the ability to customize it to meet their needs. This is done by defining new element types, elements, templates and output channels. Great documentation and support. Check out <http://www.bricolage.cc/documentation.html>. Information on Mason can be found at <http://www.masonbook.com> and <http://.www.masonhq.org>. Open source. Bricolage is distributed under the modified BSD license. How does Bricolage compare to other content management systems? It has received praise for being as good as or better than commercial alternatives. For example, see <http://www.eweek.com/article2/0,3959,652977,00.asp> Who uses Bricolage? Some that we know of are: The PIRT Group - <http://thepirtgroup.com/> World Health Organization - <http://www.who.int/> Dimensional Fund Advisors - <http://dfafunds.com/> Macworld - <http://www.macworld.com/> MacCentral - <http://www.maccentral.com/> Kineticode - <http://www.kineticode.com/> Ad Council - <http://www.adcouncil.org/> Open Forum Europe - <http://www.openforumeurope.org/> The Lab School of Washington - <http://my.labschool.org/> Brain Mapping Unit, University of Cambridge - <http://www-bmu.psychiatry.cam.ac.uk/> Architectural Energy - <http://www.archenergy.com/> 2: The Magazine for Couples - <http://www.2magazine.com/> Performance Learning Systems - <http://www.plsweb.com/> Are there any commercial support offerings for Bricolage? Yes. Kineticode, founded by Bricolage maintainer and lead developer David Wheeler, offers a range of technical support and templating support options, as well as Bricolage consulting services. Learn more at <http://www.kineticode.com/services/>.

Installation
Why does mod_perl have to be statically compiled into Apache? I've been using mod_perl as a DSO and have had no problems with it at all. You are very fortunate, because mod_perl 1.x is just not too stable as a DSO. Weird things tend to happen. That's not to say that some haven't set it up as a DSO and just had it work, but we've seen all sorts of unexplainable problems just evaporate when users have switched from a DSO to a static mod_perl. And it's not Bricolage so much as Mason where the problems are noticed. The Mason site (<http://www.masonhq.com/>) has a couple of FAQs that mention the issue: <http://www.masonhq.com/docs/faq/#why_am_i_getting_segmentation_fa> <http://www.masonhq.com/docs/faq/#does_mason_leak_memory> You can also search the Mason Users list archives (<http://marc.theaimsgroup.com/?l=mason>) and the mod_perl Users list archives (<http://marc.theaimsgroup.com/?l=apache-modperl>) for some discussions of this issue.

Errors
This section contains questions about error messages output by Bricolage. If "make cpan" fails, what can I do? Bricolage depends heavily on CPAN modules. The purpose of "make cpan" is to verify that the required CPAN modules exist and, if not, fetch and install them from CPAN, whenever possible. In the worst case where it cannot handle the an error automatically, it gives instruction on how to do it manually. Usually, the instruction tell you to perl -MCPAN -e shell look package::module perl Makefile.PL make make test make install where "package::module" is the name of the file to look for. Sometimes, it will exit with a error without telling you what to do. Read the last few lines of the output. See which "package::module" caused the error. Then manually install the module using the procedure outlined above. If, when carrying out the procedures described above, "make test" fails, you might still want to go ahead with "make install" nonetheless. However, bear in mind that the module might not be installed properly. After this, rerun "make cpan". For an example, at this writing (2 August 2003), "Apache::ConfigFile" can cause a permission problem. "make cpan" will report a strings of cannot set uid=88nnnn, gid=nnnnn Read a few line before the error message to determine the actual location of the download file, it is usually something like /root/.cpan/sources/authors/id/N/NW/NWIGER/Apache-ConfigFile-0.14.gz. "cd" into the /root/.cpan/sources/authors/id/N/NW/NWIGER/ directory and untar the tar.gz file: tar -zxvf Apache-ConfigFile-0.14.tar.gz You will get the same error messages. Note, however, that untar is successful and the directory Apache-ConfigFile-0.14 is created. "cd" into this directory and run perl Makefile.PL make make test make install This should succeed. After this, rerun "make cpan" again. More information can be founded in <http://bugzilla.bricolage.cc/show_bug.cgi?id=435>. Sometimes, "make cpan" reports that a CPAN module is not found. This could be because it is trying to get an older version of the CPAN module which CPAN no longer hosts because your CPAN index file is out-of-date and needs to be refreshed. To refresh your CPAN index file, perl -MCPAN -e 'reload index' and repeat "make cpan". Sometimes you might need to update your CPAN bundle, itself: perl -MCPAN -e 'install Bundle::CPAN' Why does "make install" exit with the error 'Missing or empty inst/bricolage.sql!'? You checked Bricolage out from Subversion and didn't run "make dist". Do something like this: # make dist [lots of output...] # cd bricolage-1.5.0 # make install Why does "make install" exit with the error 'Unable to set bricolage.conf variable APACHE_BIN to "/usr/local/apache/bin/httpd"'? Most likely it's because you're installing Bricolage on Red Hat 8 or later and haven't got 'round to reading README.RedHat. In fact, a fair number of Perl modules will fail to install or test properly with Perl 5.8 on Red Hat 8. This is because Red Hat is configured such that it defaults to a Unicode character set. Bricolage prefers this, of course, since all Bricolage data is stored in the database in Unicode. However, it does require that you set the "LANG" environment variable on Red Hat 8, like this: export LANG=en_US From what we've heard, "LANG" must not include "utf8". Presumably you should set "LANG" to a value for your local language. At any rate, you'll need to make sure that this is set in your shell in order to install Bricolage and all of its modules, and you may need to include it in your httpd.conf file, as well: PerlSetEnv LANG en_US We've also heard that you can set the LANG environment variable globally in the /etc/sysconfig/i18n file. Then you wouldn't need to worry about it anywhere else. Why does "make install" exit with the error 'IDENT authentication failed for user "postgres"'? I'm not sure why the IDENT fails. In inst/db_grant.pl, we switch EUID to that of 'postgres'. Maybe more things need to be set in order to convince postgresql that you're logging in as 'postgres' instead of 'root'? I worked around the problem by ignoring it; in pg_hba.conf, #local all all ident sameuser #host all all 127.0.0.1 255.0.0.0 ident sameuser local all all trust host all all 127.0.0.1 255.0.0.0 trust host all all 0.0.0.0 0.0.0.0 reject A Short introduction to pg_hba.conf can be found in Bric::DBA, and it is more thoroughly documented at <http://www.postgresql.org/docs/current/interactive/client-authentication.html>. Why do I get a 404 when I connect to the Bricolage UI and get an error like the following in Apache's error_log? [error] [client 127.0.0.1] Error executing AccessHandler: Bric::App::Session -- /usr/local/lib/perl5/site_perl/5.8.0/Bric/App/Session.pm -- 236 Difficulties tie'ing the session hash to file '/tmp/bricolage/session' Most likely it is because one or more files or directories in your Bricolage temp directory are no longer writable by the Apache user. You need to "chown" the temp file directories and restart Bricolage: sudo chown -R nobody:nobody /tmp/bricolage sudo bric_apachectl restart When I try to login to Bricolage, I get redirected to /login, but the page is blank. There's nothing in the HTML source except "<html><head></head></html>" or nothing at all. There are no errors in the error log or the access log. What's wrong? I've seen this a couple of times, but the cause was different each time. On one occasion, there was a FilesMatch directive in a separate VirtualHost directive in httpd.conf that was preventing Mason from seeing any of the Bricolage UI components. The directive that caused the problem looked like this: <FilesMatch "\.mas"> SetHandler perl-script PerlHandler Bric::App::Handler </FilesMatch> I have no idea why this would have caused a problem, but when it was removed, Bricolage started working again. On another occasion, a user noticed that the files comp/login/dhandler and comp/login/welcome.html were empty. This caused the equivalent of a "Document Contains No Data" error, only it didn't. In fact, in my tests, under these circumstances, the browser had no HTML source at all (although I was later told that a Mozilla setting can force the "<html><head></head></html>" to be added). At any rate, the problem was fixed by reinstalling Bricolage (a "make upgrade" would probably do the trick, too), but it's likely that simply copying these two files from the Bricolage source directories to your installed component root will correct the problem. Holler on the bricolage-general mail list if it doesn't. When I try to login to Bricolage, I get redirected to /login, but the web server reported a "500 Internal Server Error". What's wrong? Look in your Apache error_log file. If you find an error along the lines of cannot login ... Then you need to update your pg_hba.conf file as described in the section "Why does "make install" exit with the following error?". In fact, as David Wheeler suggested in one of the email in the "bricolage-general" mailing list, if you issue the following command on the command line: /usr/local/pgsql/bin/pgsql -U bric bric you will get IDENT authentication failed for user "bric" Thus demonstrating that you're dealing with a PostgreSQL configuration issue, rather than a Bricolage issue. I'm trying to restore a backup of the Bricolage database, but I keep getting an error like this: "ERROR: Function login_avail(varchar, numeric, numeric) does not exist". What gives? This is a known issue with PostgreSQL's "pg_dump" utility -- it's not smart enough to handle circular dependencies. The PostgreSQL developers are aware of the issue. See this bug report for details: <http://archives.postgresql.org/pgsql-bugs/2002-09/msg00278.php>. In the meantime, the workaround is to edit your SQL dump file so that the Bricolage database will load properly. In your SQL dump file, search for and remove the line containing the string 'CONSTRAINT "ck_usr__login"'. This should remove the creation of the constraint that uses the "login_avail()" function before the function is created. Next, go to the very end of the SQL dump file and add these lines: ALTER TABLE usr ADD CONSTRAINT ck_usr__login CHECK (login_avail(LOWER(login), active, id)); This will add the constraint at the very end of the load, when both the "usr" table and the "login_avail()" function have been created. Now you should be able to load the database and get back to work! Why do I get the error 'Can't locate object method "" via package "HTML::Mason::Lexer"'? This is a bug with Perl. It is caused by the presence of Unicode in a Mason template, and dates from a period when Perl's regular expressions had some difficulty with Unicode. It was fixed in Perl 5.8.1. Upgrade to the latest version of Perl and you should be good to go. I keep clicking the "Click here to start" link on the very first Bricolage page I see, but it keeps just opening up a new window with "Click here to start" again. What gives? I'm going to go out on a limb here and guess that you're using Safari 1.1.1 or earlier on Mac OS X. Prior to the release of version 1.2, Safari has a JavaScript bug wherein it doesn't know the name of a window. The "Click here to start" link opens a new named window, but since Safari doesn't know that it's named, Bricolage's JavaScript can't tell that it's named, either, and so keeps trying to get you to open a window with the correct name. It'll never happen. Apple should be aware of this issue, as I've filed a bug report for it using Safari's bug reporting interface, and have reported it again via Apple's official bug database (Bug # 3485193). Until Apple fixes the bug, there are two ways to resolve this issue: First, don't use Safari. This is the preferred solution, and since there are some other great Browsers for Mac OS X (notably Camino, Firebird, and Mozilla), it's a real option for most Bricolage users. The second solution is to disable the named window by adding the undocumented configuration directive "NO_TOOLBAR" to your bricolage.conf file with a false value. The downside of this approach, however, is that all users of Bricolage will now be using Bricolage in a window with the back button, and this can potentially lead to problems with the state of story objects while you're editing them. However, if you never use the back button, it should be fine. Sometimes the left navigation doesn't render properly, and the interface for adding fields doesn't work at all. What gives? Most likely you're using Safari on Mac OS X to access the Bricolage interface. Unfortunately, that browser seems to have some bugs related to rendering layers. The only workaround is to use a different browser. I recommend Camino, Firebird, or Mozilla. Bricolage seems to be automatically changing my accented and other non-ASCII characters: when I enter element content with accented characters 'à's become 'Ã¨'s and similar things occur to other accented characters. What's going on? You need Perl 5.8.0 or later for Bricolage to properly handle non-ASCII characters. Also, PostgreSQL database for Bricolage must be using UNICODE encoding. Please see Bric::Admin for further information on recommended setup for letting Bricolage correctly handle non-ASCII content. Accented and other non-ASCII characters look right in Bricolage's internal preview, but not on my own preview server or my production server. What gives? You need to make sure that your non-Bricolage server or virtual host knows that it's server Unicode characters. If you're running an Apache server, just add this to your httpd.conf and restart: AddDefaultCharset utf-8 Consult the documentation for your Web server for more information. The Bricolage SOAP server segfaults when I try to use it. What gives? Apache inadvertantly compiled the wrong expat XML parser into itself. Rebuild Apache, this time using the "--disable-rule=EXPAT" option.

Element Administration
I added a field to an element and deleted it, and now I can't add a new field with the same name. Why not? Fields cannot have the same name, even if they've been deleted. This is because you might have older stories around that use the old name, and still republish them to templates that use the old name. The solution is to give the new version of the field a different name, but make the "Label" the same. So you might have a name like "new_paragraph" and the label "Paragraph". Just remember to change any references to the old field name in your templates to use the new field name. I created a new subelement type element but it does not appear in the list of elements for which I can choose to create a template. Where is it? Did you add it as a subelement to a document type element, or as a subelement to any element that's part of a document type element hierarchy? If not, it won't show up in the template select list. This behavior has to do with sites; only story type and media type elements are associated with sites, so to create a new template in a workflow (which is associated with a site), it looks for all the story type and media type elements associated with that site, and then adds all subelements of those elements. So unless your new subelement is associated with a story type or media type element, you won't see it when you go to create a new template.

Miscellaneous
This section contains questions that didn't fit in the other sections. What does "Bricolage" mean? Click on the Bricolage log in in the UI to see the "About" section of the online help. How did Bricolage get started? What is its history? [In the beginning there was chaos....] Where can I get more information? Read the README document in the directory where you unpacked Bricolage to learn about other documents on specific things like Bricolage administration, usage, or hacking. The project's web site is <http://www.bricolage.cc/>. The web site lists information about mailing lists. I can't get my head around the idea of workflow. Is there any documentation on it? Not really, no. We'll likely write some one of these days. in the meantime, you might find some use in a presentation given at the 2000 OSCON by Ian Kallen, in which he discussed what Salon needed out of a CMS (including workflow) and how he came to select the tools to use the CMS that was the proof-of-concept for Bricolage. The article is at <http://www.arachna.com/edu/talks/iswp/index.html>. Why do searches return only objects with fields that start with my query string, rather than containing the query string anywhere in the field? This behavior is intentional. The search interface goes directly into an SQL query, and thus support SQL wild card characters. Unless you query for a string at the beginning of a column, the index on that column won't be used. So we default to only searching at the beginning of a field in order to take advantage of the speed provided by an index. However, you can get around this functionality in two ways. You can by put a '%' in front of your search string, thereby forcing the SQL query to be a full substring query. Or you can enable on the "FULL_SEARCH" bricolage.conf directive and restart Bricolage. But know that either of these methods will a lot slower (though you probably won't notice much until you have 1000s of documents). Why can't I see all the stories I should see in Find Stories/Find Media/Find Templates ? What is your 'Filter search results by site context' preference set to? When this preference is set to 'On', Bricolage filters search results according to the Site context selected. Does Bricolage have a memory leak? No. Bricolage can use a lot of memory resources, especially if you publish a lot of documents at once, such as via the SOAP interface. Perl grabs the memory it needs, but it never releases it back to the operating system, although it will reuse it before asking the OS for more. So if you've published a lot of stories at once or done anything else to cause Bricolage to load a lot of data (such as used the search interface to get a list of all 10,000 stories in your Bricolage database), then the process that handled your request will become quite large and stay that way for its lifetime. There are a number of ways to address this issue: If you're using "bric_soap" to execute big SOAP requests, use its "--chunks" option whenever possible to cut down on the amount of work any one request is doing. Change your Apache configuration to get a better handle on your process sizes. Set "MaxSpareServers" and "MinSpareServers" to a reasonable numbers, and set "MaxRequestsPerChild" to limit the number of requests any one child handles. See the Apache documentation at <http://httpd.apache.org/docs/> for more information on these and related directives. Use Bricolage's support for Apache::SizeLimit. This support is enabled via the "CHECK_PROCESS_SIZE" bricolage.conf directives, and you can tune it using the "MAX_PROCESS_SIZE", "CHECK_FREQUENCY", "MIN_SHARE_SIZE", and "MAX_UNSHARED_SIZE" directives, as well. See Apache::Admin for details. If you are using any character sets besides UTF-8, specify these character sets with the "LOAD_CHAR_SETS" directives. This will make sure that the character sets you are using are pre-loaded during server startup. This is especially important for large character sets like Big5 or Shift-JIS. If you are using any languages besides "en_us", specify these languages with the "LOAD_LANGUAGES" directives. This will make sure that the languages you are using are pre-loaded during server startup.

Template Administration
I added a template to a category and then deleted it, and now I can't add a new template with the same name. Why not? Deleted template profiles don't actually get deleted but instead marked inactive in the database. This prevents creating a new template with the same name in them same category in the same output channel. In a future release, an easy way to reactivate deleted template profiles will be integrated in the GUI. In the meantime, deleted (that is, deactivated) template can be brought back by using a updating the database directly and querying against the output channel ID and the template's file name: psql -U [username] -d [databasename] -c \ "UPDATE formatting SET active = 1 WHERE output_channel__id = [ocid] \ AND file_name = '[path]'" The arguments in brackets above are: I get an compile error when I try to use $story or $element in a Mason template "<%once>" block. What gives? To check the syntax of a Mason template as you develop it, Bricolage creates a Mason interpreter and compiles the template. Because "<%once>" blocks are designed to execute only once, Mason actually executes them during the compile. Of course, there is no $story or $element object when you're editing a template, only when you're publishing or previewing a story. But since these objects are available in a "<%once>" block during a publish or preview, and as of Bricolage 1.6.14 and 1.8.0 the $burner object is always available, you can use the $story or $element object in a "<%once>" block like this: <%once>; unless ($burner->get_mode == SYNTAX_MODE) { # Do stuff with $story or $element. } </%once> The username for your Bricolage PostgreSQL user. This is the username the Bricolage installer created for you, and which is listed as the "DBI_USER" bricolage.conf directive. The name of the Bricolage database. This is the database the Bricolage installer created for you, and which is listed as the "DB_NAME" bricolage.conf directive. The ID of the output channel that the template is in. The full URI path name of the template. This is a combination of the category path and the name of the template, usually constructed from the element for which it is created. For example, a Mason template created for the "Book Review" element in the category "/reviews/books" would be called /reviews/books/book_review.mc. Scott Lanning <slanning@theworld.com> David Wheeler <david@kineticode.com> README, <http://bricolage.cc/>, Bric::Admin