In my previous article, I provided a guided tour of the Bricolage installation
process. If you followed along, you should now have a nice, functioning
installation of Bricolage 1.8 all ready to go. But as Mr.
Popeil used to say, "But wait, there's more!"
Like many other applications, Bricolage comes with a runtime configuration
file. This file, named bricolage.conf, lives in the conf
subdirectory of your Bricolage root. It contains a list of settings that tell
Bricolage how to find things, how to connect to the database, which optional
features to include, and other good stuff. This article provides a guided tour
of all of the configuration settings in bricolage.conf to enable you
to configure things exactly the way you need them, so that you can manage your
sites more effectively with Bricolage.
The format of bricolage.conf, derived from the Perl Cookbook
, is quite simple. A directive
appears on a single line, followed by a space, an equal sign, and then the
value. Anything after a pound sign (#
) is a comment. Typical entries
look like this:
APACHE_BIN = /usr/local/apache/bin/httpd
APACHE_CONF = /usr/local/bricolage/conf/httpd.conf
LISTEN_PORT = 80
SSL_PORT = 443
SSL_ENABLE = No
Most bricolage.conf configuration options are one of two types:
Boolean values or strings. A Boolean configuration directive can be either
enabled or disabled, but you have several ways in which to do so. To enable a
Boolean directive, simply set its value to Yes
, On
, or 1
(the number one). To disable it, set it to No
, Off
, or 0
(zero). String values follow the equal sign. They can be as long as necessary,
but cannot break across lines.
The first section of bricolage.conf configures Bricolage to use the
Apache web server. Because Bricolage runs on top of Apache but uses its own
startup scripts, it needs to know where to find Apache resources so that it can
configure and start Apache properly. Bricolage's default method of dynamically
configuring Apache therefore relies on these directives. The installation sets
many of them for you, but not all, so it's worth it to have a look to see if
you need to tweak any of them:
APACHE_BIN-
This directive tells Bricolage where to find your Apache
httpd executable, which it uses to start itself up.
APACHE_CON-
This directive points to the httpd.conf file. This, of course, is
the famous Apache configuration file. It, too, needs configuration to run
Bricolage (the Bricolage installer configures the default httpd.conf
in the conf subdirectory of your Bricolage root directory), and
Bricolage, in turn, uses this directive to tell httpd where to find
the configuration file when it starts up.
LISTEN_PORT-
This is the TCP/IP port on which Bricolage will listen for requests. It uses
the HTTP standard port 80 by default, but you can change
Bricolage to use another port if you already have another server listening
on port 80.
SSL_PORT-
This is the TCP/IP port on which Bricolage will listen for secure sockets
layer (SSL) requests. It defaults to the standard HTTP SSL port 443, but again,
you can change it to another port if something else is already using port 443.
SSL is disabled by default, however, so read on for details on how to turn it
on.
SSL_ENABLE-
This directive turns on SSL support. You must have either
mod_ssl or Apache-SSL installed and properly configured in your
Apache server. Not quite a Boolean configuration directive, the possible values
for SSL_ENABEL are No
(or Off
or 0
[zero]),
mod_ssl
, or apache-ssl
. SSL is a useful feature for keeping
communications encrypted between the server and users' browsers.
ALWAYS_USE_SSL-
By default, an SSL-enabled Bricolage installation uses SSL only for logging
in to Bricolage and in the user profile (where users can change their
passwords). Users can elect to encrypt all communications by checking the
Always use SSL
checkbox when logging in, but some security policies may
require the encryption of all communications. In such cases, enable
this Boolean directive to force the encryption of all communications
between the Bricolage server and users' browsers.
SSL_CERTIFICATE_KEY_FILESSL_CERTIFICATE_FILE-
These directives specify the location of your SSL keys. If you've configured
mod_ssl or Apache-SSL, you should already be familiar with these
files. They help to encrypt and decrypt requests between the server and the
browser. If you use make certificate to generate your SSL
certificate during the Apache build process, by default your server key file
will be server.key in the conf/ssl.key subdirectory of your
Apache root directory, while the server public key file will be
server.crt and in the conf/ssl.crt subdirectory. Bricolage
uses these directives to set the Apache SSLCertificateKeyFile and
SSLCertificateFile directives, respectively, in its dynamic
configuration of Apache.
NAME_VHOST-
This directive roughly corresponds to the Apache httpd.conf
NameVirtualHost directive. Set it to the IP address on which the
Bricolage Apache server will listen for requests. If you have only one IP
address on your server, the simplest thing to do is to leave this directive set
to *
, which applies to all IP addresses. Again, Bricolage uses this
directive in its dynamic configuration of Apache.
VHOST_SERVER_NAME-
This is the virtual host name under which to run Bricolage. Bricolage
requires a full host or virtual host to run and will use this directive to
configure the virtual host dynamically. Leave it set to _default_
to use
the default host name set in your httpd.conf file.
MANUAL_APACHE-
Bricolage uses Apache::ReadConfig to configure the httpd daemon. There is
no httpd.conf include file. If you want to take control of your
Bricolage Apache server by manually configuring it, enable this Boolean
directive. It will generate a file, bric_httpd.conf, in the
bricolage subdirectory of your temporary directory (see the TEMP_DIR directive for the location of the temporary
directory). This file will contain all of the Apache configuration directives
that Bricolage uses to configure Apache dynamically. Restarting Bricolage will
rewrite this file, but if you want to use it and edit it manually, copy it to
the conf subdirectory of your Bricolage root directory, disable the
MANUAL_APACHE directive, and then change the section of the
httpd.conf file that configures Bricolage from:
PerlPassEnv BRICOLAGE_ROOT
PerlModule Bric::App::ApacheConfig
To:
Include /usr/local/bricolage/conf/bric_httpd.conf
PerlPassEnv BRICOLAGE_ROOT
PerlModule Bric::App::ApacheStartup
Here /usr/local/bricolage/conf/bric_httpd.conf is the full path
name to the newly generated bric_httpd.conf file. You can now tweak
this file to your heart's content. Just be sure to generate a new one after
each upgrade of Bricolage, as certain directives may change between
releases.
SYS_USERSYS_GROUP-
These directives configure the system user and group used by Bricolage. They
should contain the same value as the User and Group
httpd.conf directives, usually nobody
or www
. Any files
written to the file system by Bricolage will be owned by this user and
group.
The next major section of the Bricolage configuration file configures the
database. Bricolage uses PostgreSQL 7.3 or later for its data store. Connecting
to that database requires several attributes, not least of which are the
username and password. These are all set during installation, but it's worth
being familiar with them in case things change down the line.
DB_NAME-
The name of the database that stores Bricolage's data. The installer will
set this for you. The default value, bric
, works well in most
situations, but it might be set to a different name if you entered one during
installation, perhaps because you already had another database named
bric
; Why would you want to do that? Perhaps you have multiple Bricolage
installations on the same host. Another reason it might be different is that
your ISP provides you with a single database that they name according to their
own naming conventions. At any rate, you're unlikely to need to change the
value of this directive.
DB_USER-
The username that Bricolage will use when connecting to the database. Again,
you are unlikely to need to change this directive, especially because, when
Bricolage creates the database, it specifically assigns permissions for this
user to access the appropriate tables, sequences, and such. Note that, for
security reasons, you should never use the PostgreSQL superuser for
this directive.
DB_PASS-
The password for the DB_USER to use to connect to the
PostgreSQL database. You'll need to change this directive if the password ever
changes in the database. Depending on your PostgreSQL server's security model,
it might not matter what the password is. For example, if the PostgreSQL is on
the same host as your Bricolage server and trusts local users (the default
configuration), it will ignore the password. Consult your PostgreSQL authentication
settings (in the server's pg_hba.conf file) or check with your
PostgreSQL DBA if you have questions.
DB_HOST-
This is the host name of your PostgreSQL server. If it's on the same host as
your Bricolage server, it will likely be commented out, thereby letting
Bricolage default to localhost
. Otherwise, it will be a different host
name or IP address. Change this setting if ever your PostgreSQL server moves
to a different host or has its host name or IP address changed.
DB_PORT-
The TCP/IP port on which your PostgreSQL server listens for connections.
This directive will be commented out if you've installed PostgreSQL locally and
you're using Unix sockets instead of TCP/IP for its connectivity (a good idea
for security-conscious environments). It will also be commented out if
Bricolage should use the default PostgreSQL port of 5432. Otherwise, if
Bricolage must connect to the PostgreSQL server via TCP/IP on a port other than
5432, set this directive to the appropriate port number.
Bricolage stores a lot of files on your server's file system, generally in
well-named directories below your Bricolage root directory. Sometimes you may
want them installed elsewhere, perhaps for the purposes of conserving disk
space or distributing I/O between different partitions. If you want to move any
of these directories to a location other than that set by the installer, copy
over any existing files to ensure that Bricolage continues to operate
correctly.
TEMP_DIR-
Bricolage creates several temporary files as it runs, for its cache, user
sessions, and the like. If you selected the multi
option when installing
Bricolage, this directive will point to a directory named tmp under
your Bricolage root. Otherwise, it will point to your system's global
tmp directory.
MASON_COMP_ROOT-
The Bricolage UI uses HTML::Mason. All of the components to power the UI live in this
directory, generally a subdirectory of your Bricolage root named comp.
However, media files uploaded to Bricolage also go in this directory, which
means that it can become quite large if you manage a lot of media documents. It
might be useful, therefore, to move this directory to a separate partition.
MASON_DATA_ROOT-
Mason compiles the Bricolage UI components into object files and stores them
in this directory. For the most part you don't need to worry about where these
files live (the default is the data directory under the Bricolage root
directory), although Bricolage will read from it quite a lot as it loads the
object files into memory, so disk I/O is important. It's unlikely to grow too
except...
BURN_ROOT-
This directive tells Bricolage where to store formatting templates, object
files, and burned files that are ready for distribution. As such, it can also
grow quite large, especially if you've published or previewed a lot of
documents. Bricolage never deletes these files so that you always have a
canonical directory of the distribution files output by Bricolage. However, the
default location for the BURN_ROOT is under the directory
specified by the MASON_DATA_ROOT directive. If you encounter disk
space problems, you might want to move this directory to another partition.
The Bricolage Mason burner is responsible for pushing documents through
Mason formatting templates. If you're writing templates that output XML (and
I'll demonstrate writing templates in a later article, so hang in there!), you
might want to simplify things by using an XML::Writer object to generate the XML. Bricolage simplifies things
by providing these directives to create a globally available XML::Writer object
for use in all Mason templates.
INCLUDE_XML_WRITER-
Enable this Boolean directive to tell Bricolage to create an XML::Writer
object that's globally available as $writer to all Mason
templates. Bricolage is smart enough to configure the XML::Writer object to
output XML to Mason's buffer, so that you can even mix standard Mason output in
your templates with XML::Writer output.
XML_WRITER_ARGS-
Use this directive to specify a list of options to pass to the XML::Writer
constructor when INCLUDE_XML_WRITER is enabled. This directive is
a string containing a Perl expression to pass to XML::Writer. The XML::Writer documentation has the
full list of possible parameters. Common parameters include
NEWLINES to trigger the output of new lines between XML elements,
and DATA_INDENT to indent nested XML elements by a certain number
of characters.
Several configuration directives affect the behavior and security of the
Bricolage authentication system. Bricolage handles its own authentication,
storing passwords in the database as MD5-encrypted hashes and recording
authentication in a browser cookie. In a security-conscious environment, it
pays to be familiar with these directives and even to review their settings
periodically.
AUTH_TTL-
This directive specifies the time-to-live, in seconds, for an authentication
session. Each time an authenticated user sends a request to the server, the
elapsed time resets to zero. You could therefore set AUTH_TTL to
3600 seconds for a one-hour time-to-live, and a user would be able to use
Bricolage all day, as long as each request was less than an hour apart (but she
might have to re-authenticate after lunch). This directive is especially useful
in environments where users access Bricolage from public workstations and
forget to log out. The default value of 28800 (eight hours) is probably too
long in a production environment.
AUTH_SECRET-
Bricolage stores the user authentication session locally and keys it off of
an MD5 string stored in a browser cookie. The MD5 string comes from the
browser's IP subnet, the expiration time, the user name, and the last access
time. Because such a string is potentially replicable by someone trying to
crack the system, Bricolage also uses a random string of characters to salt the
MD5 string. AUTH_SECRET is the string used for this purpose. The
installer generates it for you, but you might want to change it now and then,
in order to keep it random and meet the specifications of your security policy.
All users will need to re-authenticate after you change
AUTH_SECRET and restart Bricolage.
LOGIN_LENGTH-
This directive specifies a minimum user name length. Each user must have a
user name of at least this number of characters. The default, 5
, is
generally adequate, and allows the default admin
user name to work
properly.
PASSWD_LENGTH-
This directive corresponds to the LOGIN_LENGTH directive, but
applies to passwords. The password length in Bricolage is unlimited, but it's
generally a good idea to ensure that they all contain a minimum number of
characters. The default is 5
.
When Bricolage previews or publishes documents, it pushes them through
formatting templates (written in Mason, Template Toolkit, or HTML::Template)
and writes the resulting files to disk. It then distributes those files to the
appropriate servers specified in the destination manager in the user interface.
(A later article will explain more of the Bricolage administrative interface.)
Many run-time configuration directives affect the behavior of the Bricolage
distribution server.
ENABLE_DIST-
This Boolean directive enables Bricolage distribution. The only reason to
disable distribution is if you set up a separate distribution server. To my
knowledge, no one has actually done this, even though Bricolage supports it.
The QUEUE_PUBLISH_JOBS directive is more
popular to reduce Bricolage server overhead.
DIST_ATTEMPTS-
Bricolage distributes files via file system copy, FTP, SFTP, or
WebDAV—depending on your destination configuration. We all know that
failures can occasionally occur. Bricolage will attempt to distribute a file
after a failed distribution and will do it multiple times. Set the
DIST_ATTEMPTS directive to the number of times it should attempt
to distribute a file before giving up.
PREVIEW_LOCAL-
This Boolean directive enables Bricolage's internal preview server. This is
just a URI in the Bricolage UI that knows to serve previewed content rather
than the UI. This is handy for evaluating Bricolage, but be sure to disable it
in a production environment, especially if your front-end server needs to serve
something other than static HTML. The recommended approach is to set up a
separate preview server that is identical to your production server and
configure a destination to distribute and redirect previews to that server.
PREVIEW_MASON-
With the PREVIEW_LOCAL directive enabled, if the content you're
generating includes Mason calls, you can enable this boolean directive to make
Bricolage's internal preview server evaluate the Mason code before serving
documents.
DEF_MEDIA_TYPE-
This string directive identifies the default media type (also called a
MIME type
) of files for which Bricolage cannot determine the media type.
The default value, text/html
, covers a lot of typical files in a Web
content management environment, such as .php or .jsp files.
To add new types for Bricolage to recognize, use the media type manager in the
UI.
ENABLE_SFTP_MOVER-
By default, Bricolage does not support distribution via secure FTP (SFTP). If
you need it, install the required Net::SFTP module, enable this directive, and
restart Bricolage.
SFTP_HOME-
If you've enabled SFTP distribution, use this directive specify a home
directory for SFTP to use, especially if you want to use public and private SSH
keys. Consult the Net::SFTP documentation for details.
ENABLE_SFTP_V2-
Enable this directive to prefer SSH2 support for SFTP distribution. You'll
also need to install more Perl modules from CPAN. Consult the Net::SFTP
documentation for details.
SFTP_MOVER_CIPHER-
Net::SFTP uses the Net::SSH::Perl module to handle the SSH side
of things. This module supports multiple encryption ciphers. If you prefer one,
specify it via this directive.
ENABLE_WEBDAV_MOVER-
Bricolage also supports distribution via WebDAV, a standard for distributing documents via
the HTTP protocol. DAV, as it is also known, has support in multiple web
servers including Microsoft's IIS and Apache 2. If you'd like to distribute
document files to your production server or servers via DAV, install the HTTP::DAV module, enable this Boolean directive and restart
Bricolage.
QUEUE_PUBLISH_JOBS-
By default, when a user schedules a document to publish immediately, the
Bricolage server will immediately execute the distribution. If users publish a
lot of documents or you're bulk publishing large sections of your site at once,
this can really slow down the Bricolage UI for other users. This is even true
even if you've scheduled a bulk of documents to publish at a future date and
time, because the way the default bric_dist_mon script works is to
tickle the Bricolage server to distribute documents.
The way around this problem is to enable the QUEUE_PUBLISH_JOBS
boolean directive and then use the bric_queued program instead of
bric_dist_mon. With QUEUE_PUBLISH_JOBS enabled, the
Bricolage server will never burn and distribute documents, even if a
user schedules them to publish yesterday. Instead,
bric_queued handles all of the burning and distribution itself,
without having the Bricolage server expend resources on the task. With this
approach, be sure to run bric_queued from a fairly aggressive cron
job.
FTP_UNLINK_BEFORE_MOVE-
When Bricolage distributes files via FTP, it uploads them with a temporary
file name, and then, when the transfer is complete, it renames the file to the
final name. However, if an earlier version of the file is already present, the
rename might fail. (This depends on your FTP server, but Microsoft's IIS is the
server that led us to add this feature.) In such a case, enable this directive
and Bricolage will delete any existing instance of the file before renaming the
temporary file.
Bricolage has an interface for sending alert emails when it logs events that
meet certain criteria against objects. Bricolage needs to know a few things
before it can send the alerts.
SMTP_SERVER-
Bricolage uses an SMTP server to send alert email messages. The default
value for this directive, localhost
, is fine if you use a Unix system
with sendmail (or some other SMTP server) running locally. If your organization
has a dedicated SMTP server or if your Bricolage host has none of its own,
change the value of this directive.
ALERT_FROM-
Set this directive to an email address that you want to appear in the
From
header of alert emails. I typically set it to something like
Bricolage Admin <www@example.com>
, but use whatever is appropriate
for your organization. If your users are inclined to reply to alert emails,
you may want to set up a special ALERT_FROM email address that has
an auto-responder to let the user know that the reply will go unread.
ALERT_TO_METH-
This string directive indicates which header to use for specifying alert
recipients in email alerts. The possible values are To
and
Bcc
.
Some configuration directives enable you to affect how the Bricolage user
interface works in subtle ways. If you haven't used the Bricolage browser-based
interface much yet, some of these won't make much sense just now. Feel free to
come back and look again when you're you've had some experience with the
Bricolage interface and want to make it behave more according to your own
notions of correctness.
FULL_SEARCH-
By default, when you search for objects in the Bricolage admin interfaces,
or for stories, media, or templates in the asset library, the Bricolage UI
appends a wildcard character to the end of your search string. Thus if you
search for foo
, the search will return results for all records that
start with foo
. If, however, you set the
FULL_SEARCH Boolean directive to a true value, all searches in the
Bricolage UI will become substring searches. So a search for foo
will
return all records where foo
appears anywhere in a record.
The downside to this approach is that it prevents PostgreSQL from using its
database indexes. In principal, this is only a problem if you have a large
number of objects in Bricolage. If, say, you had 100,000 stories in Bricolage,
you would notice that story searches would be noticeably slower with
FULL_SEARCH enabled than with it disabled. Leave it disabled if
you expect to manage a lot of documents. Your users can always manually prepend
the wildcard character (%
) to the front of search queries if they want a
substring search.
ALLOW_WORKFLOW_TRANSFER-
Bricolage workflows are made up of a series of desks. In general, workflows
have their own desks, but desks can appear in more than one workflow. In such a
case, documents moved to such a shared desk in one workflow will be visible on
the same desk in another workflow. This is great for managing common tasks
across workflows, such as translation or legal review. The upshot is that, by
default, a document placed on a desk in one workflow cannot be transferred from
that desk to another desk in a different workflow. Users can only move it to
other desks in the workflow in which it originated. Set the
ALLOW_WORKFLOW_TRANSFER Boolean directive to a true value to
remove this constraint, so that a document placed on a desk in one workflow can
be moved from that desk to other desks in other workflows that the desk is
in.
ALLOW_ALL_SITES_CX-
When managing multiple sites in Bricolage, the user interface will display a
site context
select list. Only the workflows for the selected site will
be displayed. If you want to allow users to see all of the workflows for all of
the sites that they have permission to access, set this Boolean directive to a
true value to add an All Sites
option to the Site context
select
list. But beware! If you have access to a lot of sites, you'll have access to a
bewildering number of workflows when you select this option!
YEAR_SPAN_BEFOREYEAR_SPAN_AFTER-
For the input of dates in Bricolage, the user interface offers select lists
for the day, month, and year. By default, the years available in the
Year
select list have a limit of the ten years before and after the
value for the year or the current year. If you need more years in your select
list, set these directives to the number of years before and after the current
value or current year. For example, if you manage a site of historical
photographs with Bricolage, you might need to select years that range back over
100 years. In such a case, set YEAR_SPAN_BEFORE to 100
. A
science fiction book review site, on the other hand, might need years much
farther in the future. For such a case, set YEAR_SPAN_AFTER to the
appropriately high number.
DEFAULT_FILENAMEDEFAULT_FILE_EXT-
The file names generated for story documents are set on a per-output channel
basis. The user interface offers default values for these settings in the
output channel profile. The default file name is index
, and the default
file name suffix is html
. If, say, you were outputing content to an IIS
server, you might want to set the DEFAULT_FILENAME directive to
default
and the DEFAULT_FILE_EXT directive to htm
,
instead. It's not a big deal either way, though, because you can actually set
the values you need for each output in the user interface. These are just the
displayed defaults, settable as directives for the ultimate in laziness.
ENABLE_OC_ASSET_ASSOCIATION-
Document models are associated with output channels in Bricolage. When you
create a new document based on a model, it will automatically have the output
channel associations defined by the model. If you'd like users to be able to
change the associations—say, to assign output channels defined by the
model to be optionally associated with documents based on that model—set
this directive to a true value. If, however, the added complexity of output
channel associations will only confuse your users, set this directive to a
false value to remove the user interface for changing document output channel
associations.
ENABLE_CATEGORY_BROWSER-
When editing a story document in Bricolage, you'll see a select list of all
categories that you have READ permission to access to allow you to optionally
add the story to a new category. Most of the time, however, you'll only add a
story to one or two categories, and then never change these settings.
Therefore, if you have a lot of categories in your Bricolage installation (and
there are systems in production with over 2000 categories), it's wasteful to
load them all every time you edit a story document when you'll never change
them again.
In such a case, set the Boolean ENABLE_CATEGORY_BROWSER
directive to a true value and restart Bricolage. This will change the story
profile to offer a link to a category browser, which enables you to search for
the category or categories to associate with a story. Now, not only will you no
longer load all categories every time you access the story profile (and the
story profile is, for content producers, the most commonly accessed page in the
Bricolage UI), but you'll only load those you search for in the category
browser. I highly recommend that every Bricolage admin to set this directive to
a true value.
These directives relate to how Bricolage manages documents.
PUBLISH_RELATED_ASSETS-
Bricolage allows you to create relationships between documents. These can
point to related stories
or add images to a document, among other
things. By default, when you publish a document, Bricolage will also try to
publish any related documents. This will help to prevent 404s or broken image
problems. In some cases, you might not want this behavior, so set the
PUBLISH_RELATED_ASSETS Boolean directive to a false value.
STORY_URI_WITH_FILENAME-
Story documents in Bricolage must have unique URIs. URIs consist of a
story's category and optionally other parts of the story, such as its cover
date and its slug (a one-word description of a story). They do not, however,
consist of the file name. This is in keeping with W3C suggestions. The idea is that the
story has a directory URI, and there may be several forms of the story with
different file names in that directory, such as index.html
for HTML,
rdf.xml
for RDF, and index.pdf
for PDFs.
However, some organizations have Website policies that demand the inclusion
of file names in the URI. This is so that different documents can be in the
same directory. A common example might be a About Us
directory with
separate /about/index.html
, /about/contact.html
, and
/about/copyright.html
documents. Such URIs are not possible by default
in Bricolage, which requires that all stories have unique URIs, because each of
these stories would have the same URI, namely /about
. To get around this
issue, set the STORY_URI_WITH_FILENAME Boolean directive to a true
value. From then on, all stories will include their file names in their URIs.
Be careful, though! Existing stories will not have their URIs changed. Decide
how you want to set this directive when you start using Bricolage, and never
change it.
ALLOW_SLUGLESS_NONFIXED-
The URIs for story documents are determined by patterns specified on a
per-output channel basis. There are two different URI formats in each output
channel, one for fixed documents and one for non-fixed documents. Non-fixed
documents typically use parts of the cover date in their URIs, while fixed URIs
do not. Each document model has a flag set to indicate whether documents based
on the model will use the fixed for non-fixed URI patterns. The result is that,
for non-fixed stories, you might have URIs like
/reviews/books/2004/12/23/princess_bride
. Here the URI format includes
the slug, a one-word summary of the contents of a story (the
princess_bride
part of this example). However, slugs are optional in
stories, even non-fixed stories. If you want to force all non-fixed stories to
include the slug in order to guarantee the creation of more meaningful URIs,
set this Boolean directive to a true value.
AUTOGENERATE_SLUG-
This Boolean directive complements the ALLOW_SLUGLESS_NONFIXED
directive. If you want to keep the slug optional but generate one when a user
neglects to type one in, set AUTOGENERATE_SLUG to a true value.
This will cause Bricolage to generate a simple slug based on the title of the
story. For example, a story with the title Essential Perl 6
would have
the slug essential_perl_6
generated for it.
Bricolage is a large application that includes many CPAN modules as well as
its own 120,000+ lines of code. When you start it up, its processes can take up
30MB of memory or more. In general this isn't a problem, because Apache shares
that memory between child processes. As each process handles requests, however,
its size can swell independent of other processes. If you're performing
resource intensive activities, such as publishing a lot of documents at once,
the process that handles the request can become quite large. Because Perl (and,
by extension, mod_perl) does not return memory to the system, this
can give the appearance that you have a memory leak.
The solution to this problem is to use the Apache::SizeLimit module distributed with
mod_perl to check your mod_perl processes
periodically and kill them when they exceed a certain size. Bricolage has
integrated support for Apache::SizeLimit that these directives can quickly
enable and configure.
CHECK_PROCESS_SIZE-
This Boolean directive turns on the Apache::SizeLimit support. After you
set it to a true value and restart Bricolage, it will use the settings in the
following directives to decide how often to check your processes and to kill
them when they get to be too big.
MAX_PROCESS_SIZE-
This is the maximum size, in bytes, that processes can reach before
Apache::SizeLimit will kill them.
CHECK_FREQUENCY-
This directive determines how often Apache::SizeLimit will check the size of
your mod_perl processes. If you set it to 5
, it will check
a process after every fifth request handled by that process. The default is
1
.
MIN_SHARE_SIZE-
This directive indicates the minimum amount of shared memory the process
must employ to avoid being considered a candidate for termination. Consult the
Apache::SizeLimit documentation for more information. The default is 0
,
meaning that all Apache mod_perl processes will have their sizes
checked.
MAX_UNSHARED_SIZE-
This directive sets a limit on the amount of unshared memory a process may
consume to not be a candidate for termination. You can use this directive to
tweak your settings if you find that Apache::SizeLimit terminates processes
while they are still mainly using shared memory. The default is 0
.
Bricolage pushes story documents through formatting templates to generate
output when you preview or publish them. Formatting templates can use Mason,
Template Toolkit, or HTML::Template. If you have a lot of different types of
story documents, or just elements of story documents, you'll likely end up with
a lot of templates to manage. Editing templates in the browser interface's
textarea fields can be a pain. A better approach is to use the
Bricolage virtual FTP server, which provides access to all Bricolage templates
via FTP. If the security of your password isn't a serious consideration
(because FTP sends passwords in the clear, and maybe you work behind a firewall
or over a virtual private network), enable the virtual FTP server and edit
Bricolage templates from within your favorite FTP-enabled editor (Emacs, Vim,
HomeSite, etc.). Here's how.
ENABLE_FTP_SERVER-
This boolean directive enables the virtual FTP server. Set it to a true
value, tune the other FTP directives, reboot Bricolage, fire up the bric_ftpd application, and get to work! Just connect to
your Bricolage FTP server on the port specified by the FTP_PORT
directive, login with your Bricolage username and password, and you can browse
templates by site, output channel, and category.
FTP_PORT-
This directive specifies a TCP/IP port on which the Bricolage virtual FTP
server will listen for connections. The default is 2121
.
FTP_ADDRESS-
If your host has more than one IP address, specify one of them here to have
the virtual FTP server to listen for connections on that IP address only. By
default, the FTP server will listen on all of your host's IP addresses.
FTP_LOG-
The location of the virtual FTP server log. By default, it will be in the
log subdirectory of your Bricolage root directory.
FTP_PID_FILE-
Specify the location of the PID file for the Bricolage FTP server.
bric_ftpd will use this file to record the PID of the server when you
start it and to stop the server when you execute bric_ftpd -k. The
default is to store the PID file in the log subdirectory of your
Bricolage root directory.
FTP_DEPLOY_ON_UPLOAD-
As of Bricolage 1.8 and later, the Bricolage FTP server will save templates
to your private sandbox when you upload them. This means that they will be
checked out to you, appear in your personal workspace in the UI, and execute
when you (and only you) preview stories that use them. To check in and deploy a
template to use in production when other users preview and publish documents,
simply append the string .deploy to the end of the file name when you
upload it and Bricolage will do the rest.
Prior to version 1.8.0, the Bricolage virtual FTP server checked out,
updated, checked in, and deployed templates on every upload. If for some
reason you prefer this approach (and to be honest, I can't imagine why
anyone would!), set the FTP_DEPLOY_ON_UPLOAD directive to
a true value and restart bric_ftpd.
FTP_DEBUG-
If for some reason the virtual FTP server isn't behaving the way you expect,
set this Boolean directive to a true value and restart bric_ftpd. Then
tail the FTP log (specified by the FTP_LOG directive) to diagnose
the problem.
Because Bricolage runs on Apache 1.3, the parent process loads all of its
code at startup time, before it forks off any children. This is memory
efficient, because most modern operating systems use a copy-on-write forking
design. This means that the children all share memory with the parent until
they write to that memory, at which time the kernel copies that memory to the
child process.
When loading a lot of code, children never overwrite much of it. It's
highly advantageous to load as much code as you think you'll need into the
parent process at startup time, to prevent each of the children from loading it
themselves and taking up that much more memory. These directives help you to do
just that.
PERL_LOADER-
This string directive can be any Perl code you like, as long as it's all on
one line in the bricolage.conf file. Bricolage will execute this code
at startup time, in the namespace used by the Mason burner. This is very useful
for loading Perl modules that your templates use, so that you're not loading
them in each child process. The default value loads Apache::Util, which has many useful HTML
output utility functions, and Bric::Util::Burner, which exports
several constants that you can use in templates to tell what type of burn is
being executed (preview or publish). Other common modules you might want to
load here include CGI.pm or XML::RSS to assist with HTML and RSS output,
respectively. You can load anything here, really.
LOAD_LANGUAGES-
Bricolage has localizations for multiple languages, including German,
Portuguese, Italian, Cantonese, Mandarin, and Russian. The localization
libraries are Perl modules loaded at server startup time. For the most
efficient use of memory, load the languages you expect to use most often by
specifying the appropriate language codes (such as en
for English,
pt_pt
for Portuguese, de_de
for German, etc.) in a
space-delimited list via the LOAD_LANGUAGES directive.
LOAD_CHAR_SETS-
This directive functions just like the LOAD_LANGUAGES
directive, except that it loads the libraries that convert to and from UTF-8.
Bricolage allows individual users to use different character sets when
accessing the Bricolage UI, including ISO-8859-1, ISO-8859-2, Big5, ShiftJIS,
GB-2312, and others. To save memory overhead, specify each character set that
you expect your users will need to use day-to-day in Bricolage in a
space-delimited list in the LOAD_CHAR_SETS directive.
As of Bricolage 1.8.0, Bricolage can generate thumbnail versions of image
files uploaded for media documents. All you need to do is install the Imager
module from CPAN (along with the necessary libraries for the image formats you
use—see the Imager README file for details) and configure thumbnail support via
these directives.
USE_THUMBNAILS-
Set this Boolean directive to a true value and restart Bricolage to have
thumbnails generated for all image files in Bricolage. You must have Imager
installed, of course. You might also want to consider installing media type
icons specific to particular types of non-image files. See the README
file and script in contrib/copy_gnome_icons in the Bricolage sources
for information on which icon files to use and how to install them using the
copy_gnome_icons script.
THUMBNAIL_SIZE-
Set this directive to the maximum dimension of thumbnail images, in pixels.
Bricolage will use this number to constrain the size of the thumbnail so that
its greatest dimension does not exceed this number. For example, if
THUMBNAIL_SIZE has its default value, 75
, and you upload a
150 x 100 pixel image file, Bricolage will generate a 75 x 50 pixel
thumbnail.
Bricolage 1.8.0 added support for WYSIWYG (what you see is what you get)
editing via the htmlArea JavaScript editor, though it has this feature disabled by
default. To enable it, download and install htmlArea 3.0 (in beta release as of
this writing) in the comp/media/htmlarea directory under your
Bricolage root. Then configure it via these directives and restart Bricolage.
You will then be able to specify a WYSIWYG
field type in document
element definitions, and content editors can take advantage of htmlArea's
WYSIWYG features when editing content in those fields.
ENABLE_HTMLAREA-
Set this Boolean directive to a true value to enable Bricolage's htmlArea
support. You must have htmlArea installed in the comp/media/htmlarea
directory under your Bricolage root.
HTMLAREA_TOOLBAR-
The htmlArea editor offers a lot of WYSIWYG features as controls (buttons)
in its interface. The controls handle tasks such as copy, paste, italicize,
boldface, link, etc. By default, Bricolage enables only a subset of these
controls. The subset excludes layout type features such as font selection and
color, line justification, and the like. The idea is to provide only the tools
needed for users to easily add semantically meaningful markup rather than
layout markup, so as to keep content independent of presentation. If you
really need to allow your users to use six different type faces in twelve
colors, you can enable the htmlArea controls for these features via the
HTMLAREA_TOOLBAR directive. The value of the directive is a
comma-separated list of single-quoted strings with brackets at either end. See
the htmlArea documentation for a complete list of supported controls.
Now you have all the information you need to configure how Bricolage
operates to your heart's content. My next article will explore the nitty-gritty
of defining document models in Bricolage.
