Skip to content

Installing Bricolage 2.0.1 on Ubuntu 10.04 LTS (Lucid Lynx)

Jump to bottom Edit New page
mikeraynham edited this page Jun 3, 2011 · 44 revisions

This page contains a step-by-step guide to installing Bricolage 2.0.1 on a clean Ubuntu 10.04 LTS (Lucid Lynx) installation. It uses Apache 2 and PostgreSQL 8.4. A selection of optional CPAN modules are installed, including Template::Toolkit.

It differs slightly from other installation guides in that it:

  • uses local::lib to contain all the CPAN modules within the Bricolage installation directory
  • runs Bricolage under its own user (optional)
  • installs Bricolage into a non-default directory (/srv/www/bricolage/2.0.1/) (optional)
  • uses App::cpanminus to install all required and optional CPAN modules prior to the installation of Bricolage
  • describes the installation of some of the more awkward CPAN modules, such as the Crypt::* modules and Net::FTPServer
  • creates a simple shell wrapper so that the Bricolage application files receive the correct BRICOLAGE_ROOT and local::lib environment settings

Update the system

sudo apt-get update
sudo apt-get upgrade

Install dependencies

sudo apt-get install \
  apache2 \
  apache2-mpm-prefork \
  apache2-prefork-dev \
  build-essential \
  libapache2-mod-apreq2 \
  libapache2-mod-perl2 \
  libapache2-request-perl \
  libexpat1-dev \
  libgif-dev \
  libgmp3-dev \
  libjpeg62-dev \
  libpng12-dev \
  libpq-dev \
  libtiff4-dev \
  postgresql \
  postgresql-server-dev-8.4

Configure Apache

/etc/init.d/apache2 stop

Remove system startup links for Apache (Bricolage has its own Apache startup script):

sudo update-rc.d -f apache2 remove

SSL: Apache SSL support is optional.

Enable the Apache request library and mod_ssl. Do not restart Apache after enabling these modules:

sudo a2enmod apreq ssl

Create a self-signed certificate for Apache

This step is only necessary if you have chosen to use Apache SSL, and if you are not using a certificate from a trusted certificate authority. Self-signed certificates are usually only useful for testing, as browsers that encounter them will produce untrusted certificate warnings.

Note: Ensure that the certificate CommonName (CN) matches the server name given in /etc/hosts

sudo mkdir -p /etc/apache2/conf/ssl.crt/
sudo mkdir -p /etc/apache2/conf/ssl.key/
sudo make-ssl-cert /usr/share/ssl-cert/ssleay.cnf /etc/apache2/conf/ssl.crt/server.crt

The resulting file needs to be split into a key file and a certificate file:

sudo cp /etc/apache2/conf/ssl.crt/server.crt /etc/apache2/conf/ssl.key/server.key

Edit server.crt and remove the entire -----BEGIN RSA PRIVATE KEY----- to -----END RSA PRIVATE KEY----- section:

sudo vim /etc/apache2/conf/ssl.crt/server.crt

Edit server.key and remove the entire -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- section:

sudo vim /etc/apache2/conf/ssl.key/server.key

Configure Postgres authentication

The default installation of PostgreSQL 8.4 on Unbuntu sets ident authentication for the postgres super user. Here, we change that to MD5 password authentication, and then set a password. This may not be suitable for your needs. Please see the relevant documentation for more information.

See the Ubuntu PostrgreSQL guide for a very quick introduction to PostgreSQL.

See the official PostgreSQL 8.4 Client Authentication documentation for a more thorough explanation of authentication methods.

Set a password:

sudo -u postgres psql postgres
\password postgres

Press Control + D to exit.

Change authentication mode:

sudo vim /etc/postgresql/8.4/main/pg_hba.conf

# Database administrative login by UNIX sockets
#local   all         postgres                          ident
local   all         postgres                          md5

# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD

# "local" is for Unix domain socket connections only
#local   all         all                               ident
local   all         all                               md5

Restart Postgres:

sudo /etc/init.d/postgresql-8.4 restart

Configure CPAN

If you haven’t done so already, you may wish to configure CPAN:

cpan
Would you like me to configure as much as possible automatically? [yes]
o conf prerequisites_policy follow
o conf build_requires_install_policy yes
o conf commit
exit

Install local::lib and cpanminus

sudo cpan local::lib App::cpanminus

Prepare Bricolage extlib directory

Create the extlib directory that will hold all the CPAN modules:

sudo mkdir -p /srv/www/bricolage/2.0.1/extlib

Install required CPAN modules

These take a while to install:

cpanm --sudo --prompt -L /srv/www/bricolage/2.0.1/extlib \
  Apache::Session \
  Cache::Cache \
  Cache::Mmap \
  Class::Container \
  Clone \
  DBD::Pg \
  Data::UUID \
  DateTime \
  DateTime::TimeZone \
  Error \
  Exception::Class \
  HTML::Mason \
  Image::Info \
  List::MoreUtils \
  MIME::Tools \
  MLDBM \
  MasonX::Interp::WithCallbacks \
  Params::CallbackRequest \
  Params::Validate \
  SOAP::Lite \
  Term::ReadPassword \
  Test::Class \
  Test::File \
  Test::MockModule \
  Text::WordDiff \
  Unix::Syslog \
  XML::Simple \
  XML::Writer

Install optional CPAN modules

You may choose to install additional optional modules, or remove some of those shown. See Optional Perl Modules in Installing Bricolage.

Install libssh2 from source

Optional: This is required by Net::SFTP, so may be omitted if you don’t plan on using SFTP.

The Ubuntu 10.04 libssh2-1-dev package doesn’t work well with Net::SSH2. Instead, a later version of libssh2 will be installed from source:

sudo mkdir -p /usr/local/src/libssh2
sudo chown user:user /usr/local/src/libssh2/
cd /usr/local/src/libssh2/
wget http://www.libssh2.org/download/libssh2-1.2.8.tar.gz
tar xvfz libssh2-1.2.8.tar.gz
cd /usr/local/src/libssh2/libssh2-1.2.8/
./configure --prefix=/usr
make
sudo make install

Crypt::* modules

The Crypt::* modules — especially Crypt::DH — can take a very long time to install and test. Installing Math::Pari and Math::BigInt::GMP first will dramatically decrease the time it takes to run the Crypt::DH tests, and will also speed up subsequent operations that use these modules.

Crypt::Random may be installed as a dependency of one of your chosen optional modules. One of its tests involves pulling data from /dev/random. If your system does not generate sufficient entropy, the data in /dev/random will deplete and the test will take a very long time to complete. I found this to be the case on my build of Ubuntu on VirtualBox – perhaps due to lack of mouse input. To solve this, you can install randomsound, which “using the low order bit of the ADC output of your sound card, randomsound gathers entropy, debiases it and offers it up to your kernel’s random pool.”. Doing so on my system reduced the test time from hours to a fraction of a second:

sudo apt-get install randomsound

Warning: Be aware that some of the Crypt::* modules run tests that are very processor intensive. This may be important on production servers.

Math::Pari requires and interactive installation. Choose y if prompted to automatically fetch the GP/PARI build:

cpanm --sudo --interactive -L /srv/www/bricolage/2.0.1/extlib \
  Math::Pari

Make sure that Math::BigInt::GMP is installed before other Crypt::* modules, especially Crypt::DH:

cpanm --sudo --prompt -L /srv/www/bricolage/2.0.1/extlib \
  Math::BigInt::GMP

CPAN modules

Choose which optional modules you require:

cpanm --sudo --prompt -L /srv/www/bricolage/2.0.1/extlib \
  Crypt::SSLeay \
  Imager \
  Net::SFTP \
  Net::SSH2 \
  Template::Toolkit \
  Test::File::Contents \
  Text::Diff::HTML \
  Text::LevenshteinXS

Net::FTPServer

To use the Virtual FTP Server, you will need to install Net::FTPServer. This has a few optional dependencies that you might also want to install. See the Net::FTPServer documentation for more details.

The optional Authen::PAM module requires libpam0g-dev:

sudo apt-get install libpam0g-dev

Authen::PAM also requires user input as part of one of the tests, so you’ll need to set verbose mode when installing via cpanm — otherwise the installation will just appear to hang forever. With verbose mode enabled, you will be asked for a password part way through the tests:

cpanm --sudo -v -L /srv/www/bricolage/2.0.1/extlib \
  Authen::PAM

Net::FTPServer requires IO::stringy which is supplied by IO::Scalar. The installation fails if it is not installed. The remaining modules are all optional:

cpanm --sudo --prompt -L /srv/www/bricolage/2.0.1/extlib \
  Archive::Zip \
  BSD::Resource \
  Digest::MD5 \
  File::Sync \
  IO::Scalar

Note: Net::FTPServer may need force installing if it fails test t/240:

t/240abort.t ................. 15/16 # Failed test 15 in t/240abort.t at line 116 fail #2
#  t/240abort.t line 116 is:     ok (/^426/);
t/240abort.t ................. Failed 1/16 subtests

See “Bug #21261: t/240abort doesn’t iterate enough”.

cpanm --sudo --force -L /srv/www/bricolage/2.0.1/extlib \
  Net::FTPServer

Create a Bricolage user

Instead of using the default www-data user, we will configure Bricolage to run under its own user (bric201). For added security, this user will not have a password, a home directory or a shell:

sudo adduser \
    --system \
    --no-create-home \
    --disabled-login \
    --disabled-password \
    --group \
    bric201

Install Bricolage 2.0.1 from source

sudo mkdir -p /usr/local/src/bricolage
sudo chown user:user /usr/local/src/bricolage/
cd /usr/local/src/bricolage/
wget http://bricolagecms.org/downloads/bricolage-2.0.1.tar.gz
tar xvfz bricolage-2.0.1.tar.gz
cd /usr/local/src/bricolage/bricolage-2.0.1/

Important: The installer needs to know where to find the extlib directory. This only needs to be run once, prior to the installation:

eval $(perl -Mlocal::lib=/srv/www/bricolage/2.0.1/extlib/)

See the Installation Variables section of Bric::Admin for more information about variables that can be passed to make.

All default options can be accepted, but be aware of the following:

SSL: Apache SSL will be used by default in this configuration. You can disable it by changing the appropriate option to no when prompted with Do you want to use SSL?.

Postgres: If you configured Postgres MD5 password authentication earlier, you will need to enter the chosen password when asked for the super user password.

Note: perl Makefile.PL does not produce any output on success.

perl Makefile.PL
make \
  BRICOLAGE_ROOT=/srv/www/bricolage/2.0.1 \
  BRICOLAGE_HTTPD_VERSION=apache2 \
  BRICOLAGE_PG_BECOME_USER=1 \
  BRICOLAGE_APACHE_USER=bric201 \
  BRICOLAGE_APACHE_GROUP=bric201

You will need to enter the correct Apache2 user and group when prompted:

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

Apache2 User:			 [www-data] bric201
Are you sure you want to use 'bric201'? [yes] 
Apache2 Group:			 [www-data] bric201
Are you sure you want to use 'bric201'? [yes]

You will need to enter the relevant password details when prompted:

Should the installer connect to the database as a super user? [yes] 

Postgres Super Username [postgres] 
Password for super user "postgres": 
Confirm password: 
Are you sure you want to use this password? [yes] 

Should the installer become the Postgres system user?
This requires that the installer be run as root. [yes] 
Postgres System Username [postgres] 
Bricolage Postgres Username [bric] 
Password for Postgres user "bric": 
Confirm password: 
Are you sure you want to use this password? [yes]

Test and install:

make test
sudo make install

Create a shell wrapper to configure environment variables

Because Bricolage has not been installed in the default location, the BRICOLAGE_ROOT environment variable must be set with the correct location. Bricolage also needs to know about the extlib directory. This sort of configuration is often done by adding the necessary environment variables and configuration code to the ~/.bashrc file that belongs to the user under which the process runs. However, in this case the user (bric201) does not have a shell, a login, or a home directory. Instead, a bash script will be created which first sets the necessary environment variables, and then calls the original Bricolage script.

sudo mkdir -p /usr/local/sbin/bricolage/2.0.1
cd /usr/local/sbin/bricolage/2.0.1
sudo vim /usr/local/sbin/bricolage/2.0.1/bric.sh

Add the following code to bric.sh:

#!/bin/bash

# Set the correct path for the Bricolage installation.
export BRICOLAGE_ROOT="/srv/www/bricolage/2.0.1"

eval $(perl -Mlocal::lib="$BRICOLAGE_ROOT/extlib")

FILENAME=$(basename $0)

if [[ $FILENAME =~ ^[SK][0-9][0-9] ]] ; then
    # Called by sysvinit or manually from /etc/rc*.d/
    # Remove first three characters from filename (S|K??)
    FILENAME=${FILENAME:3}
fi

exec $BRICOLAGE_ROOT/bin/$FILENAME "$@"

Make bric.sh executable:

sudo chmod u+x /usr/local/sbin/bricolage/2.0.1/bric.sh

Use the filenames from each of the files in the /srv/www/bricolage/2.0.1/bin/ directory to create symlinks to bric.sh:

for file in $(ls /srv/www/bricolage/2.0.1/bin); \
  do sudo ln -s bric.sh `basename $file`; \
done

Usage

Instead of calling the /srv/www/bricolage/2.0.1/bin/bric_* files directly, call the symlinked files instead. For example, to start the FTP daemon:

/usr/local/sbin/bricolage/2.0.1/bric_ftpd -S

The symlink acts as a shortcut to the bric.sh script. bric.sh configures the necessary environment variables before executing the Bricolage script of the same name (/srv/www/bricolage/2.0.1/bin/bric_ftpd in the above example).

Configure the Bricolage Apache script to run at startup

cd /etc/init.d/
sudo ln -s /usr/local/sbin/bricolage/2.0.1/bric.sh bric_apachectl
sudo update-rc.d bric_apachectl defaults 92

Configure Bricolage

sudo vim /srv/www/bricolage/2.0.1/conf/bricolage.conf

Set the following as appropriate:

ALWAYS_USE_SSL          = Yes
TT_OPTIONS              = PRE_CHOMP => 3, POST_CHOMP => 0, TRIM => 1
AUTO_PREVIEW_MEDIA      = Yes
MEDIA_UNIQUE_FILENAME   = Yes

Start Bricolage and login

sudo /etc/init.d/bric_apachectl start

From a suitable browser, go to:

http://bricolage_server_hostname

Username: admin
Password: change me now!

Add a custom footer
Add a custom sidebar
Clone this wiki locally