How to run Bricolage on a Virtual Host and on non-standard ports
This HOWTO describes how to run Bricolage on non-standard ports such as 81 and 444 (instead of 80 and 443), as well as how to run Bricolage as a virtual host on an existing Apache installation (not recommended).
The following constitutes a minimum installation
Apache 1.3.22 or later
mod_perl 1.27 or later
apache_ssl 1.3.22+ssl_1.47 or later
or
mod_ssl 2.8.4-1.3.20 or later
Bricolage 1.4.0 of later
The most recent versions of these applications and libraries are recommended. You must be familiar with the configuration of both SSL and Apache.
This HOWTO describes two different methods to run Bricolage. One as a stand-alone process with or without virtual hosts for Bricolage admin and user purposes, and the other as a second instance of Apache running as a virtual host on an existing production Apache installation (not recommended).
So why the warning? Bricolage is a heavy process. Each Apache child starts life with a minimum 25 megabyte memory requirement and grows from there. More recent versions of Bricolage are even more resource-intensive. Granted, some of that memory is shared, but if Bricolage is run as a virtual host on a production installation, then each child process bears this overhead even though it may never be called upon to deliver Bricolage content.
If it is necessary to host Bricolage on a server with a production Apache installation, it is the author's opinion that running a second instance of Apache on alternate ports with a restricted number of children will provide more efficient use of the server memory resources.
If you still wish to run Bricolage on a virtual host, this HOWTO will tell you how to do that, too, but you've been warned.
Setting up a Bricolage to run as a virtual host is as simple as editing your
bricolage.conf file and restarting the server. By default, Bricolage
automatically configures Apache so that it runs on a virtual host, even if
that virtual host is the default host name. You can change the virtual host
name for Bricolage by changing the VHOST_SERVER_NAME and NAME_VHOST
directives. For example, if your server uses only one IP address, or you
want your virtual host name to respond to requests on any IP address on your
server, set the directives like so:
NAME_VHOST = * VHOST_SERVER_NAME = your.virtual.host.name.example.com
If you need to specify the IP address, do so in the NAME_VHOST directive:
NAME_VHOST = 192.168.1.1 VHOST_SERVER_NAME = your.virtual.host.name.example.com
Then restart Bricolage. It will now respond to requests to
your.virtual.host.name.example.com on 192.168.1.1. Be sure not to include a
VirtualHost directive in your httpd.conf, as Bricolage will overwrite it
and Apache will issue a warning.
Install Bricolage using the procedure described in the Bric::Admin. You may use any installation directories for Bricolage that you choose; however this HOWTO assumes that the defaults have been chosen (/usr/local/bricolage/...). Follow these additional instructions as you perform the installation:
Bricolage comes with two sets of defaults. You'll have the opportunity to override these defaults but choosing wisely here will probably save you the trouble. Your choices are:
s - "single" one installation for the entire system
m - "multi" an installation that lives next to other
installations on the same machine
choose: m - ``multi''
Once installation is complete, edit /usr/local/bricolage/bricolage.conf, changing MANUAL_APACHE = Off to read MANUAL_APACHE = ON.This will cause Bricolage to generate the file
/usr/local/bricolage/tmp/bricolage/bric_httpd.conf
when it is started then stopped in the next step. This file contains the necessary Apache configuration directives for running Bricolage on a virtual host.
Shut down your regular Apache process and restart it using:/usr/local/bricolage/bin/bric_apachectl start
then stop Apache by issuing the command
/usr/local/bricolage/bin/bric_apachectl stopMove or copy /usr/local/bricolage/tmp/bricolage/bric_httpd.conf to your Apache configuration directory and place an include statement in your main httpd.conf file to pull it in, i.e.:
Include conf/bric_httpd.conf
Edit the bric_httpd.conf file to remove the Listen directives at the top
of the file and insert this line immediately after the <VirtualHost ... >
directives:
PerlModule Bric::App::ApacheStartup
If your Bricolage root is anything other than /usr/local/bricolage, you
should actually insert two lines after the <VirtualHost ...> directives:
PerlSetEnv BRICOLAGE_ROOT /path/to/my/bricolage PerlModule Bric::App::ApacheStartup
Or, to get more flexibility, use these two lines:
PerlPassEnv BRICOLAGE_ROOT PerlModule Bric::App::ApacheStartup
But then you'll need to set the $BRICOLAGE_ROOT environment variable before
starting Bricolage.
line(s) containing the
directive
ServerName _default_
to
ServerName your.virtual.host.name.example.com
You may also use IP based virtual hosting by changing the
<VirtualHost ...> directive to a fixed IP address.
PerlPassEnv directive in your httpd.conf and your Bricolage root
directory is something other than /usr/local/bricolage, be sure to set the
$BRICOLAGE_ROOT environment variable before starting Apache. Bricolage
should now be available on the virtual host name you defined.
This is the preferred method to run Bricolage in order to minimize resource
utilization where a standard Apache web service must be provided as well as
Bricolage admin and user services. The standard Apache service is not
modified. Instead, a second master httpd process is run that provides
Bricolage services on alternate ports. You may choose any ports you wish; in
this HOWTO, ports 81 and 444 are used. SSL service on port 444 is not
required, so ignore references to the setup of this service if it is not
needed.
Install Bricolage using the procedure described in Bric::Admin. You may use any installation directories for Bricolage that you choose; however this HOWTO assumes that the defaults have been chosen (/usr/local/bricolage/...).
In most cases the default suggestions made by the configuration script will be the correct choice. There are several questions which must be answered as follows:
Apache User: [nobody] your choice Apache Group: [nobody] your choice Apache Port: [80] 81 Are you sure you want to use '81'? [yes] Apache Server Name: [your.server.name.example.com]
If you're using SSL, be sure to select an alternate port for SSL, too:
Do you want to use SSL? [no] yes
# use your path to bricolage certificate if applicable
SSL certificate file location
[/usr/local/apache/conf/ssl.crt/server.crt]
SSL certificate key file location
[/usr/local/apache/conf/ssl.key/server.key]
Apache SSL Port: [443] 444
Are you sure you want to use '444'? [yes]
Bricolage comes with two sets of defaults. You'll have the opportunity to override these defaults but choosing wisely here will probably save you the trouble. Your choices are:
s - "single" one installation for the entire system
m - "multi" an installation that lives next to other
installations on the same machine
Your choice? [s] m
The rest of the installation can proceed in the normal fashion.
/usr/local/bricolage/conf/bricolage.conf /usr/local/bricolage/httpd.conf
as required for your installation. See Bric::Admin for details. It is recommended that the number of number of servers and clients be limited in /usr/local/bricolage/httpd.conf to not overuse host resources. My system, which has 500m of memory and concurrently provides production web services, is set as follows:
MinSpareServers 2 MaxSpareServers 4 StartServers 2 MaxClients 6You may now start bricolage by typing the command line:
/usr/local/bricolage/bin/bric_apachectl start
Michael Robinton <michael@bizsystems.com>