NAME

Bric::Admin - Bricolage System Administration Guide.

VERSION

$Revision: 1.5.2.17 $

DATE

$Date: 2001/12/10 21:15:18 $

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.

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). Installation of these 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.

MM - Shared Memory Library

Installation of MM 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_perl 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 libarary is used by mod_perl. [Is this true, or did I make it up?]

--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. Here are the details:

And now PostgreSQL is ready to go!

Bricolage

When all of the basic software components have been insalled, start PostgreSQL. You can use one of the scripts in startup/ if you like.

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.

Apache OpenSSL (mod_ssl) Configuration

The Apache OpenSSL interface (mod_ssl) is an optional part of the Bricolage application. Not only does it enabled secure logons 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.). The following directives derive from their similarly-named mod_ssl directives. See the mod_ssl documentation <http://www.modssl.org/docs> for more detail.

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 diretives 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. If you decide to edit httpd.conf yourself (but you wouldn't do that, right?), you'll want to make sure that the names set in bricolage.conf agree with the httpd.conf User and Group directives, since the user name is expected to be the same for other parts of the application.

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. [Will need to write a lot more documentation about this at some point -- and need think about saving media to /stage instead of /media/assets, too.]

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

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 -- that is, /usr/local/pgsql/data. 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 $BRICOLAGE_ROOT/data, 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 houses the templates that are used to format stories - you'll want to be sure to back it up regularly. The $BRICOLAGE_ROOT/comp/data/preview directory gets formatted story files written to it 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 prvent the loss of all of your media assets!

Bricolage also create 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 meand 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

perl(1), Bric (2).

POD ERRORS

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

Around line 555:

'=item' outside of any '=over'

Around line 1361:

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