How to category Design category Development category News category

OSX 10.8 Apache, mysql, PHP dev setup


This brief guide focuses on getting a web development setup up and running on OSX 10.8 Mountain Lion. Working with already installed software and making the configuration changes manually the aim is to establish a clear method and consistent implementation that is easy to maintain and manage. There are many useful guides out there and an some excellent shell scripts to assist – however this guide is specific to our setup and helps to keep the underlying mechanics of whats happening under the hood as transparent as possible. By going through the manual steps the daily debugging and management of your server should be a whole lot easier.

Apache setup

In 10.8 the ability to manage the server instance has been removed from the system preferences sharing options. Without the GUI starting and stopping the server is achieved by running the following commands in your terminal. If you haven’t got it already, iTerm2 is a great terminal app – and it’s on the app store…

To start it sudo apachectl start

To stop it sudo apachectl stop

To restart it sudo apachectl restart

To test your configuration apachectl -t no "sudo" required this time.

To make sure Apache starts with each reboot run –

sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist

Using the commands to manage the apache server is ultimately the best way to manage your server. One of the drawbacks of the GUI was the lack of feedback when the server fails to start, by using the commands above we can more accurately debug an manage the server instance.

On the Mac traditionally there have been two document roots, a user root and a system root. If you upgraded to Lion you may already have a "Sites" folder in your user folder, a fresh install will be missing the folder.

To create your sites folder mkdir ~/Sites

The "~" character is a shortcut in the terminal to your user folder, mkdir is the command to "make a directory".

Next – configure your sites folder, to make the system manageable we will make minimal configuration here as the aim is to contain all configuration in one place – your sites folder. This will make managing your server instance easy since you wont need to hunt around system folders. Also keeping your configuration separated from the main files makes it easier to manage when upgrades are applied.

To edit your user apache config run the following, replacing USER with your username – if your not sure of the username to use run – "whoami" in the terminal. sudo nano /etc/apache2/users/USER.conf

Copy and paste the following into the terminal Include /*.conf, you will need to prefix the string "/*.conf" with the path to your site folder. Locate your "sites" folder in the finder, position your cursor in the terminal just on the "/" then simply drag and drop the folder form the finder to the terminal, this will put the correct path to your user folder into your config. You may end up with an extra space between the path and "/", just delete this

To save and close the file in nano, simply hit ctrl+x to quit answer yes to save.

You can then configure your virtual hosts basic setup – sudo nano ~/Sites/vhost.conf

Then paste the following in, replace NAME with the default domain you want to associate with your development machine (optional – you can omit this line, however if your testing the config it will moan if that apache cant determine the servers domain name). Note – many guides will tell you to edit httpd.conf, however having your own modifications in once place outside the system files makes it a whole lot easier to maintain.

NameVirtualHost *:80
NameVirtualHost *:443
ServerName NAME:80
#optional - we live in a UTF-8 world, you may not...
AddDefaultCharset UTF-8
#enable php support
LoadModule php5_module libexec/apache2/

Now in your sites folder you can create your own *.conf files for each site you want to host locally, or simpler still you could put all your configurations in the one vhost.conf file. Note – this will not be read by your server instance untill you restart it (see above). Weather you run multiple files or one is down to personal preferance. There are many advantages of seperate configs per domain since this makes it easy to debug complex setups and even easier to simply move a few configs out the folder, if you want to disable a host.

You may need to make sure that directives can be over-riden – edit the main /etc/httpd.conf and change the following –

    Options FollowSymLinks
    AllowOverride None
    Order deny,allow
    Deny from all

To the more permissive –

    Options FollowSymLinks
    AllowOverride All
    #Order deny,allow
    #Deny from all

Site setup


We recommend you structure this folder structure in a similar way as to how we would structure them on the enterprise linux server. The "httpdocs" folder will be the location for your site files. I tend to name my local development sites the same as the live sites and alias a suffixed domain to look at my local version.

vhost.conf        - generic config
domain.conf       - specific virtual host sttings
domain/httpdocs   - web root
domain/statistics - for the log files

basic domain.conf template as follows –

<VirtualHost *:80>
   ServerName DOMAIN
   ServerAlias PREFIX_DOMAIN
   ServerAdmin webmaster@DOMAIN
   DocumentRoot "/ROOT/DOMAIN/httpdocs"
   ErrorLog "/ROOT/DOMAIN/statistics/error_log"
	CustomLog "/ROOT/DOMAIN/statistics/access_log" common
   <Directory "/ROOT/DOMAIN/httpdocs">
	Options Indexes FollowSymLinks MultiViews Includes
	AllowOverride All
	Order allow,deny
	Allow from all
	php_admin_value error_reporting 6143
	php_admin_value display_errors 1
	php_admin_value open_basedir "/ROOT/DOMAIN:/var/tmp:/usr/lib/php/pear:/tmp"

The template above needs the following replaced with your equivalent settings –

    the sites domain – we set this the same as the actual site so that we can easily run the site locally if the net is down and we want to test with a "e;live" like site.
    This is the alias domain that your going to use to view the site locally, we normally often suffix the domain with a user related string.
    the path to your sites root on the file system.


  1. Download the MySQL installer. You will need the 64bit version, first in the list. You do not need to register to download.
  2. Install MySQL
  3. Install Preference Pane
  4. Open System Preferences / MySQL
  5. Ensure the MySQL Server is running
  6. Enable MySQL to start automatically.

Add MySQL to your path by running the following in terminal – export PATH=/usr/local/mysql/bin:$PATH

To make mysql available from the command line edit the file "~/.bash_profile" and put the export line above inside it.

Note – by default MySQL will allow complete access to the server using the username "root" without a password from the localhost. To secure this account, run the following from your terminal (replacing the PASSWORD with one of your choice), note – the lowercase p before PASSWORD is required, not a typo…

mysqladmin -u root password PASSWORD
mysqladmin -u root -pPASSWORD -h localhost password PASSWORD
mysqladmin -u root -pPASSWORD reload
history -c

The "history" line clears the password from your terminal history.

Configure MySQL – if you don’t want the defaults then run –

sudo cp /usr/local/mysql/support-files/my-default.cnf /etc/my.cnf

You can then edit the /etc/my.cnf to suit your applications needs. I found the following required to make MySQL play ball…

basedir = /usr/local/mysql
datadir = /usr/local/mysql/data
pid-file = /var/run/mysqld/

Create the location for the pid file and make sure MySQL can access it…

sudo mkdir /var/run/mysqld
sudo touch /var/run/mysqld/
sudo chown -R _mysql:wheel /var/run/mysqld

I found a reboot was in order to get MySQL to read the config.

Local DNS

It’s extremely simple to make a domain point to your local machine, this can be achieved by editing your "hosts" file, simply run sudo nano /etc/hosts and add lines to the end of the file. The lines in this file are simply a list of IP address versus domain, separated by spaces. Changes to this file effect the machine immediately and are a quick and easy way to get domains pointing locally. The IP address is reserved in DNS to refer to your local machine, therfore this is the IP address you should use to map a site to your machine. For example for my test web-engineer site I may hosts file would look like –

# Host Database
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##       localhost broadcasthost
::1             localhost
fe80::1%lo0     localhost web-engineer.craig

Almost there – time for a test…

If you create a new file in your httpdocs folder – index.php (the default page) containing the following code we can validate the installation so far –


Customising PHP

Terminal time…

cd /etc
sudo cp php.ini.default php.ini
sudo chmod ug+w php.ini
sudo chgrp staff php.ini
sudo nano php.ini

Hit Crtl+w to search and look for the following settings and update as shown –

error_reporting  =  E_ALL | E_STRICT
display_errors = On
html_errors = On
extension_dir = "/usr/lib/php/extensions/no-debug-non-zts-20090626"
short_open_tag = On

Change all instances of /var/mysql/mysql.sock to /tmp/mysql.sock


Very handy debugging tool if your going to get down and dirty with your debugging… More edits required from terminal.

sudo nano /etc/php.ini

Find the line:;zend_extension="/usr/lib/php/extensions/no-debug-non-zts-20090626/" and remove the semicolon at the start

Recommend you configure your xdebug settings, then scroll to the end of the file and look for the [xdebug] section. And use –

xdebug.var_display_max_children = 999
xdebug.var_display_max_data = 99999
xdebug.var_display_max_depth = 100

Restart apache, (see above), view your phpinfo file that xdebug is now loaded.


We need PEAR! This isn’t installed by default.

cd /usr/lib/php
sudo php install-pear-nozlib.phar

Confgigure the include path – nano /etc/php.ini find and update the line: ;include_path = ".:/php/includes" and change it to: include_path = ".:/usr/lib/php/pear". Finally in your terminal run the following, note this will also add Firephp support!

sudo pear channel-update
sudo pecl channel-update
sudo pear upgrade-all
sudo pear channel-discover
sudo pear install firephp/FirePHPCore

Further reading

SSL – see for tips.

Debugging – having some fun with the configuration – don’t forget – sudo apachectl -t -D DUMP_VHOSTS will tell you which configs are loaded and which hosts come from which file…



Craig enjoys producing usable and friendly sites that look great and function well. He often also experiments with workflow automation and owns and runs web-engineer.

Comments are closed.