NAME

Bric::Admin - Bricolage System Administration Guide.

VERSION

$Revision: 1.31.2.17 $

DATE

$Date: 2002/03/07 23:55:37 $

DESCRIPTION

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

PACKAGES

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

INSTALLATION

At some point, we hope to have a makefile that will automate the installation of all of these packages for you. Until then, the following instructions will get you through installing all the needed components. 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. We do recomend the following Configure commands:

-Umymalloc

This Configure command will build perl without perl's malloc. This is necessary to prevent segfaults with XML::Parser under mod_perl. [Note that XML::Parser isn't currently part of Bricolage, but will soon be, and users will likely install it, anyway.]

-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 except all the other defaults, and it will therefore provide terse output during the configuration.

Here is how to install Perl:

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 use CPAN.pm to download the latest Bundle::Bricolage package from the CPAN and use it to install all the required packages:

perl -MCPAN -e install Bundle::Bricolage

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

You can also use the CPAN module to install the modules (perldoc CPAN for details), or use ActiveState PPM packages if they're available. We do recommend that you install all but three of the required packages immediately after installing Perl, and before installing the other software packages. (You must, of course, install them all after installing Perl; otherwise, they'll be compiled under and associated with the extant perl on your system.) The three exceptions are DBD::Pg, which can only be installed after PostgreSQL has been installed (see below); and Apache::Session and libapreq, both of which can only be installed once Apache and mod_perl have been installed.

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:

make install insn't necessary because the sources will be compiled into Apache.

Apache Interface to OpenSSL (mod_ssl) (optional)

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

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

Apache/Perl (mod_perl)

Installation of mod_perl follows the usual conventions for installing Perl modules. It does require a number of Configure commands, however. The most important command 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:

Apache

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 at least the following for Bricolage:

--with-layout=Apache

This command selects the classical Apache path layout.

--disable-rule=EXPAT

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

--enable-module=ssl (optional)

This command compiles in SSL support, using the mod_ssl sources configured earlier. You only need this option if you plan to use Bricolage's SSL support.

--enable-module=rewrite

This command 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.

--enable-module=so

This command enables the mod_so module that ships with Apache. This shared library is used by mod_perl.

--enable-module=proxy

This command enables the mod_proxy module.

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

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

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:

And now PostgreSQL is ready to go!When all of the basic software components have been installed, start PostgreSQL. You can use one of the scripts in startup/ if you like.

Bricolage

Here's how to install Bricolage.

UPGRADING

To upgrade Bricolage, first stop the server:

bin/bric_apachectl stop

Save a copy of your bricolage.conf file, so you don't overwrite it:

cp conf/bricolage.conf conf/bricolage.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). Then copy in the new sources from the distribution into you bricolage directory.

cp -a /path/to/new/bricolage .

Run the upgrade scripts needed for upgrading to the new version. The upgrade scripts are in the install/upgrade/ directory. Run .sql scripts with psql and .pl scripts with perl. For example, to upgrade from 1.0.2 to 1.2.0:

psql -U postgres_user -f install/upgrade/1.2.0/burner.sql bric_database_name

psql -U postgres_user -f install/upgrade/1.2.0/oc_include.sql bric_database_name

perl install/upgrade/1.2.0/rm_dhandlers.pl

You'll need to adjust the psql line to match your PostrgeSQL settings (postgres_user and bric_database_name). Also, you may need to edit oc_include.sql if you need to GRANT access to your database to a user other than "nobody". The GRANT statements are at the bottom of the file.

Now edit the new bricolage.conf file to match your old settings using the bricolage.conf.old settings you saved as a guide. 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.

Start up Bricolage and enjoy the new features!

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

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

System User Configuration

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

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.

Authentication Configuration

These directives set rules for Bricolage user authentication.

Character Set Configuration

All character data is stored in the PostgreSQL database in Unicode (UTF-8). However, most browsers submit data to the Bricolage server in other character sets. This directive specifies what character set to expect from Bricolage users' browsers.

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.

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.

Search Configuration

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 Extenstion" 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.

Perl Loading Configuration

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 localy (ange-ftp for Emacs, for example).

There are security risks to consider - 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:

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.

UI Configuration

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 address 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 Unite Name" for the certificate authority certificate and the server cirtificate.

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.2.xx.

  4. Execute the following command:

    make certificate TYPE=custom

    You will be prompted as you were during the inital 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 sysem 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 be 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 pending 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. All of these files are stored in sub directories of the local system's $TMP environment variable (actually, the temp directory is determined by the tmpdir() method of the File::Spec library, which uses the $TMP environment variable and other means to determine the local OS's temporary directory). Session files are stored in $TMP/bricolage/session and $TMP/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 shara data between Apache processes and applications. The data for this cache is stored in $TMP/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/clean_tmp.pl

This will run nightly at 2AM and clean out all files older than 12 hours. See the documentation in bin/clean_tmp.pl for more details.

AUTHOR

David Wheeler <david@wheeler.net>

SEE ALSO

Bric

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 562:

'=item' outside of any '=over'

Around line 1250:

You have '=item 4' instead of the expected '=item 6'