Step-by-step: Installing Project Mercury 1.1 (Beta) on Ubuntu Lucid

You are viewing a wiki page. You are welcome to join the group and then edit it. Be bold!

Here are step-by-step instructions for building Project Mercury 1.1 (BETA!!!) on a fresh Ubuntu Lucid server using the configuration manager BCFG2. Project Mercury is known to work on AWS, Rackspace, RackspaceCloud and Linode. We have AMIs of Mercury 1.1 Beta for AWS EC2 (see: and (soon) a Linode script for Mercury 1.1 (both on Ubuntu Lucid).

6/1/10: Updates for multi-site support
7/12/10: Added EBS-boot and hudson support

Project Mercury Step By Step (using the BCFG2 configuration manager)

1) Start Ubuntu Lucid (10.04):

Our work is currently based on Lucid distribution of Ubuntu. If you want to use Amazon for your infrastructure there are many AMIs available, we prefer the ones provided by Canonical. View a list of AMIs at We currently have Mercury 1.1 Beta config files for Ubuntu Lucid and CentOS 5.5 running on AWS, Rackspace and Linode. Make sure that your slice, linode, virtual box (et al) is at least 12gb.

2) Configure apt sources and get updates:

Here we download some apt sources lists to make sure everyone is on the same page:

echo -e 'APT::Install-Recommends "0";\nAPT::Cache-Limit "100000000";' | sudo tee /etc/apt/apt.conf
sudo wget -O /etc/apt/sources.list.d/mercury.list

Note: 2014 11 16 this URL is not longer valid

It seems apt-get can't find Hudson...Found this out in Step 10

sudo nano /etc/apt/sources.list.d/mercury.list

Replace 'deb binary/' with 'deb binary/' <== I had to use

Replace '' and '' with '' on all lines referencing a 'karmic' repository

sudo wget -O /etc/apt/sources.list.d/aws.list
sudo wget -O /etc/apt/preferences.d/lucid
sudo wget -O /tmp/keys.txt
sudo apt-key add /tmp/keys.txt
sudo apt-get update; sudo apt-get -y upgrade; sudo apt-get -y dist-upgrade

You may see "W: Duplicate sources.list entry" errors during the apt-get update - these are innocuous and occur because we do have some duplication in /etc/apt/sources.list.d/mercury.list (vs. /etc/apt/sources.list) to make sure everyone is starting from the same point regardless of VPS and the default set of apt-sources decided upon by that VPS. You may also be asked to configure grub-pc (AWS only) - leave the line blank. You will then be asked if it's ok to "Continue without installing GRUB" - say "Yes".

If you prefer aptitude to apt, you'll want to copy the contents of /etc/apt/preferences.d/lucid into /etc/apt/preferences due to a bug in aptitude (see

3) Install and configure BCFG2:

Time to install BCFG2 and BZR and some other packages used by Mercury and configure BCFG2:

sudo apt-get -y install bzr bcfg2-server gamin python-gamin python-genshi

**note - If you are installing the latest (as of 8 January 2011) Ubuntu Lucid 64 bit image in Amazon AWS, or locally using vmware, you may also run into the following error:

E: Dynamic MMap ran out of room. Please increase the size of APT::Cache-Limit. Current value: 25165824. (man 5 apt.conf)

Please follow the thread at for a work around and then put in the command above (again).

If you do not get the error or after using the workaround, proceed as follows:

sudo bcfg2-admin init

Will result in the following questions (recommended answers in bold) where (accept default) means hit return/enter):

Store bcfg2 configuration in [/etc/bcfg2.conf]: (accept default)
Location of bcfg2 repository [/var/lib/bcfg2]: (accept default)
Directory /var/lib/bcfg2 exists. Overwrite? [y/N]: y
Input password used for communication verification (without echoing; leave blank for a random):(accept default)
What is the server's hostname [hostname]: localhost
Input the server location [https://hostname:6789]: https://localhost:6789
Input base Operating System for clients:
1: Redhat/Fedora/RHEL/RHAS/Centos
3: Mandrake
4: Debian
5: Ubuntu
6: Gentoo
7: FreeBSD
: 5

You may be prompted to input your
Country (Two Letter Code)
State (Full Name)
Locality Name (eg, city)

Warning: /etc/bcfg2.conf already exists. Overwrite? [y/N]: y
Generating a 1024 bit RSA private key
writing new private key to '/etc/bcfg2.key'
Signature ok
Getting Private key
Repository created successfuly in /var/lib/bcfg2

If you receive a message, "Error global name 'keypath' is not defined occured while trying to write configuration file to '/etc/bcfg2.conf'.", see the discussion at for a possible work-around.

Now we want to download the BCFG2 config files from launchpad.
If you see "You have not informed bzr of your Launchpad ID..." after the bzr command, launchpad is simply telling you that you need to login to "upload" - which we're not doing here - so you can safely ignore this message.

sudo rm -rf /var/lib/bcfg2/
sudo bzr branch lp:pantheon/1.1 /var/lib/bcfg2
echo -e "<Clients version=\"3.0\">\n</Clients>" | sudo tee -a /var/lib/bcfg2/Metadata/clients.xml
sudo sed -i "s/^plugins = .*$/plugins = Bundler,Cfg,Metadata,Packages,Probes,Rules,TGenshi\nfilemonitor = gamin/" /etc/bcfg2.conf

Ensure that bcfg2-server isn't running

ps -ef | grep bcfg2

If bcfg2-server is running, try stopping the server and check again to see if it's running:

sudo /etc/init.d/bcfg2-server stop
ps -ef | grep bcfg2

If it is, kill all the bcfg2 processes:

sudo kill -9 {process number}

4) Start the BCFG2 server:

Here we start the bcfg2 server and wait until it spins up (this will require several minutes) - you know the server is ready when you see "serve_forever() [start]" in the syslog (the tail -f command monitors the file).

sudo /etc/init.d/bcfg2-server start; sudo tail -f /var/log/syslog

When the output stops, you can control-c to exit the tail and move on to the next steps.

5) Start the BCFG2 client:

Note that bcfg2 -vqed can take some time (can take 15 minutes or more!) - it's done when the command prompt returns:

Non-AWS servers:

sudo bcfg2 -vqed

*if you replaced the location of the Hudson package in Step 2, then you may get a warning:

< WARNING: The following packages cannot be authenticated!
<   hudson

Don't worry, it will continue...

AWS* servers:

sudo bcfg2 -vqed -p 'mercury-aws'

EBS-boot AWS* servers:

sudo bcfg2 -vqed -p 'mercury-aws-ebs'
  • *The -p 'mercury-aws[-ebs]' parameter is required for AWS servers only during installation (now), and is not required on subsequent starts of the bcfg2 client--`"sudo bcfg2 -vqed' will work just fine.

If you get the error "Server failure: Protocol Error: 401 Unauthorized" make sure the first line in your /etc/hosts file looks like this:
Ensure that localhost is before localhost.localdomain!     localhost localhost.localdomain

6) Install Drush:

Drush is a very useful command-line Drupal management system (see The latest version of Drush includes Drush Make:

sudo pear upgrade --force Console_Getopt
sudo pear upgrade --force pear
sudo pear upgrade-all
sudo pear channel-discover
sudo pear install drush/drush

7) Install Mercury:

Here we ask drush to download code from our project page on and install some needed Drupal modules.

sudo rm -rf /var/www
sudo drush make --working-copy /etc/mercury/mercury.make /var/www/

if you recieve an error, use the following:
sudo bzr branch --use-existing-dir lp:pressflow /var/www

8) Install ApacheSolr:

We replace Drupal's built-in search with ApacheSolr which is faster, less resource-intensive and modular:

sudo wget
sudo tar xvzf apache-solr-3.3.0.tgz
sudo mkdir /var/solr
sudo mv apache-solr-3.3.0/dist/apache-solr-3.3.0.war /var/solr/solr.war
sudo mv apache-solr-3.3.0/example/solr /var/solr/default
sudo mv /var/www/sites/all/modules/apachesolr/schema.xml /var/solr/default/conf/
sudo mv /var/www/sites/all/modules/apachesolr/solrconfig.xml /var/solr/default/conf/
sudo chown -R tomcat6:root /var/solr/

9) Prepare Pressflow files and dirs:

Pressflow ( is a distribution of Drupal with integrated performance, scalability, availability, and testing enhancements:

sudo mkdir /var/www/sites/default/files

Proceed as follows:

sudo cp /var/www/sites/default/default.settings.php /var/www/sites/default/settings.php
sudo chown -R root:www-data /var/www/*
sudo chown www-data:www-data /var/www/sites/default/settings.php
sudo chmod 660 /var/www/sites/default/settings.php
sudo chmod 775 /var/www/sites/default/files

10) Add hudson to sudoers and restart hudson:

Initially, we're only using hudson for running, cron.php and bcfg2 -vqed but there's much more coming...
echo "hudson ALL = NOPASSWD: /usr/local/bin/drush, /etc/mercury/, /usr/bin/fab, /usr/sbin/bcfg2" | sudo tee -a /etc/sudoers
sudo usermod -a -G shadow hudson
sudo /etc/init.d/hudson restart

11) Run the Mercury Init Hudson job

Hudson provides an interface to some system scripts including the Mercury Init script. To run the script log into hudson by directing your browser to http://yourdomain.tld:8081 and click on "Log In" in the upper right hand corner. Hudson is setup to use the system login/password. Some virtual servers providers, like AWS, don't have a password. You can change this by ssh'ing to the server and typing:

sudo passwd username

Here, you can also follow the instructions at and open an ssh tunnel to Hudson. However the instructions at provides a different port to Hudson. Specifically for Amazon AWS users you will need to change it as follows:

ssh -L 8081/localhost/8081 -i /path/to/securitykey

NOTE: For those not familiar with ssh tunneling, the above command is being done on your local computer (laptop, desktop, etc), not the server on which you are setting up Mercury. So locally you are setting up an ssh tunnel to the server being setup. The ssh tunnel command enables the link http://localhost:8081/ to communicate with Hudson on the Mercury server.

Once logged in, click on "Mercury Init" and then "Build Now" which does the following:

  1. setup mysql, tomcat and varnish to use /mnt to save space on / (which is only 10GB on a EC2 small instance) - AWS servers only.
  2. configure postfix with a usable hostname and check for (and download) updates to mercury and pressflow (and apply the mercury updates via BCFG2).
  3. configure APC, varnish, tomcat and PHP memory usage based on the system memory using the /etc/mercury/ script
  4. send a unique but non-identifying hash to us so we can get an idea of how many Mercury users there are.

You can follow the progress of the script by clicking on the running job (lower left corner) and then "Console Output".

If the Hudson script fails, read this issue.

If you are on a VM with a burstable RAM solution (eg. Virtuozzo), Mercury can get an inaccurate reading of your available RAM due to the way the VM handles the burstable RAM resources. If running "free -m" reports a total Mem far greater than what you'd expect, it's possible it's including the burstable RAM in it's calculation. In this case, Mercury will not be able to automatically configure the APC, Varnish, etc memory limits appropriately. To correct, manually update your /etc/mercury/server_tuneables to appropriate values based on your server's guaranteed RAM, and allow bcfg2 to update your configuration with the following command:

bcfg2 -vqed

12) Configure Pressflow:

  1. Go to your site in your web browser
  2. Choose the Mercury profile (This will setup the appropriate modules and settings.)
  3. Database name = "pantheon"
  4. Database username ="root" (no password yet - we set it below)
  5. After pressflow is configured:

  6. Set the mysql root password and create a non-root account, changing new_user and new_password to appropriate values):
  7. # Login to MySQL as root
    mysql -u root
    # Set root user password
    mysql> set password for root@localhost=PASSWORD('new_password');
    # Create new user and give a password
    mysql> create user 'new_user'@'localhost' identified by 'new_password';
    # Set privileges for new user
    mysql> grant all on pantheon.* to 'new_user'@'localhost';
    mysql> flush privileges;
    mysql> \q
  8. Update your Pressflow install with the new mysql account information by editing
    /var/www/sites/default/settings.php (again using the appropriate new_user and new_password values):
  9. sudo nano -w /var/www/sites/default/settings.php

    And change:

    $db_url = 'mysqli://username:password@localhost/databasename';

    to what you set up for the new user above. Make sure to edit the 'mysqli:' and not the 'mysql:' portion.

    $db_url = 'mysqli://new_user:new_password@localhost/pantheon';

Next Steps

  • If you're interested in using the new multi-site ability, see
  • To see what can be configured on your Mercury server, see
  • We using hudson to run drupal/drush cron jobs. We intend to add much more to hudson in the future. If you choose to turn it off via the tuneable, then run the following to make sure cronjob gets run:

    sudo crontab /etc/mercury/templates/cron

  • Time to populate your new Mercury server!