Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

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

phillipadsmith edited this page · 1 revision
Clone this wiki locally

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

  • 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
Something went wrong with that request. Please try again.