NAME

Bric::Admin - Bricolage System Administration Guide.

VERSION

$Revision: 1.157 $

DATE

$Date: 2004/04/30 00:14:02 $

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

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

  3. Install PostgreSQL 7.2 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.

PACKAGES

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

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:

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

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

Apache-SSL

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:

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.

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!

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:

Bricolage

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

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

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

Bricolage (Manual Installation)

Here's how to install Bricolage manually.

HTMLArea (Optional)

To install HTMLArea, an optional application that offers WYSIWYG editing in the Bricolage UI, simply download it from http://www.interactivetools.com/products/htmlarea/, decompress the files, and move them to the comp/media/htmlarea directory in your Bricolage root. You will also need to enable the ENABLE_HTMLAREA bricolage.conf directive (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 CVS, 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:

  bin/bric_apachectl stop

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

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

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

Delete all existing Mason object files and temporary files:

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

Run the upgrade scripts needed for upgrading to the new version. The upgrade scripts are in the inst/upgrade/ directory. Run each script in all of the version number directories that are higher than the version you're upgrading from. For example, to upgrade from 1.3.2 to 1.4.0, run each of the scripts in 1.3.0/, 1.3.1/, 1.3.2/, and 1.4.0/ -- in that order.

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

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

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

Now, start up Bricolage and enjoy the new features!

  bin/bric_apachectl start

CONFIGURATION

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.

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.

Temp Directory Configuration

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.

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.

UI Configuration

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.

Time Zone Configuration

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.

Image Thumbail 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.

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.

Story URI configuration

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

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 the Bric::DBA manpage 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.

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@wheeler.net>

SEE ALSO

Bric