Are you a client?

« back to all blogs in Web Design and Development

How to Set Up a Local ExpressionEngine 1 Development Environment on Mac OS 10.6

Here at Imp Designs, we develop sites either in Ruby on Rails or ExpressionEngine. With Ruby on Rails, everyone has a running copy of the app on their local machine; changes are visible immediately and testing browser compatibility is largely just a matter of firing up Parallels and perhaps editing a hosts file so you can see it. With ExpressionEngine, it’s make a change, commit the changes, push to the server, then start testing. Why not just run EE locally? Well, because EE isn’t very portable. You see, ExpressionEngine stores a pant-load of configuration settings in it’s database. Frustration about this situation is well documented, but ExpressionEngine’s features and flexibility still make it our first choice for relatively simple sites. Still, it’d be nice to be able to run an EE site locally and avoid a bazillion cycles from the development environment to the server. So after a bit of trial and error and with a couple of caveats (which I’ll list at the end of this article), here’s how to make it happen with ExpressionEngine 1 (we’ll get to EE2 in another post, honest).

What you’ll need. This isn’t for the wysiwyg set. If the terminal scares you and you’re afraid to poke under the Mac OS hood, run away. You’ll need to install MySQL, enable PHP, and set up a virtual host for your site. Installing MySQL and enabling PHP aren’t in the scope of this article… JFGI (Don’t know what that means? Google “JFGI"). You’ll need a copy of your EE install, a dump of the database in .sql format, comfort working with the terminal and a willingness to poke about in EE’s config file. Oh and one more thing… you should be running EE 1.6.9 or higher. Earlier versions of EE aren’t compatible with the PHP version Mac 10.6 has installed. You can make it work with earlier versions, but it’s almost as much trouble as simply upgrading.

First Step: Setting up a Virtual Host. Your first task is to get a virtual host set up so that your local machine can serve up the site. You can either painstakingly edit a variety of apache config files… or you can cheat. I have access to Jerrod the code ninja and his incredible talent for automating mundane tasks, so I’m proud to introduce a new Ruby Gem: blavoshost. This nifty little gem automates setup of virtual hosts. To install, open your terminal and type:

sudo gem install blavoshost

Be ready to enter your password. All done? Great! Now we’ll use blavoshost to automate the virtual host set up. Get the name of the directory your EE files are in and type this into the terminal:

sudo blavoshost add name-of-directory

Stuff should have just happened. Restart Apache with this command:

sudo apachectl restart

Now you should have a virtual host set up that will serve your site locally at http://name-of-directory.local.

Next Step: Set up your database. To accomplish this, you’ll need to have a copy of your EE database in .sql format. If you’re hosted on a WHM/cPanel managed server, use PHPMyAdmin to export a copy to your local drive. Most likely it’ll drop into your downloads folder. Assuming that’s the case, use these commands to set up your database:

mysqladmin create database-name
mysql database-name < ~/Downloads/database-name.sql

Now the jiggery-pokery… editing the config file. Here’s the tedious part, editing the config file. And there’s a few things you should know about ExpressionEngine 1 and the importance of this little file. By default, ExpressionEngine stores a bunch of configuration information in the database. This is crazy inconvenient if you wish to run the site in multiple locations. And the way EE stores the config information makes it difficult to edit manually in the db. Fortunately, the system/config.php file gives us a way to override all sorts of settings that are stored in the EE database (For a full list of what you can manage with this file, click here.) Warning: When updating ExpressionEngine, the updater overwrites the config file, so always keep a copy of the system/config.php file… I just copy my work over to the system/config-bak.php file.

A typical config file looks like this:

<?php

if ( ! defined('EXT')){
exit('Invalid file request');
}

$conf['app_version'] = "169";
$conf['license_number'] = "hell yeah you should buy it";
$conf['debug'] = "1";
$conf['install_lock'] = "1";
$conf['db_hostname'] = "localhost";
$conf['db_username'] = "user_name";
$conf['db_password'] = "password";
$conf['db_name'] = "db_name";
$conf['db_type'] = "mysql";
$conf['db_prefix'] = "exp";
$conf['db_conntype'] = "0";
$conf['system_folder'] = "nrlg";
$conf['cp_url'] = "http://somesite.com/site/index.php";
$conf['doc_url'] = "http://expressionengine.com/docs/";
$conf['is_system_on'] = "y";
$conf['allow_extensions'] = "y";
$conf['multiple_sites_enabled'] = "n";
$conf['cookie_prefix'] = "";

What we want to do is modify this file so that it’ll set the configuration properly regardless of where the files are ‘living’. We’re going to set up an if statement to check which environment the site is running on and store environment specific configuration, and we’re going to use standard php variables to set up common paths in a manner that will allow the site files to work regardless of their location. Here’s an edited config file:

<?php

if ( ! defined('EXT')){
exit('Invalid file request');
}

$conf['app_version'] = "170";
$conf['license_number'] = "seriously, buy it";
$conf['debug'] = "1";
$conf['install_lock'] = "1";
$conf['db_hostname'] = "127.0.0.1";

if($_SERVER['HTTP_HOST'] == 'name-of-directory.local'){
  $conf['db_username'] = "root";
  $conf['db_password'] = "";
  $conf['db_name'] = "local_db_name";
  
} else {
  $conf['db_username'] = "username";
  $conf['db_password'] = "password";
  $conf['db_name'] = "production_db";
}  

$conf['cp_url'] = "/system_name/index.php";
$conf['theme_folder_url'] = "/themes/";
$conf['theme_folder_path']= $_SERVER['DOCUMENT_ROOT']."/themes/";
$conf['tmpl_file_basepath']=$_SERVER['DOCUMENT_ROOT']."/template_dir_name/";
$conf['site_url'] = "/";
$conf['db_type'] = "mysql";
$conf['db_prefix'] = "exp";
$conf['db_conntype'] = "0";
$conf['system_folder'] = "system_name";
$conf['doc_url'] = "http://expressionengine.com/docs/";
$conf['cookie_prefix'] = "";
$conf['is_system_on'] = "y";
$conf['allow_extensions'] = "n";
$conf['multiple_sites_enabled'] = "n";

So here’s what’s going on. First, the db_hostname needs to be changed to 127.0.0.1. Curious why? JFGI (see above). Next check out the start of the if statement. We’re checking to see if our site is located in our local directory. If it is, we’re feeding EE the database settings for the local environment. If it’s anywhere else, we’re loading the production settings. Next are a series of settings you will probably use, but you may not use all of them. Note the use of PHP variables to either define the document root or the server host depending upon whether you’re setting a path or a url. Some of these settings shown are specific to how we develop—we save templates as files and hide the index.php using .htaccess— so you may need to modify some of these settings accordingly. Refer to this site for a complete explanation of all config settings.

Them Thar Caveats. Running the site locally makes checking template codes, stylesheet tweaks and such much easier. But anything you might do that requires writing to the database will have to be duplicated on the live site… things like adding a field to a weblog, adding a member group, editing categories, adding entries. You’ll have to work out the best way to work with a site in development. Maybe it’s making that sort of edit in the live site, then exporting the updated database and replacing your local copy. Maybe it’s getting your code ninja to write you a script to do that for you.

Conclusion. Is all this worth the effort? I guess that depends… if you enjoy the Ruby on Rails ‘develop on your desktop’ experience, this brings working with EE a little closer to that vibe. During the stylesheet setup cycle and for testing javascripts and such, this is a much easier way to test changes.

NOTE: The latest version of blavoshost assumes we’re dropping the files into a hosting account and appends /public_html to the file path in the /etc/apache2/sites-enabled/nameofyourdirectory.conf file. You may have to open this file and edit it to view your site properly. Assuming you have textmate and you’ve configured it to work with your shell, type

sudo mate /etc/apache2/site-enabled/nameofproj.conf

to edit.
Addendum: If you’re using a module/plugin/extension that stores a file path in the ExpressionEngine database, you’ll have to manually set that path for whatever environment you’re working in. For example, if you’re using any of the Pixel & Tonic add-ons that utilizes fieldtypes, you’ll need to set a path for that. How will you know you need to do this? The EE tags will render instead of the desired content.

Leave your thoughts on this

paulthomas said on July 19th, 2011 @ 6:44pm

.. I’m -really- looking forward to the post on installing EE2 locally ..  [please]

reply to this add my thought

You must register or Log in to post commments