Bric::Admin - Bricolage System Administration Guide.
This guide is intended for the system administrator in charge of installing, configuring, or tuning a Bricolage system.
For the really impatient you can just download a VMWare image with Bricolage already set up for you running under Ubuntu. See http://www.bricolage.cc/news/announce/2008/06/01/vmware/ for more details.
There are lots of hints and tips for installation at the Bricolage Wiki, http://wiki.bricolage.cc/bin/view/Bric/InstallationTips, along with other tutorials and useful bits.
Don't forget to read the README for your OS first for known issues and helpful tips. These can be found in the root of the unpacked Bricolage tarball.
On Apache 2 you will also need to install mod_apreq and make sure that it and all the modules above appear in the list in the mods-enabled directory in your apache2 base directory. You will also need to use the prefork mpm rather than the threaded worker mpm in Apache 2.
For SSL also install mod_ssl or (on Apache 1 only apache-ssl).
perl Makefile.PL
make
make testAnd then as root:
make installIf 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 installBricolage will do its best to discover most information by itself, and exit with an error when it cannot. Default values will be selected from the appropriate defaults file for your system. See inst/defaults for a list of supported systems. inst/defaults/standard contains all of the default values, and other system-specific files can override those values.
You can override many of those values during the install by passing the appropriate environment variables to make. The supported environment variables include:
The location where Bricolage should be installed. Defaults to /usr/local/bricoage.
One of two values describing where to install all of the Bricolage files:
All files, including Perl libraries, temp files, programs, etc., will be installed under $BRICOLAGE_ROOT. This is the default and recommended option.
Most files will be installed under $BRICOLAGE_ROOT, but Perl libraries, programs, and man pages will be stored where Perl libraries and scripts usually go (e.g., /usr/local/lib/perl, /usr/local/bin, and /usr/local/man), temporary files will be stored in the system temp directory (e.g., /tmp, etc.
The location to use for temporary files when bricolage is running. Defaults to $BRICOLAGE_ROOT/tmp. Ignored when $BRICOLAGE_INSTALL_STYLE is set to "s".
The directory under which to install Bricolage's Perl modules. Defaults to $BRICOLAGE_ROOT/lib. Ignored when $BRICOLAGE_INSTALL_STYLE is set to "s".
The directory under which to install Bricolage's programs. Defaults to $BRICOLAGE_ROOT/bin. Ignored when $BRICOLAGE_INSTALL_STYLE is set to "s".
The directory under which to install Bricolage's man pages. Defaults to $BRICOLAGE_ROOT/man. Ignored when $BRICOLAGE_INSTALL_STYLE is set to "s".
The directory under which to install Bricolage's UI Mason components. Defaults to $BRICOLAGE_ROOT/comp.
The directory for Bricolage to use for its UI Mason data. Defaults to $BRICOLAGE_ROOT/data.
The directory for Bricolage to use for its log files. Defaults to $BRICOLAGE_ROOT/data.
The file name Bricolage should use for its PID file. Defaults to $BRICOLAGE_ROOT/log/httpd.pid.
The type of database to use. Must be one of the following:
PostgreSQL. This is the default choice.
MySQL.
The path to the database config program. This would an implmentation of pg_config for PostgreSQL or mysql_config for MySQL. Bricolage will try to find the appropriate one to use for the default.
A boolean indicating whether or not the databse should be created. Defaults to true. If you set this to a false value, the database should already exist and the Bricolage database user will need to have permission to create objects in it (tables, indexes, sequences, etc.).
The name of the PostgreSQL super user. Defaults to "postgres".
The password for the PostgreSQL super user. Defaults to an empty string, which works for a locally-installed PostgreSQL using "trust" or "ident" authentication.
A boolean indicating whether or not the installer should become the PostgreSQL system user (usually named "postgres") before connecting to the database and making changes to it. Such is required if your PostgreSQL server uses ident authentication, as is the default for Debian builds of PostgreSQL. Defaults to false.
The name of the PostgreSQL user for Bricolage itself to use. Defaults to "bric".
The name of the database for Bricolage to use. Defaults to "bric".
The name of the host for the PostgreSQL database server. Defaults to "localhost".
The name of the MySQL super user. Defaults to "root".
The name of the MySQL user for Bricolage itself to use. Defaults to "bric".
The name of the database for Bricolage to use. Defaults to "bric".
The version of Apache to use. Must be one of the following:
Apache 1.3.x. This is the default choice, although that's subject to change in a future release.
Apache 2.x.
The base name of the Apache executable, usually "httpd", which happens to be the default.
A $PATH environment variable-style list of directories to search for the Apache executable. Defaults to the value returned by File::Spec::Functions::path.
A boolean value indicating whether or not Bricolage should use SSL. Defaults to true if the detected Apache server supports SSL, and false if it does not.
The location of the SSL certificate file that Bricolage should use. Defaults to $HTTPD_ROOT/conf/ssl.key/server.cert, where $HTTPD_ROOT is collected from the httpd executable.
The location of the SSL key file that Bricolage should use. Defaults to $HTTPD_ROOT/conf/ssl.key/server.key, where $HTTPD_ROOT is collected from the httpd executable.
The location of the SSL key file that Bricolage should use.
The name of the Apache super user, usually "nobody" or "daemon".
The name of the Apache super user, usually "nobody" or "daemon".
The port for Bricolage to use for its Apache server. Defaults to 80.
The SSL port for Bricolage to use for its Apache server. Defaults to 443. This option is ignored of SSL is not used.
The host name that Bricolage should use when it configures itself to run on a virtual host inside of Apache. Default to the value retuned by `hostname`.
A $PATH environment variable-style list of directories to search for expat. Defaults to the value returned by File::Spec::Functions::path.
Bricolage requires a lot of other components to be installed; here's a list of them:
Note that you also have some required categories of modules, but you must pick from among them. Depending on your choice of database, you will need to install one of:
And depending on whether you're using Apache 1 or Apache 2, you'll need to install one of:
The fact that these are marked "(optional)" is just to help the installer determine CPAN dependencies. Trust us, one or the other of these is required. Either one of these is optional, however:
Follow these instructions to prepare your system for Bricolage. If you're upgrading from an older version of Bricolage see the "UPGRADING" section below.
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:
sh Configure -Umymalloc -Dinstallusrbinperl -des
make
make test
make installFor the curious, the options used with Configure above are:
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.
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".
This optional command tells Configure that you accept all the other defaults, and it will therefore provide terse output during the configuration.
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:
sh config <commands>
make
make testmake 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.
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.
Installation of mod_ssl follows the usual conventions. Here's an example:
--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.xxWhere "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.
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:
perl Makefile.PL \
APACHE_SRC=../apache_1.3.*/src \
DO_HTTPD=1 \
USE_APACI=1 \
PREP_HTTPD=1 \
EVERYTHING=1
make
make installBefore 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:
This option selects the classical Apache path layout.
This option prevents incompatibilities between Apache's implementation of the Expat XML parser, and that used by Perl's XML::Parser module.
If you're including SSL support via mod_ssl, this option compiles it in.
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.
This option compiles in mod_perl. The library it points to was installed by the mod_perl make process.
This option ensures that mod_perl will be statically compiled into Apache, rather than as a DSO.
./configure \
--with-layout=Apache \
--disable-rule=EXPAT \
--enable-module=rewrite \
--activate-module=src/modules/perl/libperl.a \
--disable-shared=perl
makeOr 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--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=dummyIf you do have a formal certificate then can make a certificate with the command:
make certificate TYPE=customNear 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.
make installAPXS environment variable while installing it so that tests pass:% export APXS=/some/nonstandard/apache/bin/apxsAnd you're done! You can test the installation by calling
/usr/local/apache/bin/apachectl configtestPostgreSQL 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 = trueOtherwise, here are the installation details:
/usr/sbin/useradd -d /home/postgres postgres -s /bin/tcsh--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../configure --enable-multibyte=UNICODE
make
make installmkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data-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 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"cd docs
make installPOSTGRES_INCLUDE and POSTGRES_LIB environment variables, first:export POSTGRES_INCLUDE=/usr/local/include
export POSTGRES_LIB=/usr/local/libThen you can build the module:
cd /path/to/DBD-Pg-1.xx
perl Makefile.PL
make
make test
make installAnd now PostgreSQL is ready to go!
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:
perl Makefile.PL
make
make test
make installWith the 1.4.0 release, Bricolage now can be installed using the new installation system.
perl Makefile.PLThis 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):
The Apache user, set by the 'User' directive in conf/httpd.conf.
The Apache group, set by the 'Group' directive in conf/httpd.conf.
The Apache port, set by the 'Port' directive in conf/httpd.conf.
The Apacher server name, set by the 'ServerName' directive in conf/httpd.conf.
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.
A postgresql user which has permissions to CREATE DATABASE, CREATE USER, and GRANT a user permissions in the database.
I'm not sure how this is different from the root user.
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'.
Any (valid postgresql) name you want for your bricolage database.
The hostname and port of the server where your postgresql database is located. The default is localhost, through local (non TCP) sockets.
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.
What $ENV{BRICOLAGE_ROOT} will be set to.
Where temporary files, like cache files, are written.
Where Perl modules will be installed.
Where executables like bric_soap will be installed.
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).
Where access_log and error_log will be written to.
Where Apache's PID file will be written each time Bricolage is started (and removed when it's not running).
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.
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.
make
make installIf 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. 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.
Here's how to install Bricolage manually.
./bric_pgimport -u postgres -p postgres -d dbname -c -m db_user:db_passwordWhere '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.
PerlPassEnv BRICOLAGE_ROOT
PerlModule Bric::App::ApacheConfigBricolage 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 virtual host configuration to $BRICOLAGE_ROOT/conf/vhosts.conf, and then this file will be automatically rewritten and included on each startup operation. If you change this line
PerlModule Bric::App::ApacheConfigto
PerlModule Bric::App::ApacheStartupthen 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.
/usr/local/bricolage/bin/bric_apachectl startTo 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.
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).
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.
You will also need to enable the ENABLE_WYSIWYG and WYSIWYG_EDITOR bricolage.conf directives (see UI Configuration).
For Bricolage 2.0 you will need Xinha release 0.91beta or higher.
To install FCKeditor, an optional application that offers WYSIWYG editing in the Bricolage UI, simply download it from http://www.fckeditor.net/, decompress the files, and move them to the comp/media/wysiwyg/fckeditor directory in your Bricolage root.
You will also need to enable the ENABLE_WYSIWYG and WYSIWYG_EDITOR bricolage.conf directives (see UI Configuration).
If you intend to use FCKeditor's SpellerPages support for spellchecking, you'll need to change two files in the FCKeditor source to get it to work with Bricolage. First in comp/media/wysiwyg/fckeditor/editor/dialog/fck_spellerpages/spellerpages/spellChecker.js, change this line:
this.spellCheckScript = 'server-scripts/spellchecker.php';To this:
this.spellCheckScript = 'server-scripts/spellchecker.pl';And second, in comp/media/wysiwyg/fckeditor/editor/dialog/fck_spellerpages/spellerpages/server-scripts/spellchecker.pl, you will likely need to change this line:
my $aspell_cmd = '"C:\Program Files\Aspell\bin\aspell.exe"';To point to the correct loation of aspell:
my $aspell_cmd = '/usr/bin/aspell';Execute which aspell on your system if you're not sure where aspell is. You will also need to modify a couple of lines from this file (although a patch has been submitted to the SpellerPages project, so it may be fixed by the time you read this). Change these lines:
print <<EOF;
Content-type: text/html; charset=utf-8
<html>
<head>To these:
print header, <<EOF;
<html>
<head>And finally, you might also need to make the spellchecker.pl file executable:
chmod +x comp/media/wysiwyg/fckeditor/editor/dialog/fck_spellerpages/spellerpages/server-scripts/spellchecker.plTo install JS-Quicktags, an optional JavaScript libary that off buttons to make adding tags to text eadier in the Bricolage UI, simply download it from http://alexking.org/projects/js-quicktags/, decompress the files, and move them to the comp/media/wysiwyg/js-quicktags directory in your Bricolage root.
You will also need to enable the ENABLE_WYSIWYG and WYSIWYG_EDITOR bricolage.conf directives (see UI Configuration).
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/.
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 Git, 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/bricolageNext, stop the server:
$BRICOLAGE_ROOT/bin/bric_apachectl stopSave 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.oldInstall 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 dataNow 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 startAs of version 2.0, Bricolage supports the Apache 2 Web server. If you'd like to upgrade your existing, Apache 1-powered Bricolage install to run on Apache 2, first install Apache 2, mod_perl 2, and Apache2::Request (apreq 2). Then, just run make upgrade as usual, but select "apache2" instead of "apache". Once the upgrade has finished, just execute these commands:
cd $BRICOLAGE_ROOT/conf
mv httpd.conf httpd.conf.orig
cp httpd.conf.def httpd.conf
mv bricolage.conf bricolage.conf.orig
cp bricolage.conf.def bricolage.confIf you've customized your httpd.conf or bricolage.conf settings, you will likely have to edit the new files to sync up with your original settings. Once that's done, just start Bricolage and you'll be good to go on Apache 2.
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.
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.
/usr/local/apache/bin/httpd if not specified. This isn't portable, so we recommend you set it! Used only in bric_apachectl./usr/local/apache/conf/httpd.conf if not specified. This isn't portable, so we recommend you set it! Used only in bric_apachectl.APACHE_CONF (using Listen, Port, or BindAddress).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.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.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.SSL_ENABLE set to "mod_ssl" or "apache_ssl", this directive removes the choice of using SSL from the user's control and forces all access to the application server to use the https protocol. This approach may be valuable in those organizations that need to guarantee 100% encrypted access to Bricolage and can afford the overhead. Disabled by default. If you're using Briciolage behind a reverse proxy server and using SSL, you will also have to enable ALWAYS_USE_SSL so that recirects will work properly.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.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.$BRICOLAGE_ROOT/conf/vhosts.conf and include it in the configuration using the Apache Include directive. 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::ApacheConfigIf this line is changed to
PerlModule Bric::App::ApacheStartupthen only the contents of the httpd.conf specified by the APACHE_CONF directive will be passed to the httpd daemon -- Bricolage will do no dynamic configuration. In such a case, you'll want to either Include the generated vhosts.conf file (which you can edit as you wish), or incorporate its contents directly into your httpd.conf file.
Note that under Apache 2, the vhosts.conf file is always created, regardles of the setting of MANUAL_APACHE.
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).
pgimport (see above). Defaults to "castellan" if not specified.pgimport (see above). Defaults to "nalletsac" if not specified.This is the name and group of the system user as whom Bricolage and Apache run.
User directive used in the Apache configuration file specified in the APACHE_CONF configuration directive. Defaults to "nobody" if not specified.Group directive used in the Apache configuration file specified in the APACHE_CONF configuration directive. Defaults to "nobody" if not specified.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.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.
$BRICOLAGE_ROOT/comp if not specified.$BRICOLAGE_ROOT/data if not specified. Make sure that SYS_USER has permission to write to this directory.$MASON_DATA_ROOT/burn if not specified. Make sure that SYS_USER has permission to write to this directory.Note: Only the Mason burner supports XML::Writer.
Note: Only the Mason burner supports XML::Writer.
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.
These directives set rules for Bricolage user authentication.
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 LDAPThen, 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 InternalThen 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.
^eFH5D,~3!f9o&3f_=dwePL3f:/.Oi|FG/3sd9=45oi%8GF*)4#0gn3)34tf\`3~fdIf^ N: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 by username. Then the authentication is sent to the LDAP server. If a user exists in the LDAP server but not in Bricolage, she will not be able to authenticate.
You can further limit who can authenticate to Bricolage by adding their user DNs to a single LDAP group. See the LDAP_GROUP and LDAP_MEMBER_ATTR directives below for more information.
LDAP_SERVER directive. Defaults to 3.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.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.LDAP_SSL_VERSION to the version of SSL supported by your LDAP server. Defaults to 3.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.
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).
ENABLE_SFTP_MOVER directive) to use a particular encryption cipher. This can be useful for tuning SFTP distribution for speed. The default is 0, which allows the default cipher to be used. Consult the Net::SSH2 documentation for a complete list of supported ciphers for SSH-2. As of this writing, the suppported ciphers are "aes256-cbc", "aes192-cbc", "aes128-cbc", "blowfish-cbc" "arcfour", "cast128-cbc", "3des-cbc" and "none". The default SSH-2 cipher is "aes256-cbc".SYS_USER. The username and private key password (if any) must be entered in the Bricolage interface when setting up the destination.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.
PUBLISH_RELATED_ASSETS to no/off/0 so that, when publishing from a publish desk, related assets will not be published. Defaults to "yes".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".data_text parameter to the list() and friends methods of Bric::Biz::Asset::Business::Story and Bric::Biz::Asset::Business::Media to search large fields (such as paragraphs) as well as short fields (like headers). Note that this can make such searches much more expensive if you have more than a few thousand paragraph-type fields in your documents. Defaults to "Off" if not specified.WYSIWYG_EDITOR appropriately.In addition to the button specifications, Xinha and htmlArea configurations support a few other toolbar configuration options:
Inserts a space of 5 pixels (the width is configurable by external CSS) at the current position in the toolbar.
Inserts a small vertical separator, for visually grouping related buttons.
Starts a new line in the toolbar. Subsequent controls will be inserted on the new line.
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.
LOAD_LANGUAGES defaults to "en_us" and LOAD_CHAR_SETS defaults to "UTF-8".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.
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.
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.
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.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.
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:
$BRICOLAGE_ROOT/log/ftp.log if not set.$BRICOLAGE_ROOT/log/ftp.pid if not set.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.
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/dataThe following addresses a number of installation issues you might face.
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:
/usr/local/bricolage/bin/bric_apachectl stoprm -rf /usr/local/apache*make certificate TYPE=customYou 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.
make installThis will install Apache and the new certificate.
/usr/local/bricolage/bin/bric_apachectl startBricolage 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.
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.
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_tmpThis will run nightly at 2AM and clean out all files older than 12 hours. See bric_clean_tmp for more details.
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 cloneThis 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 installThat'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.
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.
David Wheeler