Local Drupal Development Setup on Mac OS X

Why a local development setup?

Having an organized development setup and methodology is essential to your personal productivity as a Web Programmer/Designer. If you are a Drupal programmer or theme developer you must have a place to work and try out new ideas. Depending on your resources, server administration skills, and any unique requirements you may have, there are several options. You could have a remote server just for development which may be convenient if you are collaborating with others. But if you are working alone, or just on a particular part of a project, a local web server, PHP, MySQL, setup is more efficient. This article details how to setup such an environment on Mac OS X.

Before beginning this endeavor I did a little searching on the net to see just what my options would be. I know OS X comes with a configured Apache web server (you just have to turn on Web Sharing) and PHP, and a MySQL binary package is available. However I read in a few places that there is no GD graphics support in the OS X system PHP. I wanted to check out the features of the system PHP for myself.

Seeing what features the OS X system PHP provides.

To see what features the OS X installed PHP has you can enable Web Sharing and run a PHP script that contains the phpinfo() function.

But first PHP has to be enabled in the Apache web server configuration. To do this and a few other things I will detail here you have to be able to edit configuration files, and not all of the files you need to edit are visible from the OS X Finder by default.

Go to Applications -> Utilities and open the Terminal app. An easy editor to start with is “nano” which is available on OS X, it’s easy because most of the commands are listed at the bottom of the editor, the ^ symbol represents the “control” key. Type this command in a Terminal window

sudo nano /etc/apache2/httpd.conf

and enter your account password when prompted.Page down with ^V until you see this line

#LoadModule php5_module        libexec/apache2/libphp5.so

then remove the hash symbol, this uncomments the line.
Write the file with ^O and then “return”, then exit with ^X.It is also possible to make all files visible in the Finder and then use a GUI editor to do your editing. To make all files visible in Finder enter this line at a Terminal prompt

defaults write com.apple.Finder AppleShowAllFiles YES

Then restart the Finder by going to the Apple menu -> Force Quit or pressing the Command-Option-Escape keys, select Finder and click Relaunch. You can now see all files in the Finder including the /etc/apache2/httpd.conf file mentioned above. To open and edit that file from the Finder you need an editor that can prompt for your account password to obtain permission to write the file. The TextEdit editor provided with OS X can’t do that, editors like BBedit or TextMate can.To return the Finder to the previous settings enter

defaults write com.apple.Finder AppleShowAllFiles NO

into Terminal and restart Finder again.Once the /etc/apache2/httpd.conf file has been edited you need to start or restart the Apache web server, go to System Preferences -> Sharing and enable Web Sharing or disable and re-enable, if it was already enabled.

Then create the following PHP script like so

nano /Library/WebServer/Documents/info.php

the script should contain this one line

<?php phpinfo();

Save the file and then enter localhost/info.php into your browser address bar, you should see a page with detailed information on the default OS X PHP.Does the system installed OS X PHP have the GD graphics library we are looking for? You can read the phpinfo() page to find information about the system installed PHP. The answer is that on OS X 10.5 Leopard there is no GD graphics module. On OS X 10.6 Snow Leopard which was released after I did this initial setup, the system installed PHP is version 5.3.0 and there is an installed GD module, however at the time of this writing there are some issues getting Drupal 6 to work with PHP 5.3. So if you want a local Drupal setup with the GD graphics module the system provided PHP on either OS X 10.5 or 10.6 isn’t sufficient.

What are the alternatives if your OS X system installed PHP doesn’t have the modules you need?

Since I want a PHP setup with the GD module installed that Drupal can run under cleanly the system php on OS X 10.5 or 10.6 is not going to do it for me. What are the options?

  • Compile from source.
    • Another alternative would be to compile PHP on your own with GD
      support — not everyone has the skills and knowledge for this
      option and even if you do it is time consuming.
  • The Fink Project or Darwin Ports projects may have the needed packages.
    • These projects package Unix software for installation on Mac OS X.
  • Install the PHP package from http://www.entropy.ch/software/macosx/php/.
  • Use MAMP, an all in one app which contains PHP5, MySQL, and Apache.

Since I don’t yet have the MySQL server installed I’ll go with MAMP.

MAMP Setup On Mac OS X

  • Download MAMP.
  • Unzip and double-click the .dmg to mount the image.
  • Follow the instructions and copy to Applications.
  • Launch the MAMP.app. The MySQL and Apache servers are started.
  • The first thing to do is set the preferences to your needs.
    • In the small MAMP window click preferences and go through the four sets.
      • Start/Stop — the defaults are fine.
      • Ports — I prefer to run the server on their normal ports so I’ll select Set to Default Apache and MySQL ports. If you select this you will have to enter your account password when starting and stopping MAMP.
        • Make sure Web Sharing is disabled or the MAMP Apache won’t start (they can’t both listen on port 80).
      • PHP — Check PHP Version 5 and Zend Optimizer then select eAccelerator or XCache.
      • Apache — this sets the Document Root which is where all your web site files will be stored. The default location is within the MAMP folder so if you upgrade MAMP you will overwrite this folder, for this reason you may want to change this setting or make sure to backup this folder. I’ll leave this default for now.
    • Then click OK, enter the password when prompted and click Open start page.
  • Next go to the Start Page. The Start Page has some useful information that you should read through as well as the interface to phpMyAdmin.
    • You can also follow the instructions to change the MySQL root password on the FAQ page although this is not a big security concern on a development server. The FAQ doesn’t list all the steps, they are: 
      • /Applications/MAMP/Library/bin/mysqladmin -u root -p password <NEWPASSWORD>
        • When prompted for the current password enter root.
      • also change the password in — /Applications/MAMP/bin/phpMyAdmin/config.inc.php
        • line 86 $cfg[‘Servers’][$i][‘password’] = ‘root’;
      • and in the file /Applications/MAMP/bin/mamp/index.php
      • and /Applications/MAMP/bin/stopMysql.sh
  • A few settings changes and a few things to make life easier.
    • You will most likely want to delete the MAMP favicon which is here — /Applications/MAMP/bin/favicon.ico.
    • Edit /Applications/MAMP/conf/php5/php.ini and increase the PHP memory limit to 128MB. 
      • memory_limit = 128M      ; Maximum amount of memory a script may consume
    • Putting the MAMP bin directories on your PATH
      • If you are going to access MySQL, PHP, and Apache from the command line it is convenient to have their bin directories on the system PATH. The system PATH is a list of directories that the system searches through when you type a command at the system prompt, looking for that command to execute. So if you type mysql at the bash prompt it will only execute if it is in the PATH. To add the MAMP MySQL, PHP, and Apache bin directories to your PATH on OS X do this.
        • Open the Terminal app. You should be in your home directory. 
          nano .bash_profile
        • Enter the following two lines and save the file. 
          PATH=/Applications/MAMP/bin/php5/bin:/Applications/MAMP/Library/bin:$PATH
export PATH
        • It is important that the MAMP bin directories be before the current PATH which is represented by $PATH since even if Web Sharing isn’t activated the Apple installed Apache is on the PATH. 
          source .bash_profile
        • This has to be done to tell the current shell to read in the file you just created. From here on it will be read in every time you launch the Terminal App or create a new Terminal window. It won’t be read in if you just type “bash” to start a new shell process from the current shell.
      • After completing the above, the commands: mysql, mysqladmin, and apachectl from MAMP can be executed by typing them at a command prompt, as long as MAMP is running of course. The command line php does not depend on MAMP being up and running.
    • Create a .my.cnf access file in your home directory then instead of mysql -uroot -p and the password you can just type mysql. 
      nano .my.cnf
      • Then enter the following lines, using the current username and password. 
        [client]
user=root
password=root

Another thing to keep in mind is that just like the default Document Root setting the MySQL database files are stored within the MAMP folder –/Applications/MAMP/db/mysql — so upgrading MAMP will overwrite them. Changing this location setting is not as easy as setting the Document Root. The mysql directory could be moved and a symbolic link to it created or backup these databases using mysqldump.

Setting up Drupal under the localhost domain.

    • Check Drupal out from cvs so it can be updated easily. Assuming there is nothing in the htdocs directory at this point run the following commands. 
      cd /Applications/MAMP/
rmdir htdocs
cvs -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal 
checkout -d htdocs -r DRUPAL-6-13 drupal
    • Create the database. Assuming you have the .my.cnf file in your home directory the commands would be:
mysql
create database drupal;
    • Copy then edit settings.php.
cd /Applications/MAMP/htdocs/sites/default
cp default.settings.php settings.php
nano settings.php
    • Change the $db_url line to reflect your username, password, and database name. 
      $db_url = 'mysqli://root:@localhost/drupal';

Enter http://localhost/install.php into your web browser and go through the install. Use username@localhost as the e-mail address for the administrator account where username is your short Mac username. Mail will then be delivered to your local account. You can access this e-mail with the mail command from the Terminal. More about how to handle e-mail during development is explained in the next section which describes a multi-site setup.

Multi-site setup

    • If you are just beginning with Drupal, just want to experiment, or know that you only have one site to develop, having one site in the default folder may be all you need. If like myself you have a need to manage multiple sites setting up a multi-site configuration with one copy of Drupal core is the way to go.I will go through the procedure I used to set up the development copy of this site noquarterarcade.com.

      As described in the INSTALL.txt file in the Drupal source code distribution Drupal handles multi-site setup by comparing the domain name to the directory names in the “sites” directory, so if I type example.com into a browser and the name example.com resolves to the IP address of a computer on the Internet and that computer has a functioning Drupal install with a sites/example.com directory the web page ‘www.example.com’ will be served.

      • So how do you make the name that you want to use for your local dev site resolve to your local computer?
        • This is done by editing the /etc/hosts file, your computer will look here first to try to find the IP address of a name it needs to resolve. 
          sudo nano /etc/hosts
        • Add an entry so the name you want to use resolves to what is known as the local loopback IP 127.0.0.1 
          127.0.0.1	localhost localhost.localdomain dev.example.com
        • You may have to flush the dns cache for this to take effect on OS X.
          • lookupd -flushcache in OS X 10.4 and below
          • dscacheutil -flushcache in OS X 10.5
      • Another question to consider is what name to use. If I have the site example.com up and running on the Internet I could still setup my development site as example.com and when I have the proper line in the /etc/hosts file to resolve the name to the local computer I’ll see and be able to work on the local copy. If however I want to view the actual site example.com I would have to remove the entry from the /etc/hosts file. I’ve found that when I am working on a development copy I often need to look at the actual site and I don’t want to edit the /etc/hosts file every time I need to do this. It can also be confusing if you put the entry in /etc/hosts and forget that it’s there. So I choose a simple convention, if I want to set up a development copy of example.com I use the host name dev.example.com and I put an entry in /etc/hosts that I can just leave there.One thing worth mentioning is even though you pick a local hostname such as dev.example.com or test.example.com you still want to name the directory example.com. Because of the way that Drupal searches for matches between the hostname and the site directory, this will work on both the development site dev.example.com and the live site example.com. It also ensures that the paths to resources stored within this directory stay the same. The most organized approach is to then put all site specific resources: files, modules, themes, etc. in that directory.
      • Once you have MAMP up and running these are the steps needed to set up a site.
        • Enter the local hostname in the /etc/hosts file as described above.
        • Create the directory within the sites folder. Either through Finder or with Terminal. 
          cd /Applications/MAMP/htdocs/sites
mkdir example.com
        • Create the database with either phpMyAdmin or Terminal. Since this is just a development copy it’s acceptable to just create the database with myslqadmin and not bother with the GRANT statement as described in the INSTALL.mysql.txt of the Drupal source distribution. If you have the .my.cnf file in your home dir it’s as easy as 
          mysqladmin create databasename
        • Copy the default.settings.php file to sites/example.com/settings.php, edit the file and add the database connection info. 
          cp default/default.settings.php example.com/settings.php
nano example.com/settings.php
          • $db_url = ‘mysqli://root:password@localhost/databasename’;
      • Go to your browser and run the install.
        • dev.example.com/install.php
      • During the install use your short Mac username and localhost, username@localhost as the e-mail address for the Administrator account. This will deliver the mail locally to /var/mail/username as it’s unlikely your home machine is set up to send out mail any other way.
      • And that’s it, the site is setup. Follow the same procedure to create multiple sites. Each site should have it’s own sites/anothersite.com directory, its own database, and settings.php file.
    • Virtual Hosts
      • Setting up Apache Virtual hosts is not required for the setup just described but to log requests and errors for each site individually it is needed.
      • Edit /Applications/MAMP/conf/apache/httpd.conf 
        sudo nano /Applications/MAMP/conf/apache/httpd.conf
      • This should be entered once before the VirtualHost containers, which should go at the end of the file.
NameVirtualHost *:80
      • Then enter a Virtual Host container for each hostname.
<VirtualHost *:80>
      ServerName dev.example.com
      DocumentRoot /Applications/MAMP/htdocs
      ErrorLog /Applications/MAMP/logs/dev.example.com-error_log
      CustomLog /Applications/MAMP/logs/dev.example.com-access_log combine
 </VirtualHost>
      • Then stop and start MAMP, or a faster way is to just restart apache from the command line. 
        sudo /Applications/MAMP/bin/apache2/bin/apachectl restart
      • If you then look in /Applications/MAMP/logs you will see the log files have been created. The best way to view them is at the command line with the tail command which shows the last 10 lines of a file by default. 
        tail /Applications/MAMP/logs/dev.example.com-error_log

This will display log entries continuously.

tail -f /Applications/MAMP/logs/dev.example.com-error_log
    • Handling e-mail during development
      • To view the first e-mail that Drupal mailed after the Administrator account was created you could use the “mail” command from the command line. Type the number of the message to view it and then type q to quit, the message is then moved to an mbox file in your home directory. A better program to view mail from Terminal is mutt which can be downloaded from www.mutt.org it has to be compiled however so you need the Developer tools installed. If you have them installed it’s as simple as
curl -O ftp.mutt.org—mutt-1.4.2.3.tar.gz
tar zxf mutt-1.4.2.3.tar.gz
cd mutt-1.4.2.3
./configure
make
sudo make install
      • Another way to view the mail is with the Thunderbird e-mail client.
        • In the Local Folders Inbox create a new Folder such as DrupalMail.
        • Find where the folder (it’s actually a file) you created is on your hard drive, the path is something similar to
          • /Users/username/Library/Thunderbird/Profiles/xxxxxxxx.default/Mail/Local Folders/Inbox.sbd
          • Once you are in that directory in Terminal delete the DrupalMail file and create a symbolic link to /var/mail/username
rm DrupalMail
ln -s /var/mail/todd DrupalMail
        • You should then see any e-mail sent to username@localhost there unless you access it first with mail or tell mutt to move it to the mbox.
    • So how to handle e-mail during development? Now that you have a way to view the local system mail install the Drupal reroute_email module and then put username@localhost as the e-mail for it to reroute to.

And that’s it. If you followed these instructions you’re up and running with a local multi-site Drupal development environment on Mac OS X. Make sure to back up your sites directory and your databases if you are working on something important.

Start Typing