HOWTO: How to run Bricolage on a Virtual Host and on Non Standard Ports
Clone this wiki locally
The following constitutes a minimum installation of:
apache_ssl 1.3.22+ssl_1.47 or mod_ssl 2.8.4-1.3.20
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.
Simple Virtual Hosting Configuration
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
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 = 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.
Manually Configuring The Bricolage Apache Server
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/…). Follow these additional instructions as you perform the installation:
When you come to the portion of the installation that asks:
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
m – "multi"
Once installation is complete, edit /usr/local/bricolage/bricolage.conf, changing
MANUAL_APACHE = Offto 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:
then stop Apache by issuing the command
Move 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.:
Edit the bric_httpd.conf file to remove the
Listendirectives at the top of the file and insert this line immediately after the
If your Bricolage root is anything other than /usr/local/bricolage, you should actually insert two lines after the
PerlSetEnv BRICOLAGE_ROOT /path/to/my/bricolage
Or, to get more flexibility, use these two lines:
But then you’ll need to set the
$BRICOLAGE_ROOTenvironment variable before starting Bricolage.
Edit the bric_httpd.conf file to change the line(s) containing the directive
You may also use IP based virtual hosting by changing the
<VirtualHost ...>directive to a fixed IP address.
Edit /usr/local/bricolage/conf/bricolage.conf, changing
MANUAL_APACHE = Onback to
MANUAL_APACHE = Off.
Start your Apache server as you normally would. If you’re using the
PerlPassEnvdirective in your httpd.conf and your Bricolage root directory is something other than /usr/local/bricolage, be sure to set the
$BRICOLAGEROOTenvironment variable before starting Apache. Bricolage should now be available on the virtual host name you defined.
Using Alternate Ports
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
SSL certificate key file location
Apache SSL Port: 443 444
Are you sure you want to use '444'? [yes]
Bricolage comes with two sets of defaults. You'll have thes - "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
opportunity to override these defaults but choosing wisely
here will probably save you the trouble. Your choices are:
The rest of the installation can proceed in the normal fashion.
Edit /usr/local/bricolage/conf/bricolage.conf and
/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:
You may now start bricolage by typing the command line: