Bric::Admin - Bricolage System Administration Guide.

$LastChangedRevision$

$LastChangedDate: 2005-07-13 21:03:08 -0700 (Wed, 13 Jul 2005) $

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

Follow these instructions if you are both impatient and expert.

Debian users can get skip most of the download and installation by downloading the debian package from <http://people.debian.org/~erich/bricolage/>. After installing, be sure to follow the instructions in /usr/share/doc/README.Debian to complete the installation.

1

Install Perl 5.6.0 or greater (5.8.0 or later strongly recommended for better Unicode support, and required if you're using a character set other than ASCII). Accented characters and other non-ASCII characters are incorrectly handled when using a Perl older than 5.8.0, so using a 5.8.0 or greater Perl is required whenever handling non-ASCII characters for the UI or in Bricolage stories.

2

Install Apache 1.3.12 or greater with mod_perl, mod_log_config, mod_mime, and mod_alias. For SSL also install mod_ssl or apache-ssl.

3

Install PostgreSQL 7.3 or greater. Be sure to use UNICODE for data encoding.

4

In the Bricolage source directory:

  perl Makefile.PL
  make
  make test

And then as root:

  make install

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

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

•

Perl 5.6.0 (5.6.1 or later recommended, 5.8.0 or later required if using characters beyond the ASCII set).

•

Perl Modules:

Storable

Time::HiRes

Unix::Syslog

Net::Cmd

Devel::Symdump

DBI 1.18

Error

Cache::Cache

Digest::MD5

Digest::SHA1 2.01

URI

HTML::Tagset

HTML::Parser

MIME::Base64

MIME::Tools

Mail::Address

XML::Writer

LWP

Image::Info

MLDBM

Params::Validate

Exception::Class 1.12

Class::Container 0.09

Apache::Request 1.0

HTML::Mason 1.23

DBD::Pg 1.22

DB_File

Apache::Session 1.54

Test::Harness 2.03

Test::Simple

Test::MockModule 0.04

Text::Balanced

XML::Parser 2.34

XML::Simple

IO::Stringy

SOAP::Lite

File::Temp

Cache::Mmap

Text::Soundex

Locale::Maketext

Test::Class

HTTP::BrowserDetect

Params::CallbackRequest 1.10

MasonX::Interp::WithCallbacks 1.10

Safe

Term::ReadPassword

HTML::Template (optional)

HTML::Template::Expr (optional)

Template 2.14 (optional)

Encode (optional)

Pod::Simple (optional)

Test::Pod 0.95 (optional)

Devel::Profiler 0.03 (optional)

Apache::SizeLimit (optional)

Net::FTPServer (optional)

Net::SFTP 0.08 (optional)

HTTP::DAV (optional)

Text::Levenshtein (optional)

Crypt::SSLeay (optional)

Imager (optional)

Text::Aspell (optional)

XML::DOM (optional)

CGI (optional)

•

Apache 1.3.12

•

mod_perl 1.25 - Apache/Perl Integration

•

PostgreSQL 7.3.0

•

Expat 1.95.0

•

OpenSSL 0.9.6b (optional)

•

mod_ssl 2.8.4-1.3.20 - Apache Interface to OpenSSL (optional)

•

apache_ssl 1.3.22+ssl_1.47 Apache SSL (optional)

•

htmlArea 3.0 or later (optional)

•

GNU Aspell 0.50 or later (optional)

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

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

Here is how to install Perl from source:

•

Download the Perl source tarball from www.perl.com.

•

Gunzip and untar the sources.

•

Change to the source directory and execute these commands:

  sh Configure -Umymalloc -Dinstallusrbinperl -des
  make
  make test
  make install

For the curious, the options used with Configure above are:

-Umymalloc

This Configure command will build perl without perl's malloc. This is necessary to prevent segfaults with XML::Parser under mod_perl. This is the default on most systems already.

-Dinstallusrbinperl

This Configure command will arrange for /usr/bin/perl to be linked to the current version of perl. If you don't specify this command, configure will prompt you to find out whether to link /usr/bin/perl to the current version of perl. We strongly suggest that you answer yes.

-des

This optional command tells Configure that you accept all the other defaults, and it will therefore provide terse output during the configuration.

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

•

Download the OpenSSL source tarball from www.openssl.org.

•

Gunzip and untar the sources.

•

Change into the source directory, read the INSTALL file to see if you need to use any Configure commands, and execute these commands:

  sh config <commands>
  make
  make test

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

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

Apache Interface to OpenSSL (mod_ssl)

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

•

Download the mod_ssl source tarball from <http://www.modssl.org/>.

•

Gunzip and untar the sources.

•

Change into the source directory, read the INSTALL file to see if you need to use any Configure commands. The only one required here is CW--with-apache, so you'll need to have already downloaded, gunzipped, and untarred the Apache sources (see below). If you already have a server certificate and a server key, use the CW--with-crt and CW--with-key commands to point to them. You might also want to consider including the optional MM library (see mod_ssl's INSTALL file for details). Then, execute this command:

  ./configure --with-apache=/usr/local/src/bricolage/apache_1.3.xx

Where apache_1.3.xx represents the version of Apache you will be installing (see the Packages section above for a recommended version number.

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

Apache-SSL

•

Download the apache_ssl source tarball from <http://www.apache-ssl.org/>.

•

Copy the tarball into the apache directory, gunzip and untar.

•

Run the FixPatch script.

•

Now build Apache in the normal fashion. The only difference is the added configuration directives for SSL, see SSLconf/conf/ for comprehensive examples. Bricolage handles most of the configuration for you.

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

•

Download the Apache source tarball from httpd.apache.org. Make sure you choose the 1.3.x rather than the new 2.x version.

•

Download the mod_perl source tarball from perl.apache.org.

•

Gunzip and untar the Apache and mod_perl sources.

•

Change into the mod_perl source directory, read the INSTALL file to see if you need to use any Configure commands other than those specified below. Then execute the commands:

  perl Makefile.PL \
    APACHE_SRC=../apache_1.3.*/src \
    DO_HTTPD=1 \
    USE_APACI=1 \
    PREP_HTTPD=1 \
    EVERYTHING=1
  make
  make install

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

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

--with-layout=Apache

This option selects the classical Apache path layout.

--disable-rule=EXPAT

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

--enable-module=ssl (optional)

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

--enable-module=rewrite

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

--activate-module=src/modules/perl/libperl.a

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

--disable-shared=perl

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

•

The commands you'll execute, therefore, should look something like this:

  ./configure               \
    --with-layout=Apache    \
    --disable-rule=EXPAT    \
    --enable-module=rewrite \
    --activate-module=src/modules/perl/libperl.a \
    --disable-shared=perl
  make

Or if you're planning to use mod_ssl:

  ./configure               \
    --with-layout=Apache    \
    --disable-rule=EXPAT    \
    --enable-module=ssl     \
    --enable-module=rewrite \
    --activate-module=src/modules/perl/libperl.a \
    --disable-shared=perl
  make

•

If you plan to use SSL you'll need to install the SSL certificates before you install Apache. If you compiled OpenSSL with the CW--with-crt and CW--with-key commands, you can skip this step. If you don't have a formal certificate from a certificate authority such as VeriSign then you can make a dummy certificate with the command:

  make certificate TYPE=dummy

If you do have a formal certificate then can make a certificate with the command:

  make certificate TYPE=custom

Near the end of the certificate creation process, you will be prompted to enter information for the certificate. Here you'll enter the information for your certificate. See the OpenSSL documentation for a description of the certificate data. You'll be prompted to enter the certificate information twice. Afterward, you'll see this prompt for each of the two new certificates:

  Encrypt the private key now? [Y/n]:

Enter n to avoid having to type in a passphrase every time you start Apache. Enter y if you really don't trust your system users.

•

Finally, install Apache:

  make install

•

Don't forget to install the Apache::Session and Apache::Request perl modules now (See Perl Modules, above). If your Apache is in a non-standard loation, you might need to set the CWAPXS environment variable while installing it so that tests pass:

  % export APXS=/some/nonstandard/apache/bin/apxs

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

  /usr/local/apache/bin/apachectl configtest

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

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

  tcpip_socket = true

Otherwise, here are the installation details:

•

Download the PostgreSQL source tarball from www.postgresql.org.

•

Gunzip and untar the sources.

•

Create a new system user named postgres. This is the user that will start the PostgreSQL server. The startup scripts that come with PostgreSQL mostly seem to expect that the postgres user will use the tcsh shell, so you may wish to set that shell now. Here's an example under Linux:

  /usr/sbin/useradd -d /home/postgres postgres -s /bin/tcsh

•

Change into the source directory and read the INSTALL file to see if you need to use any Configure commands. One Configure command is required by Bricolage: CW--enable-multibyte=UNICODE. Because Bric stores all of its textual data in Unicode format, this command is not optional. If you require the use of a different character set for your installation, this can be configured as part of the system preferences, via the Admin interface.

•

Install PostgreSQL:

  ./configure --enable-multibyte=UNICODE
  make
  make install

•

Now make a directory in which you want to keep your PostgreSQL databases, including the Bricolage database. Make the postgres user the owner of that directory. Think carefully about where you want this directory to be, and on what partition. The Bricolage database will get to be quite large, and will require a great deal of disk accessing, so we recommend you put it on its own partition. This example just demonstrates the default:

  mkdir /usr/local/pgsql/data
  chown postgres /usr/local/pgsql/data

•

Initialize the PostgreSQL database. Be sure to pass the directory you just created to the CW-D command. We also recommend that you specify the C locale, since the collation of many other locales can be quite broken (especially if you're using non-western characters in your content; see <http://archives.postgresql.org/pgsql-general/2004-08/threads.php#01079> for details).

  su - postgres -c "/usr/local/pgsql/bin/initdb --no-locale \
    -D /usr/local/pgsql/data"

You might find it easier to set PostgreSQL default encoding for new databases to UNICODE when initializing the database cluster, using the following command instead of the former one:

  su - postgres -c "/usr/local/pgsql/bin/initdb --no-locale \
    --encoding UNICODE -D /usr/local/pgsql/data"

•

Start the PostgreSQL postmaster. You can use one of the scripts in contrib/start-scripts.

•

Make the PostgreSQL documentation. This step is optional, if you don't need the docs or have them available elsewhere:

  cd docs
  make install

•

Don't forget to install the DBD::Pg perl module! If its Makefile.PL can't find your installed version of PostgreSQL, you'll need to set the CWPOSTGRES_INCLUDE and CWPOSTGRES_LIB environment variables, first:

  export POSTGRES_INCLUDE=/usr/local/include
  export POSTGRES_LIB=/usr/local/lib

Then you can build the module:

  cd /path/to/DBD-Pg-1.xx
  perl Makefile.PL
  make
  make test
  make install

And now PostgreSQL is ready to go!

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

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

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

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

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

•

Download the package sources.

•

Gunzip and untar the sources.

•

Change to the source directory and execute these commands:

  perl Makefile.PL
  make
  make test
  make install

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

•

Download the latest Bricolage sources from <http://bricolage.cc/>.

•

Decompress the Bricolage sources into a directory of your choice and change into that directory.

•

Build Bricolage:

  make

This step will check your system for all required packages. It will also ask you questions regarding your installation. In most cases the default answer will be correct and you can just press return. Note that if you use 'IDENT sameuser' authentication in PostgreSQL, you have to 1) use the same username for 'Bricolage Postgres Username' as you did for 'Apache User' (so that the apache process has permission to access the database), and 2) enter a bogus password for 'Bricolage Postgres Password'.

•

Install Bricolage (as root):

  make install

If you run into a problem, the fastest way of getting help is to search the bricolage-general archive at <http://sourceforge.net/mailarchive/forum.php?forum_id=560>. Failing that, please send an email to the mailing list itself at bricolage-general@lists.sourceforge.net. Please make sure that you describe your problem as concisely as possible. Questions like My installation fails, please help will not help other users to help you. If other uses confirm that the problem you're experiencing is a bug and suggest that you send a bug report, file it at <http://bugzilla.bricolage.cc/>. Include a copy of all *.db files generated by the Makefile as well as a complete description of where the process failed. Then, either wait for us to fix the problem or try the manual installation instructions below.

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

Here's how to install Bricolage manually.

•

Download the latest Bricolage sources from <http://bricolage.cc/>. Decompress them into /usr/share/bricolage.

•

Change directories into /usr/share/bricolage/bin and run bric_pgimport as follows:

  ./bric_pgimport -u postgres -p postgres -d dbname -c -m db_user:db_password

Where 'dbname' is the name you want the Bricolage database to be called in PostgreSQL, and 'db_user' and 'db_password' are the user name and password to be created in the PostgreSQL database, and under which the Bricolage application will run. Note that the -u argument must represent a PostgreSQL user with CREATE DATABASE and CREATE USER permissions. The 'bric_user' user will be created without these permissions (the 'dbname' database will be owned by the user passed in via the -u argument), but will be granted full CREATE, DELETE, UPDATE, and SELECT permissions on all objects in the Bricolage database. See Bric::DBA for more information on database security. You may want to alter the default security policy. Also, bric_import uses a TCP/IP connection so you may need to run postmaster with the -i option.

•

Configure Apache to use Bricolage. To have Bricolage run as the main server process on your Apache server, simply add the following two lines to your httpd.conf file (an example is provided in conf/httpd.conf):

  PerlPassEnv BRICOLAGE_ROOT
  PerlModule Bric::App::ApacheConfig

Bricolage will automatically pass the necessary configuration directives to the Apache daemon. As of mod_perl 1.27, Bricolage uses Apache::ReadConfig to configure the httpd daemon. There is no httpd include file. If you wish to have Bricolage generate and use an httpd include file, or if you with to manually configure your httpd daemon, set the CWMANUAL_APACHE directive in conf/bricolage.conf. This directive will force the startup process to write out the Bricolage configuration directives to CI$TEMP_DIR/bricolage/bric_httpd.conf, and then this file will be automatically rewritten and included on each startup operation. If you change the line

  PerlModule Bric::App::ApacheConfig

to

  PerlModule Bric::App::ApacheStartup

then only the contents of the httpd.conf file specified in bricolage.conf via the CWAPACHE_CONF direcive will be passed to the httpd daemon. You can also configure Bricolage to run on a virtual host. See CONFIGURATION below.

•

Start Apache. Use one of the scripts in scripts/ if you like. You can manually start it via the following command:

  /usr/share/bricolage/bin/bric_apachectl start

•

Try to hit the web server. If you're prompted for a login, you're in! If not, check the Apache error log to figure out what might have gone wrong. To start using Bricolage, log in as the default user. The user name is admin and the password is change me now!. This user is not special, so you can change it however you like. The first thing you should do is to change the admin login password so that others who download the Bricolage sources can't just use that login to get into your installation! Now use the admin login to create other user accounts.

To install htmlArea, an optional application that offers WYSIWYG editing in the Bricolage UI, simply download it from <http://www.htmlarea.com/>, decompress the files, and move them to the comp/media/htmlarea directory in your Bricolage root. You will also need to enable the CWENABLE_HTMLAREA bricolage.conf directive (see UI Configuration).

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

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

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

  export BRICOLAGE_ROOT=/opt/bricolage

Next, stop the server:

  bin/bric_apachectl stop

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

  cp conf/bricolage.conf conf/bricolage.conf.old
  cp conf/httpd.conf conf/httpd.conf.old

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

Delete all existing Mason object files and temporary files:

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

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

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

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

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

Now, start up Bricolage and enjoy the new features!

  bin/bric_apachectl start

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

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

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

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

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

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

•

APACHE_BIN: This directive sets the location of the Apache server binary. Defaults to CW/usr/local/apache/bin/httpd if not specified. This isn't portable, so we recommend you set it! Used only in bric_apachectl.

•

APACHE_CONF: This directive sets the location of the Apache server configuration file. Defaults to CW/usr/local/apache/conf/httpd.conf if not specified. This isn't portable, so we recommend you set it! Used only in bric_apachectl.

•

LISTEN_PORT: The TCP/IP Port on which the Bricolage server should listen for requests. Defaults to 80 if not specified. You must also tell Apache to listen on this port in the configuration file specified in CWAPACHE_CONF (using Listen, Port, or BindAddress).

•

SSL_ENABLE: Set this directive to enable SSL support. The possible values are Off, mod_ssl, or apache_ssl. The Apache OpenSSL interface (mod_ssl or apache_ssl) is an optional part of the Bricolage application. Not only does it enable secure logins to the system, but it also allows completely secure access to the entire application, should you need it (and not need to worry about the performance overhead). Make sure you've followed the installation instructions for building a mod_ssl or apache_ssl. Disabled by default. Note: The CWLISTEN_PORT directive must be set to 80 if CWSSL_ENABLE is on. The Bricolage server will not start if CWSSL_ENABLE is on and CWLISTEN_PORT is set to a value other than 80.

•

SSL_CERTIFICATE_FILE: If you have enabled SSL, use this directive to set the location of the SSL certificate file. This file will be used by the Bricolage virtual host (if specified via the CWNAME_VHOST and CWVHOST_SERVER_NAME parameters) for the SSL encryption support. Use in tandem with the CWSSL_CERTIFICATE_KEY_FILE direcive Defaults to an empty value.

•

SSL_CERTIFICATE_KEY_FILE: If you have enabled SSL, use this directive to set the location of the SSL certificate key file. This file will be used by the Bricolage virtual host (if specified via the CWNAME_VHOST and CWVHOST_SERVER_NAME parameters) for the SSL encryption support. Use in tandem with the CWSSL_CERTIFICATE_FILE direcive. Defaults to an empty value.

•

ALWAYS_USE_SSL: With CWSSL_ENABLE set to mod_ssl or apache_ssl, this directive removes the choice of using SSL from the user's control and forces all access to the application server to use the https protocol. This approach may be valuable in those organizations that need to guarantee 100% encrypted access to Bricolage and can afford the overhead. Disabled by default.

•

NAME_VHOST: The IP address on which the virtual host name specified in the CWVHOST_SERVER_NAME directive will respond. Note that the syntax for this directive is identical to the syntax for Apache's CWNameVirtualHost directive. Also note that the VirtualHost record that Bricolage creates will be for CWNAME_VHOST . ':' . LISTEN_PORT, so if you want to identify your own virtual hosts to listen for on the same IP address, you will need to include the port number in your CWVirtualHost declarations. Also note that if the CWSSL_ENABLE is turned on, then a CWNAME_VHOST . ':443' VirtualHost directive will also be created by Bricolage. The upshot is to remember to always use the port number in your own VirtualHost declarations. Defaults to * if not specified.

•

VHOST_SERVER_NAME: The host name under which Bricolage will run as a virtual host in the Apache server. Defaults to the default host if not specified.

•

CHECK_PROCESS_SIZE: Turn on this feature to limit the size of Apache child processes. CWMAX_PROCESS_SIZE determines the maximum size in KBs to which the processes will be allowed to grow. CWCHECK_FREQUENCY determines how many requests will be handled before a process' candidacy for termination is evaluated. CWMIN_SHARE_SIZE Indicates the minimum amount of shared memory the process must employ to not be a candidate for termination. CWMAX_UNSHARED_SIZE Sets a limit on the amount of unshared memory a process may consume to not be a candidate for termination. Set CWMIN_SHARE_SIZE or CWMAX_UNSHARE_SIZE to '0' to disable either respective test. All size settings are in KBs. See Apache::SizeLimit for more information.

•

MANUAL_APACHE: Choose the Apache configuration method. As of mod_perl 1.27, Bricolage uses Apache::ReadConfig to configure the httpd daemon. If you wish have Bricolage generate an httpd.conf include file, or if you wish to manually configure your Apache server for Bricolage, set this directive to a true value. Doing so will cause Bricolage to generate CI$TEMP_DIR/bricolage/bric_httpd.conf to provide a tracefile or template for your own manual httpd.conf. If no changes are made to CI$BRICOLAGE_ROOT]/conf/httpd.conf, then this file will be automatically included on each startup by the last line of the httpd.conf file:

  PerlModule Bric::App::ApacheConfig

If this line is changed to

  PerlModule Bric::App::ApacheStartup

then only the contents of the httpd.conf specified by the CWApache_CONF directive will be passed to the httpd daemon.

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

•

DB_NAME: The name of the Bricolage database. Defaults to sharky if not specified.

•

DB_HOST: The host name of the server that hosts the Bricolage database. Defaults to the relevant value used by the DBD driver if not specified.

•

DB_PORT: The port on which the server database server that hosts the Bricolage database listens. Defaults to the relevant value used by the DBD driver if not specified.

•

DBI_USER: The name of the PostgreSQL user as whom Bricolage should connect to the DB_NAME database. This should be the same as the username passed to the first half of the -m argument to CWpgimport (see above). Defaults to castellan if not specified.

•

DBI_PASS: The password of the PostgreSQL user as whom Bricolage should connect to the DB_NAME database. This should be the same as the password passed to the second half of the -m argument to CWpgimport (see above). Defaults to nalletsac if not specified.

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

•

SYS_USER: The system user as whom Bricolage runs. Must be the same as the CWUser directive used in the Apache configuration file specified in the CWAPACHE_CONF configuration directive. Defaults to nobody if not specified.

•

SYS_GROUP: The system group of which SYS_USER is a member. Must be the same as the CWGroup directive used in the Apache configuration file specified in the CWAPACHE_CONF configuration directive. Defaults to nobody if not specified.

•

TEMP_DIR: The system will create a sub-directory below this directory where Bricolage will store temporary files. Must be writable by CWSYS_USER described above. May be overridden by a CW$BRIC_TEMP_DIR environment variable. Defaults to the return value from CWFile::Spec->tempdir if not specified.

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

•

MASON_COMP_ROOT: Mason's element root. This is the directory in which all the Bricolage UI elements are stored. Defaults to CW$BRICOLAGE_ROOT/comp if not specified.

•

MASON_DATA_ROOT: Mason's data root. This where Mason stores the Bricolage UI elements once they've been compiled. Defaults to CW$BRICOLAGE_ROOT/data if not specified. Make sure that SYS_USER has permission to write to this directory.

•

BURN_ROOT: The staging area directory where the burn system places content files upon publication or preview. Defaults to CW$MASON_DATA_ROOT/burn if not specified. Make sure that SYS_USER has permission to write to this directory.

•

TEMPLATE_QA_MODE: When enabled, this directive causes more verbose error messages to be displayed when there is an exception thrown during a publish or preview. This may be useful for debugging templates while developing them. Defaults to off if unspecified.

•

INCLUDE_XML_WRITER: This directive, when switched on, causes Bricolage to instantiate an XML::Writer object and to include it in all templates as a global variable named CW$writer. See the XML::Writer documentation for more information. Defaults to off if unspecified. Note: Only the Mason burner supports XML::Writer.

•

XML_WRITER_ARGS: If INCLUDE_XML_WRITER is switched on, then this directive is passed to the instantiation method of the XML::Writer object. All arguments to XML::Writer->new() are supported except the OUTPUT argument, which Bricolage handles internally to ensure that data is sent directly to the template's output file. Defaults to no arguments if not specified. Note: Only the Mason burner supports XML::Writer.

These directives set rules for Bricolage user authentication.

•

AUTH_TTL: The amount of time, in seconds, a user is allowed to be idle before he/she is automatically logged out. Defaults to 8 hours (28,800 seconds) if not specified.

•

AUTH_SECRET: A random string that's used to encrypt the authentication cookie information in a double-MD5 hashing scheme. It's a good idea to change this value periodically so that anyone who might have seen it before can't reverse-engineer the authentication cookie. If you're running the distribution monitor (see below) on a different machine, be sure that this directive is exactly the same as on the machine running the Bricolage distribution server. Defaults to the following string if not specified:

  ^eFH5D,~3!f9o&3f_=dwePL3f:/.Oi|FG/3sd9=45oi%8GF*)4#0gn3)34tf\`3~fdIf^ N:

•

LOGIN_LENGTH: The minimum length of login name allowed to users. Defaults to 5 if not specified.

•

PASSWD_LENGTH: The minimum length of password allowed to users. Note that passwords can be of infinite length. Defaults to 5 if not specified.

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

•

ENABLE_DIST: This directive indicates whether the Bricolage server will also handle distribution responsibilities. If set to On or Yes or 1, the Bricolage server will handle distribution. If set to any other value, it will not. In this latter case, be sure you set up another server to do it. Note that this directive has no effect on previews, as those need to be immediate and will thus always be handled by the Bricolage server. Defaults to 1 if not specified.

•

DIST_ATTEMPTS: This directive tells the distribution engine how many times to attempt to distribute a resource before giving up. This number can range from 1 to 10, and defaults to 3 if not specified.

•

PREVIEW_LOCAL: This directive tells Bricolage to use its own Apache server to preview stories. If set to On or Yes or 1, Bricolage will use its own Apache server to serve preview pages (using a directory prefix from the root). If it's set to any other value, it will use a server from a destination with the 'Preview' checkbox checked. For large Bricolage installations where performance is important, we recommend that you use a separate server for previews, as using the Bricolage server itself adds a fair bit of overhead to every request including requests outside of the preview directory. Defaults to 1 if not specified.

•

PREVIEW_MASON: This directive tells Bricolage to use Mason for local story previews. If set to On or Yes or 1, Bricolage will use its own Apache server and Mason to serve preview pages. If it's set to any other value, it will not use Mason for local previews. For large Bricolage installations, we recommend that you not use Bricolage's built-in previewing support (see above), and even when you do, enabling Mason for local previews adds even more overhead to every request including requests outside of the preview directory. Defaults to 0 if not specified, and has no affect unless the PREVIEW_LOCAL directive has been activated (see above).

•

DEF_MEDIA_TYPE: Designates the default media type for assets where Bricolage cannot ascertain the media type. The value of this directive must be present in the database see Bric::Util::MediaType for more information. Defaults to text/html if not specified.

•

ENABLE_SFTP_MOVER: This directive indicates whether the Bricolage server may distribute resources using the SFTP mover. Setting this to On or Yes or 1 will enable the SFTP mover. In order to use the SFTP mover, you must manually install the Net::SFTP module from the CPAN. Furthermore, you should login to the remote server in order to initialize ~/.ssh/known_hosts before using the SFTP mover. You might also need to create the directory /.ssh on the Bricolage server (and possibly on the destination server, too) with write permission for nobody, in case nobody's home directory is something like /bin/false and ssh falls back to / as the home directory). To use a private key, it must be named ~/.ssh/identity for ~/.ssh/id_rsa, as those are the files that Net::SSH::Perl looks for. Defaults to Off if not specified.

•

ENABLE_SFTP_V2: Set this directive to On or Yes or 1 to enable the SFTP mover to try to use the SSH protocol 2 before protocol 1; otherwise, it first tries protocol 1. Enable this directive if you've installed the necessary CPAN modules for SSH-2 support in Net::SFTP. Disabled if not specified.

•

SFTP_HOME: If you've enabled SFTP, set this directive to a directory containing your SSH keys and with permisssions appropriate for CWSYS_USER to access. If no value is provided, the default will be specified by Net::SFTP, but is generally / (and therefore probably not what you want).

•

SFTP_MOVER_CIPHER: This directive forces the SFTP mover (if enabled by the CWENABLE_SFTP_MOVER directive) to use a particular encryption cipher. This can be useful for tuning SFTP distribution for speed. The default is 0, which allows the default cipher to be used. Consult the Net::SSH::Perl documentation for a complete list of supported ciphers for SSH-1 and SSH-2. As of this writing, the suppported ciphers are IDEA, DES, DES3, and Blowfish for SSH-1; and arcfour, blowfish-cbc, and 3des-cbc for SSH-2. The default SSH-1 cipher is IDEA; the default SSH-2 cipher is 3des-cbc.

•

ENABLE_WEBDAV_MOVER: Bricolage also supports resource distribution through the WebDAV protocol. Set this directive to On or Yes or 1 to enable it. You need to have installed HTTP::DAV from the CPAN, in order to use WebDAV from Bricolage. Please note that currently due to restrictions in the perl www client library (LWP), a resource must be fully loaded into memory before being uploaded to the WebDAV server. It's recommended not to use the WebDAV transport to transfer large files, such as movies. Check <http://www.webdav.org/> for information on the WebDAV protocol.

•

QUEUE_PUBLISH_JOBS. This directive indicates that all publishing should be run from a queue. If this is set to On or Yes or 1 then a request for publication either from a publish desk or from the story profile page will result in the creation of a Bric::Util::Job::Pub object, which will be tracked in the job list. Publish jobs can fail on CWDIST_ATTEMPTS or more errors, wether caused by a template error or some other fault. In this case they will be left in the queue but marked failed to prevent further execution attempts, and the error message will be stored for debugging. This feature can be used with either bric_queued or with a specially tuned instance of Bricolage to limit the system resources given over to publishing. The new queue daemon, bric_queued, always executes publish jobs one at a time, while maintaining a seperate thread for distribution jobs. If you prefer to run publish jobs from the queue concurrently, you can still control the use of system resources by running a second instance of Bricolage, setting the Apache MaxClients configuration directive to control the number of Apache processes which will be used for publishing, and thus the amount of memory and processor cycles.

•

FTP_UNLINK_BEFORE_MOVE. This directive must be set to Yes for some FTP servers (e.g. pure-ftpd has been reported to need this) to correctly handle uploads of already existing files: when publishing via FTP, Bricolage first creates a temporary file, than moves this temp file over the existing, older file, overwriting it. Some servers do not support renaming to existing files, so the original one must be deleted first.

•

DISABLE_NAV_LAYER: Rather than have the UI's left side navigation menu rendered in its own separate layer, make it a part of the raw HTML of the page. This may be necessary if you encounter problems with the side navigation layer in your browser. Note that by setting this directive to a true value, any changes made to a form in the UI will be lost by clicking a menu item rather than the Save button. Defaults to 0 if not specified.

•

ALLOW_WORKFLOW_TRANSFER: Allow assets to be transfered across workflows via shared desks. By default, a desk that is shared between workflows appears in both workflows, but any asset on that desk can only be transfered to other desks in the workflow from which the asset originated. To allow assets to optionally be able to move to desks in any of the workflows a desk is a member of, set this directive to Yes, On or 1. Defaults to Off if not specified.

•

FULL_SEARCH: Enables Bricolage to perform sub-string searches in its database queries, rather than merely to search at the beginning of a string. Full sub-string searches are more expensive, since they cannot use database indexes, but that may not matter if there are few records in your database. Many users find the sub-string searches to be more intuitive, so enable it if you find the trade-off to be worth it. Defaults to Off if not specified.

•

ALLOW_ALL_SITES_CX: Allow users to select All Sites from their site context menu. This will enable them to see the workflows for all sites to which they have at least READ access. Defaults to Off if not specified.

•

YEAR_SPAN_BEFORE and YEAR_SPAN_AFTER: These directives enable you to control how many years before and after the current year to display in the list of years in the date and time select widget. The default values are 10 for each, meaning that if the current year is 2003, then the date span will be from 1993 to 2013.

•

ENABLE_CATEGORY_BROWSER: Category browser setting. Enable this directive to make the Media and Story profiles use the category browserb. This is useful if you have a lot of categories, as it prevents them all from being loaded into a big select list each time you edit a Media or Story document. Disabled by default.

•

ENABLE_HTMLAREA and HTMLAREA_TOOLBAR: These directives control the htmlArea WYSIWYG editor in Bricolage. htmlArea 3.0 must be installed in comp/media/htmlarea. Download it from <http://www.interactivetools.com/products/htmlarea/> and simply rename the decompressed archive file to comp/media/htmlarea in your Bricolage root. Once it's installed and CWENABLE_HTMLAREA has been enabled, you can specify exactly what shows up in your htmlArea toolbar and how it is displayed. This is useful for ensuring that content remains separate from presentation. For example, you usually won't want to include the font control buttons, as these are generally best managed in templates. Here is a complete list of the available buttons:

fontname

fontsize

formatblock

bold

italic

underline

strikethrough

subscript

superscript

copy

cut

paste

undo

redo

linebreak

justifyleft

justifycenter

justifyright

justifyfull

lefttoright

righttoleft

insertorderedlist

insertunorderedlist

outdent

indent

forecolor

hilitecolor

inserthorizontalrule

createlink

insertimage

inserttable

htmlmode

popupeditor

showhelp

about

In addition to the button specifications, htmlArea configuration supports a few other toolbar configuration options:

space

Inserts a space of 5 pixels (the width is configurable by external CSS) at the current position in the toolbar.

separator

Inserts a small vertical separator, for visually grouping related buttons.

linebreak

Starts a new line in the toolbar. Subsequent controls will be inserted on the new line. The default value for CWHTMLAREA_TOOLBAR is:

  ['bold', 'italic', 'underline', 'strikethrough', 'separator', 'subscript',
   'superscript', 'separator', 'copy', 'cut', 'paste', 'space', 'undo',
   'redo', 'createlink', 'htmlmode', 'separator', 'popupeditor', 'separator',
   'showhelp', 'about']

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

•

LOAD_LANGUAGES and LOAD_CHAR_SETS: Tell Bricolage which languages and character sets to pre-load. If you plan on using multiple languages and/or character sets, you can save some memory by pre-loading them at server startup. Otherwise, they will be loaded on demand. Multiple entries should be separated by spaces. CWLOAD_LANGUAGES defaults to en_us and CWLOAD_CHAR_SETS defaults to UTF-8.

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

•

SMTP_SERVER: The DNS name of an SMTP server that the Alerting API can send alerts to. All alerts are sent by email, so this directive is important to fill out. Defaults to localhost if not specified.

•

ALERT_FROM: The email address that appears in the 'From' header of emailed alerts. Defaults to SERVER_ADMIN directive if not specified.

•

ALERT_TO_METH: The email header used for addressing alert recipients. Use to if you want everyone who receives the same alert to see who else received it. Use bcc if you don't want anyone to see who else got an alert, or if you just want to save the bandwidth. Defaults to bcc if not specified.

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

•

USE_THUMBNAILS: Enables thumbnail generation and display for image media files in the Bricolage UI, and icon display in the UI for all other media files. See contrib/copy_gnome_icons for a scipt to copy GNOME icons into the Bricolage root for use in the UI. Only one icon is included by default, with thanks to the KDE project's license for the graphic (<http://artist.kde.org/new/license.html#others>). Disabled by default.

•

THUMBNAIL_SIZE: Sets the size of the thumbnails generated by Bricolage. The largest dimension of the thumbnail will be no greater than this value, ensuring relative uniformity of size for display in the UI. Defaults to 75 if not specified.

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

•

DEFAULT_FILENAME: Sets the default filename that all new Output Channel will start with in their File Name property. Combined with DEFAULT_FILE_EXT and a page index number to uniquely name the file for a given story. Defaults to index if not specified.

•

DEFAULT_FILE_EXT: Sets the default file extension that all new Output Channel will start with in their File Name property. Combined with DEFAULT_FILENAME and a page index number to uniquely name the file for a given story. Defaults to html if not specified.

•

STORY_URI_WITH_FILENAME: Enable this directive if you wish for story URIs to always include their file names. This is useful for allowing stories to be in the same category and date but have different file names and still be unique. Off by default.

•

PERL_LOADER: Pass in a line of Perl code, and it will be executed at startup time in the same package spaces as your templates run in. This is so that you only have to load stuff that you might often use once, such as CGI.pm or Apache::DBI. This should be a complete Perl statement that can simply be loaded, and won't pause and wait for anything else, as otherwise your server will never start! And be warned that this code is executed at server startup time, so beware loading any variables that don't survive forks very well (such as database handles). Defaults to load nothing if not specified. Note: Only the Mason burner supports PERL_LOADER.

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

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

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

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

•

ENABLE_FTP_SERVER: Set this to 1 if you want to use the FTP server. Defaults to 0.

•

FTP_PORT: The port that the FTP server will run on. Users will need to know this port to connect to the FTP server. Since you won't be running the server as root you'll need to choose a port above 1024. Defaults to 2121.

•

FTP_ADDRESS: Normally the FTP server will bind to all the available IP addresses for your machine. If you set this variable then the server will only bind to the specified address.

•

FTP_LOG: Set this to the file where you want to FTP logs written to. Defaults to CW$BRICOLAGE_ROOT/ftp.log if not set.

•

FTP_PID_FILE: Set this to the file where you want to the FTP daemon PID stored. Defaults to CW$BRICOLAGE_ROOT/ftp.pid if not set.

•

FTP_DEPLOY_ON_UPLOAD: Prior to Bricolage. 1.8.0, the virtual FTP server deployed a template whenever it was uploaded. Beginning with Bricolage 1.8.0, templates are checked out to the user and put on her workspace and in her sandbox for testing, but they are not deployed. Enable this directive to restore the pre-1.8.0 behavior.

•

FTP_DEBUG: If you set this to 1 you'll see a lot of useful tracing information in the FTP logfile. This can help diagnose errors but is probably only of interest to developers. Defaults to 0.

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

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

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

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

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

  $BRICOLAGE_ROOT/data
  $BRICOLAGE_ROOT/comp/data

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

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

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

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

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

1.

Shut down Apache if it's running:

  /usr/share/bricolage/bin/bric_apachectl stop

2.

Delete the existing installation of Apache:

  rm -rf /usr/local/apache*

3.

Change directories into /usr/local/src/bricolage/apache_build/apache_1.3.xx.

4.

Execute the following command:

  make certificate TYPE=custom

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

5.

Execute the following command:

  make install

This will install Apache and the new certificate.

6.

Start Apache again:

  /usr/share/bricolage/bin/bric_apachectl start

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  make clone

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

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

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

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

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

There is also an on-line copy at <http://www.bricolage.cc/docs/Bric/FAQ.html>.

David Wheeler <david@wheeler.net>

Bric