Bric::Admin(3p)       User Contributed Perl Documentation      Bric::Admin(3p)



NAME
       Bric::Admin - Bricolage System Administration Guide.

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2007-01-17 08:58:24 +0100 (Wed, 17 Jan 2007) $

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

QUICK INSTALLATION INSTRUCTIONS
       Follow these instructions if you are both impatient and expert.

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

       1.  Install Perl 5.8.0 or greater.

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

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

       4.  In the Bricolage source directory:

             perl Makefile.PL
             make
             make test

           And then as root:

             make install

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

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

         make INSTALL_VERBOSITY=QUIET
         make test
         make INSTALL_VERBOSITY=QUIET install

       Bricolage will do it's best to discover most information by itself, and
       exist with an error when it cannot.

       This feature wil likely prove most useful for automated or batch
       installations.

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

       o   Perl 5.8.0.

       o   Perl Modules:

           Storable
           Time::HiRes
           Unix::Syslog
           Net::Cmd
           Devel::Symdump
           DBI 1.18
           Error
           Cache::Cache
           Cache::Mmap
           Digest::MD5
           Digest::SHA1 2.01
           URI
           HTML::Tagset
           HTML::Parser
           MIME::Base64
           MIME::Tools
           Mail::Address
           XML::Writer
           LWP
           Image::Info
           MLDBM
           Params::Validate
           Exception::Class 1.12
           Class::Container 0.09
           Apache::Request 1.0
           HTML::Mason 1.23
           DBD::Pg 1.22
           DB_File
           Apache::Session 1.54
           Test::Harness 2.03
           Test::Simple
           Test::MockModule 0.04
           Test::File::Contents 0.02
           Text::Balanced
           XML::Parser 2.34
           XML::Simple
           IO::Stringy
           SOAP::Lite
           File::Temp
           Text::LevenshteinXS
           Locale::Maketext
           Test::Class 0.04
           Params::CallbackRequest 1.10
           MasonX::Interp::WithCallbacks 1.10
           Safe
           DateTime 0.21
           DateTime::TimeZone 0.2601
           Term::ReadPassword
           Data::UUID
           List::Util
           List::MoreUtils
           Text::Diff
           Text::Diff::HTML 0.02
           Text::WordDiff
           URI::Escape
           Scalar::Util
           HTML::Template (optional)
           HTML::Template::Expr (optional)
           Template 2.14 (optional)
           PHP::Interpreter (optional)
           Encode (optional)
           Pod::Simple (optional)
           Test::Pod 0.95 (optional)
           Devel::Profiler 0.03 (optional)
           Apache::SizeLimit (optional)
           Net::FTPServer (optional)
           Net::SFTP 0.08 (optional)
           Math::BigInt::GMP (optional)
           HTTP::DAV (optional)
           Crypt::SSLeay (optional)
           Imager (optional)
           Text::Aspell (optional)
           XML::DOM (optional)
           CGI (optional)
       o   Apache 1.3.12

       o   mod_perl 1.25 - Apache/Perl Integration

       o   PostgreSQL 7.3.0

       o   Expat 1.95.0

       o   OpenSSL 0.9.6b (optional)

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

       o   apache_ssl 1.3.22+ssl_1.47 Apache SSL (optional)

       o   mod_gzip - Gzip page compression (optional)

       o   htmlArea 3.0 or later (optional)

       o   Xinha WYSIWYG editor (optional)

       o   GNU Aspell 0.50 or later (optional)

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

   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:

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

       o   Gunzip and untar the sources.

       o   Change to the source directory and execute these commands:

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

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

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

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

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

   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:

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

       o   Gunzip and untar the sources.

       o   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

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

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

       Apache Interface to OpenSSL (mod_ssl)

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

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

       o   Gunzip and untar the sources.

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

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

       Apache-SSL

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

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

       o   Run the FixPatch script.

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

   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:

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

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

       o   Gunzip and untar the Apache and mod_perl sources.

       o   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

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

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

       --with-layout=Apache
           This option selects the classical Apache path layout.

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

       --enable-module=ssl (optional)
           If you're including SSL support via mod_ssl, this option compiles
           it in.

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

       --activate-module=src/modules/perl/libperl.a
           This option compiles in mod_perl. The library it points to was
           installed by the mod_perl make process.

       --disable-shared=perl
           This option ensures that mod_perl will be statically compiled into
           Apache, rather than as a DSO.

       o   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

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

       o   Finally, install Apache:

             make install

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

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

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

         /usr/local/apache/bin/apachectl configtest

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

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

         tcpip_socket = true

       Otherwise, here are the installation details:

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

       o   Gunzip and untar the sources.

       o   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

       o   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: "--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.

       o   Install PostgreSQL:

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

       o   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

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

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

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

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

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

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

             cd docs
             make install

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

       And now PostgreSQL is ready to go!

   Perl Modules
       There are quite a few Perl modules required by Bricolage (see
       "PACKAGES" above for a list). The easiest way to install them all is to
       let Bricolage's installation system handle it using the 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:

       o   Download the package sources.

       o   Gunzip and untar the sources.

       o   Change to the source directory and execute these commands:

             perl Makefile.PL
             make
             make test
             make install

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

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

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

       o   Build Bricolage:

             make

           This step will check your system for all required packages.  It
           will also ask you questions regarding your installation.  In most
           cases the default answer will be correct and you can just press
           return. Most of these answers can be overridden in
           conf/bricolage.conf or conf/httpd.conf.  Here is more information
           on some of the questions (some obvious questions were skipped):

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

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

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

           Apache Server Name
               The Apacher server name, set by the 'ServerName' directive in
               conf/httpd.conf.

           Do you want to use SSL?
               If the installation program found either mod_ssl or
               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 INSTALLATION, Apache Configuration, and
               INSTALLATION ISSUES sections of this document for more
               information on SSL support.

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

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

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

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

           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.

           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 (/usr/lib/perl5,
               /usr/man/man? or something); whereas if you choose 'm', it'll
               put everything under one directory, like /usr/local/bricolage,
               so the second bricolage you install could be under
               /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.

           Bricolage Root Directory
               What $ENV{BRICOLAGE_ROOT} will be set to.

           Temporary Directory
               Where temporary files, like cache files, are written.

           Perl Module Directory
               Where Perl modules will be installed.

           Executable Directory
               Where executables like bric_soap will be installed.

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

           Log Directory
               Where access_log and error_log will be written to.

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

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

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

       o   Install Bricolage (as root):

             make install

       If you run into a problem, the fastest way of getting help is to search
       the bricolage-general archive at
       http://marc.theaimsgroup.com/?l=bricolage-general
       <http://marc.theaimsgroup.com/?l=bricolage-general>. Failing that,
       please send an email to the mailing list itself at
       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 at <http://bugzilla.bricolage.cc/>.
       Include a copy of all *.db files generated by the Makefile as well as a
       complete description of where the process failed. Then, either wait for
       us to fix the problem or try the manual installation instructions
       below.

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

   Bricolage (Manual Installation)
       Here's how to install Bricolage manually.

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

       o   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 Bric::DBA for more information on database security. You may
           want to alter the default security policy. Also, bric_import uses a
           TCP/IP connection so you may need to run postmaster with the -i
           option.

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

             PerlPassEnv BRICOLAGE_ROOT
             PerlModule Bric::App::ApacheConfig

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

             PerlModule Bric::App::ApacheConfig

           to

             PerlModule Bric::App::ApacheStartup

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

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

       o   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

       o   Try to hit the web server. If you're prompted for a login, you're
           in! If not, check the Apache error log to figure out what might
           have gone wrong.

           To start using Bricolage, log in as the default user. The user name
           is "admin" and the password is "change me now!". This user is not
           special, so you can change it however you like. The first thing you
           should do is to change the admin login password so that others who
           download the Bricolage sources can't just use that login to get
           into your installation! Now use the admin login to create other
           user accounts.

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

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

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

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

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

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

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

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

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

         export BRICOLAGE_ROOT=/opt/bricolage

       Next, stop the server:

         $BRICOLAGE_ROOT/bin/bric_apachectl stop

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

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

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

       Delete all existing Mason object files and temporary files:

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

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

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

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

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

       Now, start up Bricolage and enjoy the new features!

         $BRICOLAGE_ROOT/bin/bric_apachectl start

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.

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

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

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

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

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

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

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

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

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

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

       o   ALWAYS_USE_SSL: With "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.

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

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

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

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

             PerlModule Bric::App::ApacheConfig

           If this line is changed to

             PerlModule Bric::App::ApacheStartup

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

       o   ENABLE_GZIP: Turn on this feature if you have the mod_gzip Apache
           module installed 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.

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

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

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

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

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

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

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

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

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

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

   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.

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

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

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

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

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

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

           Note: Only the Mason burner supports XML::Writer.

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

           Note: Only the Mason burner supports XML::Writer.

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

           Note: Only the Mason burner supports the HTML::Mason::Interp
           arguments.

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

           Note: Only the Template Tooolkit burner supports the Template
           Toolkit options.

   Authentication Configuration
       These directives set rules for Bricolage user authentication.

       o   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
           "LDAP Configuration" in LDAP directives. Defaults to "Internal".

           Note that the "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 bricolage.conf:

             AUTH_ENGINES = Internal LDAP

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

           On the other hand, if you have this line in 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.

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

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

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

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

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

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

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

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

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

       o   LDAP_VERSION: The version of the LDAP standard supported by the
           server specified in the "LDAP_SERVER" directive. Defaults to 3.

       o   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
           "LDAP_USER" to the DN of a user who can bind to the LDAP server and
           search for users. Set "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.

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

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

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

       o   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
           "LDAP_GROUP " to the DN of that group (Something like
           "cn=Bricolage,ou=Group,dc=example,dc=com"), and set
           "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). "LDAP_GROUP"
           is unspecified by default.

       o   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 "LDAP_SSL_VERSION" to the version of SSL supported by your LDAP
           server. Defaults to 3.

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

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

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

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

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

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

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

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

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

       o   SFTP_MOVER_CIPHER: This directive forces the SFTP mover (if enabled
           by the "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::SSH::Perl documentation for a complete list
           of supported ciphers for SSH-1 and SSH-2. As of this writing, the
           suppported ciphers are "IDEA", "DES", "DES3", and "Blowfish" for
           SSH-1; and "arcfour", "blowfish-cbc", and "3des-cbc" for SSH-2. The
           default SSH-1 cipher is "IDEA"; the default SSH-2 cipher is
           "3des-cbc".

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

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

           The new queue daemon, bric_queued, always executes publish jobs one
           at a time, while maintaining a seperate thread for distribution
           jobs.

           If you prefer to run publish jobs from the queue concurrently, you
           can still control the use of system resources by running a second
           instance of Bricolage, setting the Apache MaxClients configuration
           directive to control the number of Apache processes which will be
           used for publishing, and thus the amount of memory and processor
           cycles.

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

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

       o   PUBLISH_RELATED_FAIL_BEHAVIOR: When "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
           "PUBLISH_RELATED_FAIL_BEHAVIOR" to "warn". Defaults to "fail".

   UI Configuration
       o   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.

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

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

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

   Media Configuration
       o   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.

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

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

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

   UI Configuration
       o   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.

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

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

       o   ENABLE_WYSIWYG and WYSIWYG_EDITOR: These directives control the
           WYSIWYG editor in Bricolage.  Currently supported are htmlArea and
           Xinha (a fork of htmlArea).  After installing htmlArea or Xinha
           (see dependency info above), set "WYSIWYG_EDITOR" appropriately.

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

           fontname
           fontsize
           formatblock
           bold
           italic
           underline
           strikethrough
           subscript
           superscript
           copy
           cut
           paste
           undo
           redo
           linebreak
           justifyleft
           justifycenter
           justifyright
           justifyfull
           lefttoright
           righttoleft
           insertorderedlist
           insertunorderedlist
           outdent
           indent
           forecolor
           hilitecolor
           inserthorizontalrule
           createlink
           insertimage
           inserttable
           htmlmode
           popupeditor
           showhelp
           about

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

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

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

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

   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.

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

   Time Zone Configuration
       o   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".

   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.

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

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

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

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

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

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

   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.

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

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

   Relateds POD Tag
       o   RELATED_DOC_POD_TAG: Controls the type of related media and related
           story POD tags that will be generated by the "serialize_to_pod()"
           method of Bric::Biz::Element::Container and therefore the "Bulk
           Edit" interface in the UI. The tags have the format of
           "=related_story_*" or "=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.

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

   Perl Loading Configuration
       o   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 CGI.pm or Apache::DBI. This should be a complete
           Perl statement that can simply be loaded, and won't pause and wait
           for anything else, as otherwise your server will never start! And
           be warned that this code is executed at server startup time, so
           avoid loading any variables that don't survive forks very well
           (such as database handles). Defaults to load nothing if not
           specified.

           Note: Only the Mason, Template Toolkit, and PHP burners can
           directly use any symbols exported by code executed in the
           "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.

   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:

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

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

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

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

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

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

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

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

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

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

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

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

         $BRICOLAGE_ROOT/data
         $BRICOLAGE_ROOT/comp/data

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

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

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

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

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

       1.  Shut down Apache if it's running:

             /usr/local/bricolage/bin/bric_apachectl stop

       2.  Delete the existing installation of Apache:

             rm -rf /usr/local/apache*

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

       4.  Execute the following command:

             make certificate TYPE=custom

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

       5.  Execute the following command:

             make install

           This will install Apache and the new certificate.

       6.  Start Apache again:

             /usr/local/bricolage/bin/bric_apachectl start

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

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

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

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

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

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

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

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

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

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

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

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

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

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

AUTHOR
       David Wheeler <david@justatheory.com>

SEE ALSO
       Bric



perl v5.12.2                      2007-01-17                   Bric::Admin(3p)
