We've expanded our Perl news coverage and improved our search! Search for all things Perl across O'Reilly!

Installing Bricolage
by David Wheeler | Pages: 1, 2, 3

Back to Installation Configuration

After the Bricolage installer has determined which Perl module dependencies need to be satisfied, it moves on to checking the Apache dependencies, using the path to the httpd binary we provided earlier:

==> Finished Probing Required Perl Modules <==

/usr/bin/perl inst/apache.pl


==> Probing Apache Configuration <==

Extracting configuration data from `/usr/local/apache/bin/httpd -V`.
Reading Apache conf file: /usr/local/apache/conf/httpd.conf.
Extracting static module list from `/usr/local/apache/bin/httpd -l`.
Your Apache supports loadable modules (DSOs).
Found Apache user: nobody
Found Apache group: nobody
Checking for required Apache modules...
All required modules found.
====================================================================

Your Apache configuration suggested the following defaults.  Press
[return] to confirm each item or type an alternative.  In most cases
the default should be correct.

Apache User:                     [nobody]

The most important settings relative to Apache are the Apache user, group, and port, as well as the domain name of your new Bricolage server. The Bricolage installer probes the default Apache httpd.conf file to select default values, so you can often accept these:

Apache User:                     [nobody] [Return]
Apache Group:                    [nobody] [Return]
Apache Port:                     [80] [Return]
Apache Server Name:              [geertz.example.com] bricolage.example.com

Here I've elected only to change the hostname for my Bricolage server. Because Bricolage requires its own hostname to run, I've just given it a meaningful name. Be sure to set up DNS as necessary to point to your Bricolage-specific domain name. You can also run Bricolage on alternate ports, which can be useful on a server running Bricolage in addition to an existing web server (see the Bricolage web site for more information on running Bricolage concurrent with another web server process).

Bricolage will also check to see if your Apache binary includes support for mod_ssl or Apache-SSL. If so, it will ask if you wish to use SSL support with Bricolage:

Do you want to use SSL? [no] yes
SSL certificate file location [/usr/local/apache/conf/ssl.crt/server.crt] [Return]
SSL certificate key file location [/usr/local/apache/conf/ssl.key/server.key] [Return]
Apache SSL Port:                 [443] [Return]

Here I've elected to use the default values. If your Apache server has both mod_ssl and Apache-SSL support, the installer will prompt to find out which you wish to use. The installer will pull the default SSL certificates from the Apache conf directory; type in alternatives if you want to use different certificates or if the installer couldn't find any.

Once it has all of the Apache configuration information in hand, the Bricolage installer moves on to gathering PostgreSQL information:

==> Finished Probing Apache Configuration <==

/usr/bin/perl inst/postgres.pl


==> Probing PostgreSQL Configuration <==

Extracting postgres include dir from /usr/local/pgsql/bin/pg_config.
Extracting postgres lib dir from /usr/local/pgsql/bin/pg_config.
Extracting postgres bin dir from /usr/local/pgsql/bin/pg_config.
Finding psql.
Finding PostgreSQL version.

In order to create the Bricolage database and populate it with default data, the installer needs access to the database server as the PostgreSQL administrative or Root user, usually postgres. Then it will ask you to pick names for the Bricolage database and PostgreSQL user, which it will create:

Postgres Root Username [postgres] [Return]
Postgres Root Password (leave empty for no password) [] [Return]
Postgres System Username [postgres] [Return]
Bricolage Postgres Username [bric] [Return]
Bricolage Postgres Password [NONE] password
Are you sure you want to use 'password'? [yes] [Return]
Bricolage Database Name [bric] [Return]

Here I've accepted the default value for the Postgres Root Username. I left the password empty because by default PostgreSQL allows local users to access the server without a username. Instances of PostgreSQL installed from a package may have other authentication rules; consult the documentation for your installation of PostgreSQL for details. The Postgres System Username is necessary only if you're running PostgreSQL on the same box as Bricolage. If so, then you'll need to type in the Unix username under which PostgreSQL runs (also usually postgres). If PostgreSQL is running on another box, enter root or some other real local username for this option.

You can give your Bricolage database and PostgreSQL user any names you like, but the defaults are typical. You must provide a password for the Bricolage PostgreSQL username (here I've entered password). Next, the Bricolage installer will prompt for the location of your PostgreSQL server:

Postgres Database Server Hostname (default is unset, i.e. local domain socket)
      [] [Return]
Postgres Database Server Port Number (default is local domain socket)
      [] [Return]

Here I've accepted the defaults, because I'm running PostgreSQL on the local box and on the default port. In fact, if you leave these two options to their empty defaults, Bricolage will use a Unix socket to communicate with the PostgreSQL server. This has the advantage of not only being faster than a TCP/IP connection, but it also allows you to turn off PostgreSQL's TCP/IP support if you worry about having another port open on your server. However, if PostgreSQL is running on a separate box, you must enter a host name or IP address. If it's running on a port other than the default port (5432), enter the appropriate port number.

Next, the Bricolage installer asks how you want to install its various parts:

==> Finished Probing PostgreSQL Configuration <==

/usr/bin/perl inst/config.pl


==> Gathering User Configuration <==

========================================================================

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] 

There are essentially two ways to install Bricolage: The first, single, assumes that you will only ever have a single instance of Bricolage installed on your server. In such a case, it will install all of the Perl modules into the appropriate Perl @INC directory like any other Perl module and the executables into the same bin directory as your instance of Perl (such as /usr/local/bin).

The second way to install Bricolage is with the multi option. This option allows you to have multiple versions of Bricolage installed on a single server. Even if you never intend to do this, I generally recommend taking this approach, because the upshot is that all of your Bricolage files (with the exception of the database, the location of which depends on your PostgreSQL configuration) will install into a single directory. This makes it very easy to keep track of where everything is.

Your choice? [s] m

Next, the Bricolage installer wants to know where to install Bricolage. The default option, /usr/local/bricolage, is the easiest, but you can put it anywhere you like. All of the other relevant directories will by default be subdirectories of this directory, but you can change them too. For example, you might prefer to have the error log file in the typical log directory for your OS, such as /var/log. Personally, I prefer to keep everything in one place.

Bricolage Root Directory [/usr/local/bricolage] [Return]
Temporary Directory [/usr/local/bricolage/tmp] [Return]
Perl Module Directory [/usr/local/bricolage/lib] [Return]
Executable Directory [/usr/local/bricolage/bin] [Return]
Man-Page Directory (! to skip) [/usr/local/bricolage/man] [Return]
Log Directory [/usr/local/bricolage/log] [Return]
PID File Location [/usr/local/bricolage/log/httpd.pid] [Return]
Mason Component Directory [/usr/local/bricolage/comp] [Return]
Mason Data Directory [/usr/local/bricolage/data] [Return]

If you elected for the single installation option, then your choices would look more like:

Bricolage Root Directory [/usr/local/bricolage] [Return]
Temporary Directory [/tmp] [Return]
Perl Module Directory [/usr/local/lib/perl5/site_perl/5.8.5] [Return]
Executable Directory [/usr/local/bin] [Return]
Man-Page Directory (! to skip) [/usr/local/man] [Return]
Log Directory [/usr/local/apache/logs/] [Return]
PID File Location [/usr/local/apache/logs/httpd.pid] [Return]
Mason Component Directory [/usr/local/bricolage/comp] [Return]
Mason Data Directory [/usr/local/bricolage/data] [Return]

Again, you can customize these as you like. That's it for the installation configuration!

==> Finished Gathering User Configuration <==


===========================================================
===========================================================

Bricolage Build Complete. You may now proceed to
"make cpan", which must be run as root, to install any
needed Perl modules; then to
"make test" to run some basic tests of the API; then to
"make install", which must be run as root.

===========================================================
===========================================================

Installing CPAN Modules

Whether you elected to install optional CPAN modules, the Bricolage installer still might have identified missing module dependencies, so it's a good idea to follow the helpful instructions and run make cpan. Of course, the cpan target will implicitly execute if you just moved on to make test, but it's a good idea to run it on its own to have more control over things and to identify any possible problems. My system had all of the dependencies satisfied already (I've done this once or twice before), but you'll recall that I had elected to install the optional Text::Leventshtein module. The Bricolage installer will therefore attempt to install it from CPAN.

% make cpan
/usr/bin/perl inst/cpan.pl
This process must (usually) be run as root.
Continue as non-root user? [yes] n
make: *** [cpan] Error 1

Whoops! Don't make the mistake I just made! make cpan must run as the root user.

% sudo make cpan 
/usr/bin/perl inst/cpan.pl


==> Installing Modules From CPAN <==

CPAN: Storable loaded ok
CPAN: LWP::UserAgent loaded ok

&x2026;

Found Text::Levenshtein.  Installing...
Running install for module Text::Levenshtein
Running make for J/JG/JGOLDBERG/Text-Levenshtein-0.05.tar.gz
Fetching with LWP:
  http://www.perl.com/CPAN/authors/id/J/JG/JGOLDBERG/Text-Levenshtein-0.05.tar.gz

&x2026;

Text::Levenshtein installed successfully.


==> Finished Installing Modules From CPAN <==

I've truncated the output here, but you should have the general idea. The Bricolage installer uses the Perl CPAN module to install any needed modules from CPAN. If you encounter any problems, you might need to stop and manually configure and install a module. If so, once you're ready to continue with the Bricolage installation, delete the modules.db file in order to force the installer to detect all modules again so that it notices that you now have the module installed:

% rm modules.db
% sudo make cpan

Running Tests

The next step in installing Bricolage is optional, but will help identify any pitfalls before going any further. That's running the test suite.

% make test                                    
PERL_DL_NONLAZY=1 /usr/bin/perl inst/runtests.pl
t/Bric/Test/Runner....ok                                                     
All tests successful, 7 subtests skipped.
Files=1, Tests=2510, 21 wallclock secs ( 8.83 cusr +  1.39 csys = 10.22 CPU)

Make it So!

Once all tests pass, you're ready to install Bricolage:

% sudo make install
/usr/bin/perl inst/is_root.pl
/usr/bin/perl inst/cpan.pl
All modules installed. No need to install from CPAN.
rm -f lib/Makefile
cd lib; /usr/bin/perl Makefile.PL; make install
&x2026;
==> Finished Copying Bricolage Files <==

If you happened to select a database name for Bricolage for a database that already exists, the installer will warn you about it:

/usr/bin/perl inst/db.pl


==> Creating Bricolage Database <==

Becoming postgres...
Creating database named bric...
Database named "bric" already exists.  Drop database? [no] 

Now you have a choice. If you elect to dropt the database, the Bricolage installer will drop it and then create a new copy — but it must have Root user access to the PostgreSQL server. In other situations you might want to continue with the installed database, as in the case when your ISP has created the database for you ahead of time. You will also receive a prompt if the PostgreSQL user for the Bricolage database already exists. Again, you can either opt to drop and recreate the user or continue with the existing username:

Database named "bric" already exists.  Drop database? [no] [Return]
Create tables in existing database? [yes] [Return]
Creating user named bric...
User named "bric" already exists. Continue with this user? [yes] [Return]
Loading Bricolage Database (this may take a few minutes). 

At this point, the Bricolage installer is creating the Bricolage database. On my Mac, it takes about a minute to create the database, but your mileage may vary. Once that ends, the installer grants the appropriate PostgreSQL permissions and the installation is complete!

Done.
Finishing database...
Done.
/usr/bin/perl inst/db_grant.pl
Becoming postgres...
Granting privileges...
Done.
/usr/bin/perl inst/done.pl


=========================================================================
=========================================================================

                   Bricolage Installation Complete

You may now start your Bricolage server with the command (as root):

  /usr/local/bricolage/bin/bric_apachectl start

If this command fails, look in your error log for more information:

  /usr/local/bricolage/log/error_log

Once your server is started, open a web browser and enter the URL for
your server:

  http://bricolage.example.com

Login in as "admin" with the default password "change me now!". Your
first action should be changing this password. Navigate into the ADMIN ->
SYSTEM -> Users menu, search for the "admin" user, click the "Edit"
link, and change the password.

=========================================================================
=========================================================================

Start 'er Up and Login

That's it. Bricolage should start with the command helpfully provided by the installer:

% sudo /usr/local/bricolage/bin/bric_apachectl start
bric_apachectl start: starting httpd
bric_apachectl start: httpd started

If you set the Bricolage root directory to something other than /usr/local/bricolage, you'll need to set the $BRICOLAGE_CONF environment variable, first. For example, using Bash or Zsh, do:

% BRICOLAGE_ROOT=/opt/bricolage \
> sudo /opt/bricolage/bin/bric_apachectl start
bric_apachectl start: starting httpd
bric_apachectl start: httpd started

Once Bricolage successfully starts, point your browser to the appropriate URL and login as the admin user and change the password!

Up Next: Bricolage Runtime Configuration

Now that you have Bricolage up and running, you can start using it. Consult the documentation as directed in the README file to get started. Feel free to also subscribe to the Bricolage mail lists to ask any questions and to learn from the brave souls who have gone before you.

If you're interested in tuning your Bricolage installation, be sure to catch my next article, Bricolage Runtime Configuration, in which I'll cover all of the options when configuring Bricolage for added functionality and features.