Creating Your Sandbox

Fen Labalme's picture

Creating Your Sandbox - Overview

  • Code development cannot occur directly on our servers as the client users (w_CLIENT) only have read access to their SVN repositories
    • Further, it's safer to develop on a local copy of the site so as not to "bump into" other developers working on the same site
  • Therefore, CivicActions developers create a local "sandbox" on their personal development machine that enables them to (once set up) easily create copies of our client's code on their personal workstations.

See Also

Install Core Code for Multi-Site Use

The CivicActions multi-site directory structure enables multiple projects to share the same major versions of Drupal and optionally CiviCRM.

Your Sandbox Workspace

CivicActions' Best Practices strongly recommend a directory named "workspace" directly under your home directory that will be your localhost's Apache docroot. Our tools and documentation assume this directory structure.

To make it so that you can cut-and-paste most of the scripts below, in your terminal application set the WORKSPACE environment variable that will be used in the scripts:

# this is a cut-and-paste script
WORKSPACE=~/workspace
mkdir ${WORKSPACE}

If you would like to verify that this worked (and see what the variable WORKSPACE has in it) do:

echo $WORKSPACE

Note that in the scripts below, the variable is surrounded by curly brackets. These are only there to ensure that the shell can exactly determine where the variable name begins and ends should it be up against other words, etc.

Get Drupal Core(s)

Pull the Drupal version(s) you want to set up; note you can also pull Drupal 4, 5 and Pressflow should you so desire) onto your machine:

  • (Replace version numbers with the latest currently available in our SVN repository.)
# This is a cut-and-paste script
cd ${WORKSPACE}

# Set the Drupal MAJOR and VERSION numbers as you desire
# (You may want to repeat this entire section several times with different
#  values for the following variables to set up multiple installations.)
#DRUPAL_MAJOR='6'
#DRUPAL_SUFFIX='6'
#DRUPAL_VERSION='6.20'

#DRUPAL_MAJOR='6'
#DRUPAL_SUFFIX='6p'
#DRUPAL_VERSION='6.20.97-pressflow'

DRUPAL_MAJOR='7'
DRUPAL_SUFFIX='7'
DRUPAL_VERSION='7.0'

svn co https://svn.civicactions.net/repos/drupal/${DRUPAL_MAJOR}/tags/${DRUPAL_VERSION} drupal-${DRUPAL_SUFFIX}

# Effectively make the ~/workspace/ directory the Drupal sites/ directory
ln -s ${WORKSPACE} drupal-${DRUPAL_SUFFIX}/sites

# Copy .htaccess.orig to .htaccess and uncomment the 'RewriteBase /' directive
sed 's|# RewriteBase /$|RewriteBase /|' < drupal-${DRUPAL_SUFFIX}/.htaccess.orig > drupal-${DRUPAL_SUFFIX}/.htaccess
  • We copy rather than symlink the .htaccess file as it must be edited to uncomment the RewriteBase line so that it looks like this:
    RewriteBase /

    To ensure the sed (stream editor) script worked, do the following command and the output should show the original, commented # RewriteBase / line from .htaccess.orig and the uncommented RewriteBase / directive from the newly created .htaccess file:

    diff drupal-6/.htaccess.orig drupal-6/.htaccess
  • To upgrade all your Drupal sites by a minor revision, say from 6.17 to 6.19, simply:
    cd ~/workspace/drupal-6
    svn switch https://svn.civicactions.net/repos/drupal/6/tags/6.19
    • You'll then want to visit /update.php or use drush updatedb to run any needed database updates.

Get CiviCRM Core(s) (if needed)

You may not need CiviCRM for your first client PROJECT so you can skip this section if not needed. Or you may want to install a CiviCRM core for later use (or present exploration). But after working at CivicActions for a while, you'll likely find that you have clients using several different versions of CiviCRM.

  • (Replace version number with the latest currently available in our SVN repository.)
# this is a cut-and-paste script
mkdir ${WORKSPACE}/civicrm
cd ${WORKSPACE}/civicrm

svn co https://svn.civicactions.net/repos/civicrm/v3.2/tags/v3.2.5 v3.2

# Create settings_location.php file
svn export https://svn.civicactions.net/repos/civicrm/v3.2/etc/settings_location.php

# Define CIVICRM_CONFDIR as the path to the sites/ directory (which is $WORKSPACE for most sites)
sed -i -e "s|/home/clients/websites/w_PROJECT/sites|${WORKSPACE}|" settings_location.php

# Link settings_location.php file into base directory of each CiviCRM install
ln -s ${WORKSPACE}/settings_location.php v3.2
  • Just as with updating Drupal minor revisions, simply use svn switch to update e.g., v3.2.1 to v3.2.5
    • You'll then want to visit /civicrm/upgrade?reset=1 or use drush civicrm-upgrade-db to upgrade the database
  • The settings_location.php file is needed so that CiviCRM can find things when it's in a non-standard place (CiviCRM expects to be in sites/all/modules/). There will need to be a copy of (or link to) this file in the base directory of each CiviCRM install. You can see what's in this file with this command:
    cat settings_location.php

Apache Config Files in ~workspace/conf.d/

These Apache configuration files will enable your multi-site sandbox.

  • Create a conf.d directory under your workspace with Apache configuration file templates:
    # this is a cut-and-paste script
    cd ${WORKSPACE}
    svn export https://svn.civicactions.net/repos/system/conf.d
  • Edit the Apache configuration file templates:
    # this is a cut-and-paste script
    cd ${WORKSPACE}/conf.d
    for CONF in *.conf; do
        sed -i -e "s|WORKSPACE|${WORKSPACE}|" $CONF
    done
  • Include the ${WORKSPACE}/conf.d/ directory in the set of locations that Apache will search on startup for configuration directives:
    • Linux:
      # this is a cut-and-paste script
      echo "Include ${WORKSPACE}/conf.d/*.conf" > civicactions.conf
      sudo mv civicactions.conf /etc/apache2/sites-enabled/civicactions.conf
      sudo apachectl restart
    • Mac OSX with MAMP
      # this is a cut-and-paste script
      sudo echo "Include ${WORKSPACE}/conf.d/*.conf" >> /Applications/MAMP/conf/apache/httpd.conf
      ...and Restart MAMP
    • Mac OSX with Macports
      # this is a cut-and-paste script
      sudo echo "Include ${WORKSPACE}/conf.d/*.conf" >> /opt/local/apache2/conf/httpd.conf
      ...and restart Apache

Project Code Instances

We show two examples:

  • Generational Alliance (ga.6) is a standard Drupal 6 site that also uses CiviCRM
  • CivicActions home (home.localhost) uses a site-specific modified ("hacked") Drupal and CiviCRM

Standard Drupal ("PROJECT.6")

Put your code in a sub-directory of ${WORKSPACE} with a name like PROJECT.6 (for using Drupal 6), e.g. for the Generational Allaince (PROJECT="ga") site, do:

# Set your project name here, generally the vhost username without the "w_", e.g.,
PROJECT='ga'
DRUPAL_MAJOR='6'

# this is a cut-and-paste script
cd ${WORKSPACE}
svn co https://svn.civicactions.net/repos/${PROJECT}/trunk ${PROJECT}.${DRUPAL_MAJOR}

If your project will be using CiviCRM, you'll need to link CiviCRM into your project's modules directory:

# this is a cut-and-paste script
cd ${PROJECT}.${DRUPAL_MAJOR}/modules
ln -s ${WORKSPACE}/civicrm/v3.2 civicrm

Hacked Drupal ("PROJECT.localhost")

This is only necessary when a hacked Drupal Core has been used. This site will be accessible as (e.g.) http://home.localhost/ which also uses an older CiviCRM:

# Set your project name and hacked Drupal 6 version here
PROJECT='home'
DRUPAL_MAJOR='6'
DRUPAL_VERSION='6.19-search-drupal-goto'
CIVICRM='v3.1'

# this is a cut-and-paste script
cd ${WORKSPACE}
svn co https://svn.civicactions.net/repos/drupal/${DRUPAL_MAJOR}/branches/${DRUPAL_VERSION} ${PROJECT}
mkdir ${PROJECT}/sites
cd ${PROJECT}/sites
# Instead of "default" you could also say "${PROJECT}.localhost"
svn co https://svn.civicactions.net/repos/${PROJECT}/trunk default
# Link in CiviCRM
ln -s ~/workspace/civicrm/${CIVICRM} default/modules/civicrm

Create the settings.php File

  • Generally you'll sync your sandbox databases from the VHost, but if you are going to run the Drupal installation locally see Installing Drupal Locally. The rest of this section assumes you'll sync the database from the VHost.
  • Modern project trees will include a settings.inc file - if one is not in the tree, ask your Tech Lead to review creating a CivicActions-style settings.php file.
  • You'll need a settings.php file, which you can create in one of several ways:
    1. Copy and edit a settings.php file from one of your other sandbox sites
    2. SCP the settings.php file from the PROJECT VHost and then edit that. Given that Drupal-6 and Drupal-7 have such different settings file, and that we assume you have SSH access to the PROJECT VHost, this is often the easiest.
      # This is usually the case
      SITENAME=${PROJECT}
      
      # pull the Drupal settings.php file
      scp w_${PROJECT}@${SITENAME}.civicactions.net:sites/${SITENAME}.civicactions.net/settings.php .
      sed -i -e "s|live_|${PROJECT}_|" settings.php
      # You'll also need to edit the file to set your local mysql username, password and port
      # (Generally, you will want to leave the port value empty)
    3. Create a settings.php file using one of these templates and edit as needed.
  • Add special settings for your sandbox:
    # Drupal 6
    # $conf['file_directory_path'] = conf_path() .'/files';
    
    # Drupal 7
    $conf['file_public_path'] = conf_path() .'/files';
    
    # Drupal 7 - see: http://drupal.org/documentation/modules/file if needed
    # $conf['file_private_path'] = conf_path() .'/files/private';
    
    # Uncomment this if you want, or just use 'drush updatedb'
    # $update_free_access = TRUE;
    
    $conf['environment_indicator_text'] = 'LOCAL PROJECT SANDBOX';
    $conf['environment_indicator_color'] = 'green';

Create the civicrm.settings.php File

  • Generally you'll sync your sandbox databases from the VHost, but if you are going to run the Drupal installation locally (Installing Drupal Locally) you'll also want to install CiviCRM locally . The rest of this section assumes you'll sync the database from the VHost.
  • Modern project trees will include a civicrm.settings.inc file - if one is not in the tree, ask your Tech Lead to review creating a CivicActions-style civicrm.settings.php file.
  • You'll need a civicrm.settings.php file, which you can create in one of several ways:
    1. Copy and edit a civicrm.settings.php file from one of your other sandbox sites
    2. SCP the civicrm.settings.php file from the VHost and then edit that
      # pull the CiviCRM civicrm.settings.php file
      scp w_${PROJECT}@${SITENAME}.civicactions.net:sites/${SITENAME}.civicactions.net/civicrm.settings.php .
      sed -i -e "s|live_|${WORKSPACE}_|" civicrm.settings.php
    3. Create a civicrm.settings.php file using the following template and edit as needed (at the least, replace 'PROJECT' with the project's name):

Tags: 

Groups audience: 

Openness: 

Public - accessible to all