HOWTO: How to run Bricolage on a Virtual Host and on Non Standard Ports

Requirements

The following constitutes a minimum installation of:

Apache 1.3.22
mod_perl 1.27
Bricolage 1.4.0
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.

Caveats

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

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

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 stop
```
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.:
```
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.

Edit the bric_httpd.conf file to change the 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.

Edit /usr/local/bricolage/conf/bricolage.conf, changing MANUAL_APACHE = On back to MANUAL_APACHE = Off.

Start your Apache server as you normally would. If you’re using the PerlPassEnv directive in your httpd.conf and your Bricolage root directory is something other than /usr/local/bricolage, be sure to set the $BRICOLAGEROOT environment 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:          ⁸⁰     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: ⁴⁴³ 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.

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:
```
MinSpareServers      2
MaxSpareServers      4

StartServers         2

MaxClients           6
```

You may now start bricolage by typing the command line:
```
/usr/local/bricolage/bin/bric_apachectl start
```

Provide feedback

Saved searches