Admin.pod

=head1 Name

Bric::Admin - Bricolage System Administration Guide.

=head1 Description

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

=head1 Quick Installation Instructions

For the really impatient you can just download a VMWare image with Bricolage
already set up for you running under Ubuntu. See L<the
announcement|http://www.bricolagecms.org/news/announce/2008/06/01/vmware/> for
more details.

There are lots of hints and tips for installation at the L<Bricolage
Wiki|http://wiki.github.com/bricoleurs/bricolage/>, along with other tutorials
and useful bits.

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

=over

=item 1

Install Perl 5.8.0 or greater.

=item 2

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

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

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

=item 3

Install PostgreSQL 8.1 or greater or MySQL 5.0.3 or greater.

=item 4

In the Bricolage source directory:

  perl Makefile.PL
  make
  make test

And then as root:

  make install

=back

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

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

  make INSTALL_VERBOSITY=QUIET
  make test
  make INSTALL_VERBOSITY=QUIET install

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

=head2 Installation Variables

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

=over

=item * BRICOLAGE_ROOT

The location where Bricolage should be installed. Defaults to
F</usr/local/bricoage>.

=item * BRICOLAGE_INSTALL_STYLE

One of two values describing where to install all of the Bricolage files:

=over

=item m

All files, including Perl libraries, temp files, programs, etc., will be
installed under C<$BRICOLAGE_ROOT>. This is the default and recommended
option.

=item s

Most files will be installed under C<$BRICOLAGE_ROOT>, but Perl libraries,
programs, and man pages will be stored where Perl libraries and scripts
usually go (e.g., F</usr/local/lib/perl>, F</usr/local/bin>, and
F</usr/local/man>), temporary files will be stored in the system temp
directory (e.g., C</tmp>, etc.

=back

=item * BRICOLAGE_TEMP_DIR

The location to use for temporary files when bricolage is running. Defaults to
C<$BRICOLAGE_ROOT/tmp>. Ignored when C<$BRICOLAGE_INSTALL_STYLE> is set to
"s".

=item * BRICOLAGE_MODULE_DIR

The directory under which to install Bricolage's Perl modules. Defaults to
C<$BRICOLAGE_ROOT/lib>. Ignored when C<$BRICOLAGE_INSTALL_STYLE> is set to
"s".

=item * BRICOLAGE_BIN_DIR

The directory under which to install Bricolage's programs. Defaults to
C<$BRICOLAGE_ROOT/bin>. Ignored when C<$BRICOLAGE_INSTALL_STYLE> is set to
"s".

=item * BRICOLAGE_MAN_DIR

The directory under which to install Bricolage's C<man> pages. Defaults to
C<$BRICOLAGE_ROOT/man>. Ignored when C<$BRICOLAGE_INSTALL_STYLE> is set to
"s".

=item * BRICOLAGE_COMP_ROOT

The directory under which to install Bricolage's UI Mason components. Defaults
to C<$BRICOLAGE_ROOT/comp>.

=item * BRICOLAGE_DATA_DIR

The directory for Bricolage to use for its UI Mason data. Defaults to
C<$BRICOLAGE_ROOT/data>.

=item * BRICOLAGE_LOG_DIR

The directory for Bricolage to use for its log files. Defaults to
C<$BRICOLAGE_ROOT/data>.

=item * BRICOLAGE_PID

The file name Bricolage should use for its PID file. Defaults to
C<$BRICOLAGE_ROOT/log/httpd.pid>.

=item * BRICOLAGE_DB_TYPE

The type of database to use. Must be one of the following:

=over

=item Pg

PostgreSQL. This is the default choice.

=item mysql

MySQL.

=back

=item * BRICOLAGE_PG_CONFIG_PATH

=item * BRICOLAGE_MYSQL_CONFIG_PATH

The path to the database config program. This would an implmentation of
C<pg_config> for PostgreSQL or C<mysql_config> for MySQL. Bricolage will try
to find the appropriate one to use for the default.

=item * BRICOLAGE_CREATE_DB

A boolean indicating whether or not the databse should be created. Defaults to
true. If you set this to a false value, the database should already exist and
the Bricolage database user will need to have permission to create objects in
it (tables, indexes, sequences, etc.).

=item * BRICOLAGE_PG_SUPERUSER

The name of the PostgreSQL super user. Defaults to "postgres".

=item * BRICOLAGE_PG_SUPERPASS

The password for the PostgreSQL super user. Defaults to an empty string, which
works for a locally-installed PostgreSQL using "trust" or "ident"
authentication.

=item * BRICOLAGE_PG_BECOME_USER

A boolean indicating whether or not the installer should become the PostgreSQL
system user (usually named "postgres") before connecting to the database and
making changes to it. Such is required if your PostgreSQL server uses ident
authentication, as is the default for Debian builds of PostgreSQL. Defaults to
false.

=item * BRICOLAGE_PG_BRICUSER

The name of the PostgreSQL user for Bricolage itself to use. Defaults to
"bric".

=item * BRICOLAGE_PG_DB

The name of the database for Bricolage to use. Defaults to "bric".

=item * BRICOLAGE_PG_HOSTNAME

The name of the host for the PostgreSQL database server. Defaults to
"localhost".

=item * BRICOLAGE_MYSQL_SUPERUSER

The name of the MySQL super user. Defaults to "root".

=item * BRICOLAGE_MYSQL_BRICUSER

The name of the MySQL user for Bricolage itself to use. Defaults to
"bric".

=item * BRICOLAGE_MYSQL_DB

The name of the database for Bricolage to use. Defaults to "bric".

=item * BRICOLAGE_HTTPD_VERSION

The version of Apache to use. Must be one of the following:

=over

=item apache

Apache 1.3.x. This is the default choice, although that's subject to change in
a future release.

=item apache2

Apache 2.x.

=back

=item * APACHE_EXE

=item * APACHE2_EXE

The base name of the Apache executable, usually "httpd", which happens to be
the default.

=item * APACHE_PATH

=item * APACHE2_PATH

A C<$PATH> environment variable-style list of directories to search for the
Apache executable. Defaults to the value returned by
C<File::Spec::Functions::path>.

=item *

=item * BRICOLAGE_SSL

A boolean value indicating whether or not Bricolage should use SSL. Defaults
to true if the detected Apache server supports SSL, and false if it does not.

=item * BRICOLAGE_SSL_CERT

The location of the SSL certificate file that Bricolage should use. Defaults
to F<$HTTPD_ROOT/conf/ssl.key/server.cert>, where C<$HTTPD_ROOT> is collected
from the C<httpd> executable.

=item * BRICOLAGE_SSL_KEY

The location of the SSL key file that Bricolage should use. Defaults to
F<$HTTPD_ROOT/conf/ssl.key/server.key>, where C<$HTTPD_ROOT> is collected from
the C<httpd> executable.

=item * BRICOLAGE_SSL_KEY

The location of the SSL key file that Bricolage should use.

=item * BRICOLAGE_APACHE_USER

The name of the Apache super user, usually "nobody" or "daemon".

=item * BRICOLAGE_APACHE_GROUP

The name of the Apache super user, usually "nobody" or "daemon".

=item * BRICOLAGE_APACHE_PORT

The port for Bricolage to use for its Apache server. Defaults to 80.

=item * BRICOLAGE_APACHE_SSL_PORT

The SSL port for Bricolage to use for its Apache server. Defaults to 443. This
option is ignored of SSL is not used.

=item * BRICOLAGE_APACHE_HOSTNAME

The host name that Bricolage should use when it configures itself to run on a
virtual host inside of Apache. Default to the value retuned by C<`hostname`>.

=item * EXPAT_PATH

A C<$PATH> environment variable-style list of directories to search for expat.
Defaults to the value returned by C<File::Spec::Functions::path>.

=back

=head1 Packages

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

=over

=item *

Perl 5.8.0.

=item *

Perl Modules:

=begin installation

START MODULE LIST

=end installation

=over

=item Storable

=item Time::HiRes

=item Unix::Syslog

=item Net::Cmd

=item Devel::Symdump

=item DBI 1.49

=item Error

=item Cache::Cache

=item Cache::Mmap

=item Digest::MD5

=item Digest::SHA1 2.01

=item URI

=item HTML::Tagset

=item HTML::Parser

=item MIME::Base64

=item MIME::Tools

=item Mail::Address

=item XML::Writer

=item LWP

=item Image::Info

=item MLDBM

=item Params::Validate

=item Exception::Class 1.12

=item Class::Container 0.09

=item HTML::Mason 1.37

=item DB_File

=item Apache::Session 1.54

=item Test::Harness 2.03

=item Test::Simple

=item Test::MockModule 0.04

=item Test::File::Contents 0.02

=item Test::File

=item Text::Balanced

=item XML::Parser 2.34

=item XML::Simple

=item IO::Stringy

=item SOAP::Lite

=item File::Temp

=item Text::LevenshteinXS

=item Locale::Maketext

=item Test::Class 0.04

=item Params::CallbackRequest 1.16

=item MasonX::Interp::WithCallbacks 1.10

=item Safe 2.09

=item DateTime 0.21

=item DateTime::TimeZone 0.2601

=item Term::ReadPassword

=item Data::UUID

=item List::Util

=item List::MoreUtils

=item Text::Diff

=item Text::Diff::HTML 0.02

=item Text::WordDiff

=item URI::Escape

=item Scalar::Util

=item Clone

=item Imager

=item HTML::Template (optional)

=item HTML::Template::Expr (optional)

=item Template 2.14 (optional)

=item PHP::Interpreter (optional)

=item Encode (optional)

=item Pod::Simple (optional)

=item Test::Pod 1.42 (optional)

=item Net::FTPServer (optional)

=item Net::SSH2 0.28 (optional)

=item HTTP::DAV (optional)

=item Crypt::SSLeay (optional)

=item Text::Aspell (optional)

=item XML::DOM (optional)

=item CGI (optional)

=back

Note that you also have some required categories of modules, but you must pick
from among them. Depending on your choice of database, you will need to install
one of:

=begin installation

START DBD

=end installation

=over

=item DBD::Pg 1.22

=item DBD::mysql 3.0007

=back

And depending on whether you're using Apache 1 or Apache 2, you'll need to
install one of:

=begin installation

END DBD

START Apache

=end installation

=over

=item Apache::Request

=item Apache2::Request

=back

The fact that these are marked "(optional)" is just to help the installer
determine CPAN dependencies. Trust us, one or the other of these B<is>
required. Either one of these is optional, however:

=over

=item Apache::SizeLimit (optional)

=item Apache2::SizeLimit (optional)

=back

=begin installation

END Apache

END MODULE LIST

=end installation

=item *

Apache 1.3.34 or later or Apache 2.0.55 or later

=item *

mod_perl 2.xx or mod_perl 1.xx - Apache/Perl Integration

=item *

PostgreSQL 7.3.0 or MySQL 5.0.3

=item *

Expat 1.95.0

=item *

OpenSSL 0.9.6b (optional)

=item *

mod_ssl 2.8.4-1.3.xx - Apache Interface to OpenSSL (optional)

=item *

apache_ssl 1.3.xx+ssl_1.xx Apache SSL (optional)

=item *

mod_gzip - Gzip page compression (optional)

=item *

htmlArea 3.0 or later (optional)

=item *

Xinha WYSIWYG editor (optional)

=item *

FCKeditor WYSIWYG editor (optional)

=item *

JS-Quicktags WYSIWYG editor (optional)

=item *

GNU Aspell 0.50 or later (optional)

=back

=head1 Installation

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

=head2 Perl

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:

=over

=item *

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

=item *

Gunzip and untar the sources.

=item *

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:

=over

=item -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.

=item  -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".

=item -des

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

=back

=back

=head2 OpenSSL (optional)

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

=over

=item *

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

=item *

Gunzip and untar the sources.

=item *

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

=back

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

=head2 Apache SSL Support (Optional)

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

=head3 Apache Interface to OpenSSL (mod_ssl)

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

=over

=item *

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

=item *

Gunzip and untar the sources.

=item *

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 C<--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 C<--with-crt> and C<--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.

=back

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

=head3 Apache-SSL

=over

=item *

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

=item *

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

=item *

Run the FixPatch script.

=item *

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.

=back

=head2 Apache/Perl (mod_perl)

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

=over

=item *

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

=item *

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

=item *

Gunzip and untar the Apache and mod_perl sources.

=item *

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

=back

=head2 Apache

Before continuing, consult the F<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:

=over

=item --with-layout=Apache

This option selects the classical Apache path layout.

=item --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.

=item --enable-module=ssl (optional)

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

=item --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.

=item --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.

=item --disable-shared=perl

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

=back

=over

=item *

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

=item *

If you plan to use SSL you'll need to install the SSL certificates
before you install Apache.  If you compiled OpenSSL with the
C<--with-crt> and C<--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.

=item *

Finally, install Apache:

  make install

=item *

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 C<APXS> environment variable while installing it so
that tests pass:

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

=back

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

  /usr/local/apache/bin/apachectl configtest

=head2 PostgreSQL

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 C<locate postgresql.conf> to find it) and turn on
the tcpip_socket option:

  tcpip_socket = true

Otherwise, here are the installation details:

=over

=item *

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

=item *

Gunzip and untar the sources.

=item *

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 (note: I use bash with no
problem), 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

=item *

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: C<--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.

=item *

Install PostgreSQL:

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

=item *

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

=item *

Initialize the PostgreSQL database. Be sure to pass the directory you just
created to the C<-D> command.

  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"

=item *

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

=item *

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

  cd docs
  make install

=item *

Don't forget to install the DBD::Pg perl module! If its F<Makefile.PL>
can't find your installed version of PostgreSQL, you'll need to set the
C<POSTGRES_INCLUDE> and C<POSTGRES_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

=back

And now PostgreSQL is ready to go!

=head2 Perl Modules

There are quite a few Perl modules required by Bricolage (see
L<"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:

=over

=item *

Download the package sources.

=item *

Gunzip and untar the sources.

=item *

Change to the source directory and execute these commands:

  perl Makefile.PL
  make
  make test
  make install

=back

=head2 Bricolage

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

=over

=item *

Download the latest L<Bricolage
sources|http://www.bricolagecms.org/downloads/>.

=item *

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

=item *

Build Bricolage:

  perl Makefile.PL

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. Most of these
answers can be overridden in F<conf/bricolage.conf> or F<conf/httpd.conf>.
Here is more information on some of the questions (some obvious questions
were skipped):

=over

=item Apache User

The Apache user, set by the 'User' directive in F<conf/httpd.conf>.

=item Apache Group

The Apache group, set by the 'Group' directive in F<conf/httpd.conf>.

=item Apache Port

The Apache port, set by the 'Port' directive in F<conf/httpd.conf>.

=item Apache Server Name

The Apacher server name, set by the 'ServerName' directive in F<conf/httpd.conf>.

=item Do you want to use SSL?

If the installation program found either F<mod_ssl> or F<mod_apache_ssl>, it
will ask this question. If you use one of these modules, your Bricolage will
be served over a secure connection. See the L<INSTALLATION|/"INSTALLATION">,
L<Apache Configuration|/"Apache Configuration">, and L<INSTALLATION
ISSUES|/"INSTALLATION ISSUES"> sections of this document for more information
on SSL support.

=item Postgres Root Username

A postgresql user which has permissions to CREATE DATABASE, CREATE USER,
and GRANT a user permissions in the database.

=item Postgres System Username

I'm not sure how this is different from the root user.

=item Bricolage Postgres Username

The postgresql user that you normally run Bricolage under. This user only has
CREATE, DELETE, UPDATE, and SELECT permissions on the objects B<within> the
bricolage database.

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'.

=item Bricolage Database Name

Any (valid postgresql) name you want for your bricolage database.

=item Postgres Database Server Hostname & Port

The hostname and port of the server where your postgresql database is located.
The default is localhost, through local (non TCP) sockets.

=item Single vs. Multi Installation

It has nothing to do with multi-sites.
If you choose 's', that means that it'll be difficult to install
more than one bricolage on the same machine because it'll put the
libraries, perldocs, etc. in standard locations (F</usr/lib/perl5>,
F</usr/man/man>? or something); whereas if you choose 'm', it'll put
everything under one directory, like F</usr/local/bricolage>, so the
second bricolage you install could be under F</usr/local/bric2> or
whatever and they won't conflict. I'd recommend 'm' just because
it's centralized so you know where everything is installed.

=item Bricolage Root Directory

What $ENV{BRICOLAGE_ROOT} will be set to.

=item Temporary Directory

Where temporary files, like cache files, are written.

=item Perl Module Directory

Where Perl modules will be installed.

=item Executable Directory

Where executables like bric_soap will be installed.

=item Man-Page Directory

Where man pages for the Perl modules will be installed. You can put '!'
in order to not install the man pages (this is intended more for developers,
not users, of Bricolage).

=item Log Directory

Where F<access_log> and F<error_log> will be written to.

=item PID File Location

Where Apache's PID file will be written each time Bricolage is started
(and removed when it's not running).

=item Mason Component Directory

Where Mason components for the Bricolage UI are put. Also, its F<data/media>
subdirectory is where media files are stored. See also the C<MASON_COMP_ROOT>
directive in F<conf/bricolage.conf>. The Apache User has to have write permission
to this directory.

=item Mason Data Directory

Where the Mason data directory is located. This stores things like
cached Mason components See also the C<MASON_COMP_ROOT> directive in
F<conf/bricolage.conf>. The Apache User has to have write permission
to this directory.

=back

=item *

Install Bricolage (as root):

  make
  make install

=back

If you run into a problem, the fastest way of getting help is to search the
L<bricolage-general
archive|http://marc.theaimsgroup.com/?l=bricolage-general>. Failing that,
please send an email to the mailing list itself at
L<users@lists.bricolage.cc|mailto:users@lists.bricolage.cc>. Please make sure
that you describe your problem as concisely as possible. Questions like "My
installation fails, please help" will not help other users to help you. If
other uses confirm that the problem you're experiencing is a bug and suggest
that you send a bug report, file it via our L<bug
tracker|http://bugs.bricolagecms.org/>. Include a copy of all F<*.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.

=head2 Bricolage (Manual Installation)

Here's how to install Bricolage manually.

=over

=item *

Download the latest L<Bricolage
sources|http://www.bricolagecms.org/downloads/>. Decompress them into
F</usr/local/bricolage>.

=item *

Change directories into /usr/local/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 'db_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 L<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<-i> option.

=item *

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
F<httpd.conf> file (an example is provided in F<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 wish to
manually configure your httpd daemon, set the C<MANUAL_APACHE> directive in
F<conf/bricolage.conf>. This directive will force the startup process to write
out the Bricolage virtual host configuration to
F<C<$BRICOLAGE_ROOT>/conf/vhosts.conf>, and then this file will be
automatically rewritten and included on each startup operation. If you change
this line

  PerlModule Bric::App::ApacheConfig

to

  PerlModule Bric::App::ApacheStartup

then only the contents of the F<httpd.conf> file specified in
F<bricolage.conf> via the C<APACHE_CONF> direcive will be passed to the httpd
daemon.

You can also configure Bricolage to run on a virtual host. See
L<"CONFIGURATION"> below.

=item *

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

  /usr/local/bricolage/bin/bric_apachectl start

=item *

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 B<change the
admin login password> so that others who download the Bricolage sources can't
just use that login to get into I<your> installation! Now use the admin login to
create other user accounts.

=back

=head2 htmlArea (Optional)

To install htmlArea, an optional application that offers WYSIWYG editing in
the Bricolage UI, simply L<download
it|http://www.dynarch.com/projects/htmlarea/>, decompress the files, and move
them to the F<comp/media/wysiwyg/htmlarea> directory in your Bricolage root.

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

You will also need to enable the C<ENABLE_WYSIWYG> and C<WYSIWYG_EDITOR>
F<bricolage.conf> directives (see L<UI Configuration|/"UI Configuration">).

=head2 Xinha (Optional)

To install Xinha, an optional application that offers WYSIWYG editing in the
Bricolage UI, simply L<download it|http://www.xinha.org/>, decompress the
files, and move them to the F<comp/media/wysiwyg/xinha> directory in your
Bricolage root.

You will also need to enable the C<ENABLE_WYSIWYG> and C<WYSIWYG_EDITOR>
F<bricolage.conf> directives (see L<UI Configuration|/"UI Configuration">).

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

=head2 FCKeditor (Optional)

To install FCKeditor, an optional application that offers WYSIWYG editing in
the Bricolage UI, simply L<download it|http://www.fckeditor.net/>, decompress
the files, and move them to the F<comp/media/wysiwyg/fckeditor> directory in
your Bricolage root.

You will also need to enable the C<ENABLE_WYSIWYG> and C<WYSIWYG_EDITOR>
F<bricolage.conf> directives (see L<UI Configuration|/"UI Configuration">).

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

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

To this:

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

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

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

To point to the correct loation of aspell:

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

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

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

  <html>
  <head>

To these:

  print header, <<EOF;
  <html>
  <head>

And finally, you might also need to make the F<spellchecker.pl> file
executable:

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

=head2 JS-Quicktags (Optional)

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

You will also need to enable the C<ENABLE_WYSIWYG> and C<WYSIWYG_EDITOR>
F<bricolage.conf> directives (see L<UI Configuration|/"UI Configuration">).

=head2 GNU Aspell (Optional)

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

=head1 Upgrading

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

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

  export BRICOLAGE_ROOT=/opt/bricolage

Next, stop the server:

  $BRICOLAGE_ROOT/bin/bric_apachectl stop

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

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

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

Delete all existing Mason object files and temporary files:

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

Run the upgrade scripts needed for upgrading to the new version. The upgrade
scripts are in the F<inst/upgrade/> directory. Run each script in all of the
version number directories in the order given in F<inst/versions.txt>.
For example, to upgrade from 1.6.13 to 1.8.1, run each of the scripts in
F<1.6.13/>, F<1.7.5/>, F<1.6.14/>, F<1.8.0/>, and F<1.8.1/> -- B<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 B<not> to copy example templates, as they may overwrite
your own templates. You're best off moving the contents of F<data/> out
of the way.

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

Now edit the new F<bricolage.conf> file to match your old settings using the
F<bricolage.conf.old> settings you saved as a guide. Do the same thing with
F<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 L<"CONFIGURATION"> section below for details.

Now, start up Bricolage and enjoy the new features!

  $BRICOLAGE_ROOT/bin/bric_apachectl start

=head2 Switching to Apache 2

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

  cd $BRICOLAGE_ROOT/conf
  mv httpd.conf httpd.conf.orig
  cp httpd.conf.def httpd.conf
  mv bricolage.conf bricolage.conf.orig
  cp bricolage.conf.def bricolage.conf

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

=head1 Configuration

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

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

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

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

=head2 Apache Configuration

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

B<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.

=over

=item *

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

=item *

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

=item *

B<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 C<APACHE_CONF> (using
Listen, Port, or BindAddress).

=item *

B<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.
B<Note:> The C<LISTEN_PORT> directive I<must> be set to 80 if C<SSL_ENABLE> is
on. The Bricolage server will not start if C<SSL_ENABLE> is on and
C<LISTEN_PORT> is set to a value other than 80.

=item *

B<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 C<NAME_VHOST> and
C<VHOST_SERVER_NAME> parameters) for the SSL encryption support. Use in tandem
with the C<SSL_CERTIFICATE_KEY_FILE> direcive Defaults to an empty value.

=item *

B<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 C<NAME_VHOST> and
C<VHOST_SERVER_NAME> parameters) for the SSL encryption support. Use in
tandem with the C<SSL_CERTIFICATE_FILE> direcive. Defaults to an empty value.

=item *

B<ALWAYS_USE_SSL:> With C<SSL_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. If
you're using Briciolage behind a reverse proxy server and using SSL, you will
also have to enable B<ALWAYS_USE_SSL> so that recirects will work properly.

=item *

B<SKIP_SSL_REDIRECT:> When SSL is enabled and C<ALWAYS_USE_SSL> is not,
Bricolage will switch back and forth between SSL and non-SSL connections as
appropriate. Mostly this means that it uses SSL for pages with password
information, and non-SSL otherwise. If you don't want Bricolage to do this
kind of switching, enable C<SKIP_SSL_REDIRECT>. This will be most useful if
Bricolage lives behind a reverse proxy server that handles the SSL stuff
itself.

=item *

B<NAME_VHOST:> The IP address on which the virtual host name specified in the
C<VHOST_SERVER_NAME> directive will respond. Note that the syntax for this
directive is identical to the syntax for Apache's C<NameVirtualHost> directive.
Also note that the VirtualHost record that Bricolage creates will be for
C<NAME_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 C<VirtualHost> declarations. Also note that if the C<SSL_ENABLE>
is turned on, then a C<NAME_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.

=item *

B<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.

=item *

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

=item *

B<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 Apache configuration 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
F<C<$BRICOLAGE_ROOT>/conf/vhosts.conf> and include it in the configuration
using the Apache C<Include> directive. If no changes are made to
F<C<$BRICOLAGE_ROOT>/conf/httpd.conf>, then this file will be automatically
included on each startup by the last line of the F<httpd.conf> file:

  PerlModule Bric::App::ApacheConfig

If this line is changed to

  PerlModule Bric::App::ApacheStartup

then only the contents of the F<httpd.conf> specified by the C<APACHE_CONF>
directive will be passed to the httpd daemon -- Bricolage will do no dynamic
configuration. In such a case, you'll want to either C<Include> the generated
F<vhosts.conf> file (which you can edit as you wish), or incorporate its
contents directly into your F<httpd.conf> file.

Note that under Apache 2, the F<vhosts.conf> file is B<always> created,
regardles of the setting of C<MANUAL_APACHE>.

=item *

B<ENABLE_GZIP:> Turn on this feature if you have the mod_gzip Apache 1 module
or the mod_deflate Apache 2 module installed and loaded in your F<httpd.conf>
file and want it to compress the the UI pages. Pages will be as much as
fifteen times smaller, with minimal extra server load, resulting in faster
load times and less bandwidth consumption. Disabled by default.

=back

=head2 Database Configuration

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

=over

=item *

B<DB_NAME:> The name of the Bricolage database. Defaults to "sharky" if not
specified.

=item *

B<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.

=item *

B<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.

=item *

B<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 C<pgimport> (see above). Defaults to
"castellan" if not specified.

=item *

B<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 C<pgimport> (see above). Defaults to
"nalletsac" if not specified.

=back

=head2 System User Configuration

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

=over

=item *

B<SYS_USER:> The system user as whom Bricolage runs. Must be the same as the
C<User> directive used in the Apache configuration file specified in the
C<APACHE_CONF> configuration directive. Defaults to "nobody" if not specified.

=item *

B<SYS_GROUP:> The system group of which SYS_USER is a member. Must be the same
as the C<Group> directive used in the Apache configuration file specified in the
C<APACHE_CONF> configuration directive. Defaults to "nobody" if not specified.

=back

=head2 Temp Directory Configuration

=over

=item *

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

=back

=head2 Mason Configuration

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

=over

=item *

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

=item *

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

=item *

B<MASON_STATIC_SOURCE:> Set this directive to a true value (1, Yes, or On) to
enable static source caching in the Bricolage UI. This can save many stats per
request, and thus increase the performance of Bricolage. Disabled by default.

=back

=head2 Burner Configuration

=over

=item *

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

=item *

B<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.

=item *

B<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 $writer. See the XML::Writer documentation for more information.
Defaults to off if unspecified.

B<Note>: Only the Mason burner supports XML::Writer.

=item *

B<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.

B<Note>: Only the Mason burner supports XML::Writer.

=item *

B<MASON_INTERP_ARGS:> This directive passes arguments to the
L<HTML::Mason::Interp|HTML::Mason::Interp> constructor in
L<Bric::Util::Burner::Mason|Bric::Util::Burner::Mason>'s C<burn_one> method,
which means it affects the Mason interpreter for your templates. See
L<HTML::Mason::Interp|HTML::Mason::Interp> for the list of parameters you can
pass to the C<new> method. Defaults to no arguments if not specified.

B<Note>: Only the Mason burner supports the HTML::Mason::Interp arguments.

B<TT_OPTIONS:> This directive passes arguments to the L<Template|Template>
constructor in
L<Bric::Util::Burner::TemplateToolkit|Bric::Util::Burner::TemplateToolkit>'s
C<burn_one> method, which means it affects the Template Toolkit object for
your templates. See L<Template|Template> for the list of parameters you can
pass to the C<new> method. Defaults to no arguments if not specified.

B<Note>: Only the Template Tooolkit burner supports the Template Toolkit
options.

=back

=head2 Authentication Configuration

These directives set rules for Bricolage user authentication.

=over

=item *

B<AUTH_ENGINES:> A space-delimited list of the authentication engines to try,
in the order listed, when a user attemptes to login to Bricolage. The
supported engines are "Internal", for Bricolage's default, internal
authentication scheme, and "LDAP", for authentication against an LDAP server.
If you include "LDAP" in your list of authentication engines, you must also
configure the L<LDAP directives/"LDAP Configuration">. Defaults to "Internal".

Note that the C<AUTH_ENGINES> directive can contain any number of supported
authentication engines, and each will be used by the user class in turn. For
example, if have this line in F<bricolage.conf>:

  AUTH_ENGINES = Internal LDAP

Then, when the C<check_password()> method is called on a user object, the user
class will first attmpt to authenticate the user using
L<Bric::Util::AuthInternal|Bric::Util::AuthInternal> module's
C<authenticate()> method. If it returns true, then C<check_password()> will
return true and the user will be considered to be authenticated. If
C<authenticate()> returns false, the user class will then call the
C<authenticate()> method on the L<Bric::Util::AuthLDAP|Bric::Util::AuthLDAP>
module, and return true or false depending on whether the call to the
C<authenticate()> method returns true or false.

On the other hand, if you have this line in F<bricolage.conf>:

  AUTH_ENGINES = LDAP Internal

Then the user class will attempt to authenticate using the LDAP auth module
and then fall back to the Internal auth module if the LDAP authentication
fails.

=item *

B<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.

=item *

B<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:

=item *

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

=item *

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

=back

=head2 LDAP Configuration

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

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

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

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

=over

=item *

B<LDAP_SERVER:> The domain name or IP address of the server running the
LDAP service. Defaults to "localhost".

=item *

B<LDAP_VERSION:> The version of the LDAP standard supported by the server
specified in the C<LDAP_SERVER> directive. Defaults to 3.

=item *

B<LDAP_USER and LDAP_PASS:> By default, Bricolage will bind to the LDAP server
anonymously before attempting to authenticate a user. If your LDAP server does
not allow anonymous bindings, set C<LDAP_USER> to the DN of a user who can
bind to the LDAP server and search for users. Set C<LDAP_PASS> to the password
for that user. If an anonymous bind can search for users, leave these two
directives unspecified or set to 0 (zero). Both are unspecified by default.

=item *

B<LDAP_BASE:> The base DN to use when searching for user records, usually
something like "ou=Users,dc=example,dc=com". Defaults to an empty string.

=item *

B<LDAP_UID_ATTR:> The attribute of user records that contains the user ID.
Defaults to "uid".

=item *

B<LDAP_FILTER:> A filter to use when searching for user records. Defaults to
"(objectclass=*)".

=item *

B<LDAP_GROUP and LDAP_MEMBER_ATTR:> If you'd like to allow only the members of
a particular LDAP group to login to Bricolage, set C<LDAP_GROUP > to the DN of
that group (Something like "cn=Bricolage,ou=Group,dc=example,dc=com"), and set
C<LDAP_MEMBER_ATTR> to the name of the Attribute of that group that represents
members, such as the default, "uniqueMember". If these directives are not
specified or are set to 0 (Zero). C<LDAP_GROUP> is unspecified by default.

=item *

B<LDAP_TLS and LDAP_SSL_VERSION:> Enable this boolean directive if your LDAP
server supports TLS and you'd like Bricolage to use encrypted communications
with the LDAP server. Disabled by default. Set C<LDAP_SSL_VERSION> to the
version of SSL supported by your LDAP server. Defaults to 3.

=back

=head2 Distribution Configuration

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

=begin comment

Will need to write a lot more documentation about this at some point -- and need
think about saving media to /stage instead of /media/assets, too.

=end comment

=over

=item *

B<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.

=item *

B<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.

=item *

B<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.

=item *

B<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).

=item *

B<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.

=item *

B<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 L<libssh2|http://www.libssh2.org/>. You will also need to
install the Net::SSH2 module from the CPAN. If you've installed your own SSL
toolkit such as OpenSSL, make sure that libssh2 is using the same version as
your Bricolage instance.

Login to the remote server in order to initialize F<~/.ssh/known_hosts> before
using the SFTP mover. You might also need to create the directory F</.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
F</bin/false> and ssh falls back to F</> as the home directory).

=item *

B<SFTP_MOVER_CIPHER:> This directive forces the SFTP mover (if enabled by the
C<ENABLE_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::SSH2 documentation
for a complete list of supported ciphers for SSH-2. As of this writing, the
suppported ciphers are "aes256-cbc", "aes192-cbc", "aes128-cbc", "blowfish-cbc"
"arcfour", "cast128-cbc", "3des-cbc" and "none". The default SSH-2 cipher is
"aes256-cbc".

=item *

B<SFTP_KEY_TYPE, SFTP_PUBLIC_KEY_FILE, and SFTP_PRIVATE_KEY_FILE:> These
directives set the key-based authentication variables. As of this writing,
Net::SSH2 supports SFTP_KEY_TYPE values of 'ssh-rsa' and 'ssh-dss'. You
may need to adjust the permissions of the key files so they are readable
by C<SYS_USER>. The username and private key password (if any) must be
entered in the Bricolage interface when setting up the destination.

=item *

B<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 the L<WebDAV
site|http://www.webdav.org/> for information on the WebDAV protocol.

=item *

B<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 C<DIST_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 L<bric_queued|bric_queued> or with a
specially tuned instance of Bricolage to limit the system resources given over
to publishing.

The new queue daemon, F<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.

=item *

B<FTP_UNLINK_BEFORE_MOVE:> This directive must be set to Yes for some FTP and
SFTP servers (e.g. pure-ftpd has been reported to need this and sshd less then
version 5 requires 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.

=item *

B<PUBLISH_RELATED_ASSETS:> Set C<PUBLISH_RELATED_ASSETS> to no/off/0 so that,
when publishing from a publish desk, related assets will not be published.
Defaults to "yes".

=item *

B<PUBLISH_RELATED_FAIL_BEHAVIOR:> When C<PUBLISH_RELATED_ASSETS> is enabled,
the publish process will fail if any of the related assets cannot be published
automatically, due to being checked out or not on a publish desk. If you want
the process to just supply warnings but otherwise allow the publish to
succeed, then set C<PUBLISH_RELATED_FAIL_BEHAVIOR> to "warn". Defaults to
"fail".

=back

=head2 UI Configuration

=over

=item *

B<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.

=item *

B<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.

=item *

B<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.

=item *

B<BLOB_SEARCH:> Allows the C<data_text> parameter to the C<list()> and friends
methods of
L<Bric::Biz::Asset::Business::Story|Bric::Biz::Asset::Business::Story> and
L<Bric::Biz::Asset::Business::Media|Bric::Biz::Asset::Business::Media> to
search large fields (such as paragraphs) as well as short fields (like
headers). Note that this can make such searches much more expensive if you
have more than a few thousand paragraph-type fields in your documents.
Defaults to "Off" if not specified.

=item *

B<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.

=back

=head2 Media Configuration

=over

=item *

B<AUTO_PREVIEW_MEDIA>. This directive determines whether files uploaded to
Media documents are automatically distributed to all relevant preview servers
when the media document is saved, or whether they must be previewed manually
after they're uploaded. Defaults to "Off" if not specified.

=item *

B<MEDIA_UPLOAD_LIMIT:> Set this to a number, so that no files larger than that
number of kilobytes can be uploaded. Defaults to 0, which means no limit.

=item *

B<MEDIA_UNIQUE_FILENAME:> When this directive is enabled, Bricolage will
generate a unique eight-character MD5 hash as the name of each new media
file. The file name suffix will be retained as it was loaded. Disabled by
default.

=item *

B<MEDIA_FILENAME_PREFIX:> When set, uses the value as a character string to
prefix to unique media filenames. Disabled by default.

=back

=head2 UI Configuration

=over

=item *

B<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.

=item *

B<CATEGORY_MIN_CHARS AND CATEGORY_MIN_CHARS_TMPL:> These directives tell the
UI how many characters the user needs to type in before it suggests a list
of possible options. By default this is 1, since to begin with a Bricolage
intallation wont have many categories. But if you start to find that it's
taking to long to suggest categories because there are just too many (and
they all start with the first character, "/"), try changing it to 2.

=item *

B<ENABLE_CATEGORY_BROWSER:> Category browser setting. Enable this directive to
make the Media and Story profiles use the category browser. 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.

=item *

B<RELATED_MEDIA_UPLOAD:> This directive allows users to upload media files
directly into a related media element profile if they have permission to
create media and to access a media workflow. This makes it a much simpler
process for editors to quickly associate media with story documents. The
uploaded media files will be created based on the media type element selected
from a select list, and given the same category, cover date, and priority as
the current document. Enabled by default.

=item *

B<ENABLE_WYSIWYG and WYSIWYG_EDITOR:> These directives control the WYSIWYG
editor in Bricolage. Currently supported are htmlArea, Xinha (a fork of
htmlArea), and FCKeditor. After installing the editor of your choice (see
dependency info above), set C<WYSIWYG_EDITOR> appropriately.

=item *

B<HTMLAREA_TOOLBAR and XINHA_TOOLBAR:> You can specify exactly what shows up
in your Xinha/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:

=over

=item fontname

=item fontsize

=item formatblock

=item bold

=item italic

=item underline

=item strikethrough

=item subscript

=item superscript

=item copy

=item cut

=item paste

=item undo

=item redo

=item linebreak

=item justifyleft

=item justifycenter

=item justifyright

=item justifyfull

=item lefttoright

=item righttoleft

=item insertorderedlist

=item insertunorderedlist

=item outdent

=item indent

=item forecolor

=item hilitecolor

=item inserthorizontalrule

=item createlink

=item insertimage

=item inserttable

=item htmlmode

=item popupeditor

=item showhelp

=item about

=back

In addition to the button specifications, Xinha and htmlArea configurations
support a few other toolbar configuration options:

=over

=item space

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

=item separator

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

=item linebreak

Starts a new line in the toolbar. Subsequent controls will be inserted on the
new line.

=back

=item *

B<FCKEDITOR_CONFIG:> You can fully control FCKeditor configuration using this
directive. Simply enter all of the JavaScript code to configur FCKeditor on a
single line, and Bricolage will tell FCKeditor to use it. Consult the
L<FCKeditor documenation|http://wiki.fckeditor.net/> for details. By default,
Bricolage sets up a very simple toolbar for FCKeditor (overriding its
"Default" toolbar set).

=back

=head2 Language Configuration

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

=over

=item *

B<LOAD_LANGUAGES> and B<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. C<LOAD_LANGUAGES> defaults to "en_us" and
C<LOAD_CHAR_SETS> defaults to "UTF-8".

=back

=head2 Time Zone Configuration

=over

=item *

B<LOAD_TIME_ZONE:> Tell Bricolage which time zones to pre-load. If you plan on
using any time zones other than UTC, 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. Defaults to "UTC".

=back

=head2 Alert Configuration

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

=over

=item *

B<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.

=item *

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

=item *

B<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.

=begin comment

It might be worthwhile in a future version to allow Alert Type owners to set
this themselves.

=end comment

=back

=head2 Image Thumbnail Configuration

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

=over

=item *

B<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 F<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
L<license|http://artist.kde.org/new/license.html#others> for the graphic.
Enabled by default.

=item *

B<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.

=back

=head2 File Naming Configuration

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

=over

=item *

B<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.

=item *

B<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.

=back

=head2 Relateds POD Tag

=over

=item *

B<RELATED_DOC_POD_TAG:> Controls the type of related media and related story
POD tags that will be generated by the C<serialize_to_pod()> method of
L<Bric::Biz::Element::Container|Bric::Biz::Element::Container> and therefore
the "Bulk Edit" interface in the UI. The tags have the format of
C<=related_story_*> or C<=related_media_*>, where "*" is drawn from this
directive and can be any one of: "uuid", "uri", "url", or "id". Defaults to
"uuid" if not specified.

=back

=head2 Story URI configuration

=over

=item *

B<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.

=back

=head2 Perl Loading Configuration

=over

=item *

B<PERL_LOADER:> Pass in a line of Perl code, and it will be executed at
startup time in the same namespace as your templates run in. This is so that
you only have to load stuff that you might often use once, such as
L<CGI.pm|CGI.pm> or L<Apache::DBI|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 avoid loading any variables that don't
survive forks very well (such as database handles). Defaults to load nothing
if not specified.

B<Note>: Only the Mason, Template Toolkit, and PHP burners can directly use
any symbols exported by code executed in the C<PERL_LOADER> directive. TT can
only use unique symbols (that is, if the code that runs exports a hash and a
scalar with the same names, only the hash will be available in TT templates),
while PHP can use imported functions only with PHP::Interpreter 1.1.0 or
later.

=back

=head2 Virtual FTP Server Configuration

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

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

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

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

=over

=item *

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

=item *

B<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.

=item *

B<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.

=item *

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

=item *

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

=item *

B<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.

=item *

B<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.

=back

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

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

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

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

=head1 Directory Permissions

As noted above, you need to supply the user and group names under which
Bricolage will run. It's important that this user have permission to write to
certain directories, as Bricolage will store some data files on the file system.
So be sure to grant to SYS_USER and/or SYS_GROUP the necessary permissions to
write to the directories identified by the MASON_DATA_ROOT, BURN_ROOT, and
BURN_DATA_ROOT configuration directives. Also, Bricolage stores Media asset
files in C<$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

=head1 Installation Issues

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

=head2 Building SSL Certificate

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

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

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

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

=over

=item 1.

Shut down Apache if it's running:

  /usr/local/bricolage/bin/bric_apachectl stop

=item 2.

Delete the existing installation of Apache:

  rm -rf /usr/local/apache*

=item 3.

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

=item 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.

=item 5.

Execute the following command:

  make install

This will install Apache and the new certificate.

=item 6.

Start Apache again:

  /usr/local/bricolage/bin/bric_apachectl start

=back

=head1 System Administration

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

=head2 Database

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 L<Bric::DBA>
for more detail.

=head2 Application

Bricolage stores all of its application files -- including the UI elements and
Perl libraries -- in C<$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 C<$BRICOLAGE_ROOT/lib>,
although mostly they will only be read on startup.

Bricolage creates a great many files on the filesystem, too, however. The
C<$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
C<$BURN_ROOT/stage> and C<$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 C<$MASON_COMP_ROOT/data/preview> directory gets formatted story files copied
to it from C<$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 C<$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 C<TEMP_DIR/bricolage/session> and
C<TEMP_DIR/bricolage/lock>. These directories should stay relatively
free of cruft, as the session files are regularly deleted when users
logout or their login sessions expire and they attempt to log back
in. (However, in some cases we've noticed a buildup of files in the
lock directory.)

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

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

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

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

=head1 Cloing an Installation

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

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

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

  make clone

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

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

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

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

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

=head1 Installation/Startup Problems

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

There is also an L<on-line
copy|http://www.bricolagecms.org/docs/Bric/FAQ.html>.

=head1 Author

David Wheeler <david@justatheory.com>

=head1 See Also

L<Bric|Bric>

=cut