Setting Up a CiviCRM Development Sandbox on Ubuntu

I got myself a new development machine last Thursday, and the old one spectacularly failed two hours later (talk about timing). This means I ended up with a clean install of Ubuntu (I went with the development version of Feisty Fawn, but the below should work for the stable Edgy Eft as well) and can share with you how to setup a CiviCRM development sandbox from scratch. This tutorial is very Ubuntu-centric, but should be easily adaptable to other (especially Unix-based) operating systems. You can of course skip all the parts that are already working in your install. Webserver and PHP I’m a big fan of lighttpd, but of course Apache would be a good choise as well. First, install the lighttpd package. This will get the server installed and running; you can verify it by opening http://localhost/ in your browser. Now, for ease of use, you want to make the server run as your user (I’m assuming a private development box here). Edit /etc/lighttpd.conf and change the following line accordingly:

server.username            = "shot"

Now, change the webroot and lighttpd logs directories’ ownership accordingly by running the following:

$ sudo chown -R $USER /var/www /var/log/lighttpd

As CiviCRM and Drupal are written in PHP, you need PHP support in your webserver. For this, install the php5-cgi and php5-cli packages. Installing the MySQL support at this point is a good idea, so add the php5-mysql package to the mix. Now, the webserver configuration. Create a /etc/lighttpd/conf-available/simple-vhost.conf file with the following contents:

server.modules += ( "mod_simple_vhost" )
simple-vhost.default-host  = "localhost"
simple-vhost.document-root = "/public/"
simple-vhost.server-root   = "/var/www/"

This will allow you to use local addresses like http://drupal/ and have them served from the /var/www/drupal/public directory. lighttpd uses FastCGI for serving PHP pages, so configure that. Create a /etc/lighttpd/conf-available/php.conf file with the following contents:

server.modules += ( "mod_fastcgi" )
fastcgi.server = (
  ".php" => (
    "localhost" => (
      "bin-path"              => "/usr/bin/php-cgi",
      "broken-scriptfilename" => "enable",
      "socket"                => "/tmp/php-fastcgi.socket",
    )
  )
)

This will make lighttpd bring up PHP on restarts and listen to it on the specified socket. To actually enable the above configs, link to them from the /etc/lighttpd/conf-enabled directory:

$ tree /etc/lighttpd/conf-enabled
/etc/lighttpd/conf-enabled/
|-- php.conf -> ../conf-available/php.conf
`-- simple-vhost.conf -> ../conf-available/simple-vhost.conf

Restart the webserver with

$ sudo /etc/init.d/lighttpd restart

To test whether everything is working, create a /var/www/phpinfo/public/index.php file with the following contents:

<?php phpinfo() ?>

and add the following line to /etc/hosts:

127.0.0.1 phpinfo

Now, go to http://phpinfo/ and you should see the usual PHP status page. MySQL and PHPMyAdmin CiviCRM is based on the MySQL database, so you need to install it to get up and running. PHPMyAdmin is a nice, web-based frontend to MySQL. Install the mysql-server and phpmyadmin packages. Make a symbolic link pointing /var/www/mysql/public to /usr/share/phpmyadmin and add

127.0.0.1 mysql

to your /etc/hosts file; now you should be able to administer MySQL by going to http://mysql/ in your browser. If you want your PHPMyAdmin session to expire less often, add the following to the /etc/phpmyadmin/config.inc.php file:

$cfg['LoginCookieValidity'] = 31556952;

For security, add a password for the root user and (optionally) create a MySQL superuser for yourself. For ease of use, create a ~/.my.cnf file with the following contents (adjust as necessary):

[client]
user     = shot
password = ********

– now you’ll be able to use the commandline client without authorisation. Drupal Download Drupal from drupal.org and extract to the /var/www/drupal/public directory. Create a drupal MySQL database and a user which can access it. Add

127.0.0.1 drupal

to /etc/hosts and go to http://drupal/ – you shold be able to provide the proper settings and install a local Drupal copy. To get rid of the administer menu errors, create a /var/www/drupal/public/files directory and run the cronjob once. For clean URLs under lighttpd, create the following /etc/lighttpd/conf-available/drupal.conf file (the host regular expression will match the upcoming civicrm-16 and civicrm-trunk hosts as well):

server.modules += ( "mod_rewrite" )
$HTTP["host"] =~ "^(drupal|civicrm-(16|trunk))$" {
  url.rewrite-once = (
    "^/system/test/(.*)$" => "/index.php?q=system/test/$1",
    "^/([^.?]*)\?(.*)$"   => "/index.php?q=$1&$2",
    "^/([^.?]*)$"         => "/index.php?q=$1",
    "^/search/node/(.*)$" => "/index.php?q=search/node/$1",
  )
}

and link to it from /etc/lighttpd/conf-enabled – don’t forget to restart lighttpd for the changes to take effect. CiviCRM Finally, set up the CiviCRM development environment. Install the subversion package to get, well, Subversion. First, create a directory like /home/shot/work/CiviCRM/svn, go into it and checkout our trunk and/or the CiviCRM 1.6 branch:

$ svn checkout http://svn.civicrm.org/trunk trunk
$ svn checkout http://svn.civicrm.org/branches/v1.6 branches/v1.6

Go to PHPMyAdmin and create the civicrm_16 and/or civicrm_trunk databases; also, create a civicrm MySQL user that can access them. Drupal supports a multi-site structure that allows one Drupal codebase to serve different domains (with different module selections avaliable); we’ll use that. Create the following /var/www/drupal/public/sites structure or its subset (the civicrm.settings.php links will be broken for now, but that’s ok):

$ tree /var/www/drupal/public/sites
/var/www/drupal/public/sites
|-- all
|   `-- README.txt
|-- civicrm-16
|   |-- civicrm.settings.php -> /home/shot/work/CiviCRM/svn/branches/v1.6/civicrm.settings.php
|   |-- default
|   |   `-- civicrm.settings.php -> /home/shot/work/CiviCRM/svn/branches/v1.6/civicrm.settings.php
|   |-- files
|   |   `-- civicrm
|   |-- modules
|   |   `-- civicrm -> /home/shot/work/CiviCRM/svn/branches/v1.6
|   `-- settings.php -> ../default/settings.php
|-- civicrm-trunk
|   |-- civicrm.settings.php -> /home/shot/work/CiviCRM/svn/trunk/civicrm.settings.php
|   |-- default
|   |   `-- civicrm.settings.php -> /home/shot/work/CiviCRM/svn/trunk/civicrm.settings.php
|   |-- files
|   |   `-- civicrm
|   |-- modules
|   |   `-- civicrm -> /home/shot/work/CiviCRM/svn/trunk
|   `-- settings.php -> ../default/settings.php
`-- default
    `-- settings.php

Go to the place(s) you checked-out the Subversion codebase(s) and create a settings_location.php location file(s) there, with the following contents:

<?php
define( 'CIVICRM_CONFDIR', '/var/www/drupal/public/sites/civicrm-trunk' );
?>

(for trunk)

<?php
define( 'CIVICRM_CONFDIR', '/var/www/drupal/public/sites/civicrm-16' );
?>

(for CiviCRM 1.6). Copy the bin/setup.sh.txt file(s) to bin/setup.sh and edit as necessary. Run them; this should create all of the auto generated CiviCRM files (like DAOs and SQL scripts) and the civicrm.settings.php.sample file(s). Copy the civicrm.settings.php.sample file(s) to civicrm.settings.php and edit as appropriate; now run the bin/setup.sh file(s) to auto-populate the database(s). Create the /var/www/civicrm-16 and/or /var/www/civicrm-trunk symlinks pointing to /var/www/drupal and add

127.0.0.1 civicrm-16 civicrm-trunk

to the /etc/hosts file; Drupal now should serve the http://civicrm-16/ and/or http://civicrm-trunk/ URL(s) and allow you to enable the proper CiviCRM module in its administration interface. Finally, log in to Drupal, enable CiviCRM, add the useful CiviCRM Drupal blocks, go to Administer | CiviCRM and put in the proper path(s) in Global Settings | Resource URLs – http://civicrm-16/sites/civicrm-16/modules/civicrm/ for CiviCRM 1.6 and http://civicrm-trunk/sites/civicrm-trunk/modules/civicrm/ for CiviCRM trunk (CiviCRM not guessing these URLs properly is a bug, I’ll see whether it can be easily extended to do this automatically). Now you should have a working CiviCRM 1.6 and/or CiviCRM trunk install. The civiclear script To easily rebuild the auto-generated files and clear the CiviCRM state, I have a small script, called civiclear, that looks like the following:

#!/bin/bash
echo ' * setup.sh'
/var/www/drupal/public/sites/civicrm-$1/modules/civicrm/bin/setup.sh
echo ' * clear templates'
rm -rf /var/www/drupal/public/sites/civicrm-$1/files/civicrm/templates_c/*
echo " * [drupal] TRUNCATE cache"
mysql drupal -e 'TRUNCATE cache'
echo " * [drupal] TRUNCATE sessions"
mysql drupal -e 'TRUNCATE sessions'

It’s supposed to be run with a parameter, either as `civiclear 16` or `civiclear trunk`, and then clear the given CiviCRM install’s setup. Conclusions The above should cover setting up a full webserver/PHP/MySQL/Drupal/CiviCRM stack from scratch on an Ubuntu system. Do let me know (either in comments or by mailing to shot@civicrm.org) if there’s anything missing/broken in the above.

Comments

Note:

The repository has been relocated. On some machines this will cause a

svn: PROPFIND request failed on '/trunk'
svn: PROPFIND of '/trunk': 302 Found (http://svn.civicrm.org)

Somewhere it was suggested this is caused by a proxy server setting.

 

On other machines you get

svn: Repository moved temporarily to 'http://svn.civicrm.org/civicrm/trunk'; please relocate

 

So, this

$ svn checkout http://svn.civicrm.org/trunk trunk
$ svn checkout http://svn.civicrm.org/branches/v1.6 branches/v1.6

should become

$ svn checkout http://svn.civicrm.org/civicrm/trunk trunk
$ svn checkout http://svn.civicrm.org/civicrm/branches/v1.6 branches/v1.6