Configuring a Local Apache/PHP/MySQL Dev Environment in OS X

Update: If you’re just getting started now, I strongly recommend looking into Vagrant instead of rolling your own environment like I describe. I still use the exact environment I detail below, but am leaning towards Vagrant soon. If you’re a WordPress developer, specifically check out Varying Vagrant Vagrants (VVV) by 10up.

 

PREFACE

These are my personal notes that I use every time I reformat or get a new computer. I’ve curated these instructions over the course of 4 years, so they are littered with links to relevant source material and have been stripped down to the exact actionable steps I need to take to get up and running. As such, this post is mostly for my own benefit, and I will regularly update it as my process changes (usually with each new OS X release).

These instructions have been updated to specifically support OS X Mavericks (10.9), but will work with Mountain Lion (10.8), Lion (10.7), Snow Leopard (10.6), and Leopard (10.5). Running 10.4 or lower? You should probably upgrade :)

I might write some follow-up posts about using this setup to create a killer local WordPress Multisite installation, and also porting your dev environment contents to live in DropBox. If so, I’ll link them up here.

Why not just use MAMP?

If you’re wondering, I like to set up my local environment, instead of using MAMP, because I prefer to have it always available. I never liked having a separate application running just so I could access my local dev setup. Also, it has always bothered me that MAMP bundled its own copies of PHP, Apache and MySQL when the only missing component that doesn’t come pre-loaded with OS X is MySQL.

Help, I’m stuck!

It’s worth mentioning here that I’m not a very smart guy, which is why I’ve kept these detailed notes for the last 4 years. These instructions work for me, but they might not work for you. If you get stuck with an issue, I suggest googling around and sharing what you discover here in the comments. It will likely be much faster than asking me for help, and will benefit everyone who reads this (me included)!

A Quick Word about my Terminal Commands

In many of the terminal instructions I use my custom bash shortcut “sub” to open a given file in Sublime Text 2 via command line. You can substitute “sub” for your text editor of choice (e.g. “vi” for Vim, or “mate” for TextMate, or “subl” for the standard Sublime shortcut).


Install MySQL

Follow these steps, in order:

  1. Download DMG installer from http://www.mysql.com/downloads/mysql/
  2. Install MySQL
  3. Install MySQL auto-start
  4. Install MySQL pref pane
  5. Then, configure MySQL:
  6. In Terminal: sub ~/.profile
    1. Add this line to the file: export PATH="/usr/local/bin:/usr/local/sbin:/usr/local/mysql/bin:$PATH"
    2. Save and close the file.
  7. In Terminal: source ~/.profile
  8. Finally, configure MySQL socket (because OS X is looking in the wrong directory): http://www.davewidmer.net/blog/2009/03/upgrading-to-leopard-broke-my-local-development/

Configure PHP

These steps are really only to keep you sane while testing uploads and such in your projects:

  1. In Terminal: sudo cp /etc/php.ini.default /etc/php.ini
  2. In Terminal: sub /etc/php.ini
  3. Update upload_max_filesize to something like 64MB (L891 in OS 10.8)
  4. Update post_max_size to something like 64MB (L740 in OS 10.8)
  5. Save and close

Configure Apache

Update httpd.conf to enable PHP5 and Virtual Hosts:

  1. In Terminal: sub /etc/apache2/httpd.conf
  2. Uncomment the include for PHP5 (L117 in OS 10.8, L111 in older releases)
  3. Uncomment the include Virtual Hosts (L477 in OS 10.8, L623 in older releases)
  4. Save and close the file.
  5. If you’re running OS X 10.7 or earlier, you’ll also need to enable “Web Sharing” in System Preferences > Sharing.

Setup Virtual Hosts (http://foundationphp.com/tutorials/vhosts_leopard.php):

Update: If you’d rather have “*.dev” dynamically mapped to “~/Sites/www/*”, check out this great article on Apache zero-config development. Then, follow this article on using DNSmasq to redirect all .dev traffic locally.

For the example below, you’ll want to replace “rzen.dev” with your own custom URL, and “username” with your own OS X username.

  1. In Terminal: sub /private/etc/hosts
  2. Add the following line to the file:
    1. 127.0.0.1 rzen.dev
  3. Save and close the file.
  4. In Terminal: sub /private/etc/apache2/users/username.conf
  5. Add the following lines to the file:
    1. <Directory "/Users/username/Sites/">
          Options FollowSymLinks Indexes MultiViews
          AllowOverride All
          Order allow,deny
          Allow from all
      </Directory>
      
      <VirtualHost *:80>
         ServerName rzen.dev
         DocumentRoot "/Users/username/Sites/"
      </VirtualHost>
  6. Save and close the file.
  7. Finally, flush the DNS cache & Restart Apache (you’ll want to do this any time you edit your hosts file and virtual hosts setup):
    1. In Terminal: dscacheutil -flushcache
    2. In Terminal: sudo apachectl restart

In my setup I’ve registered rzen.dev to point to my ~/Sites/ folder, rzen.wp to point to ~/Sites/wordpress/, and rzen.php to point to ~/Sites/phpMyAdmin. This means I’ve created a separate pointer for each domain in my hosts file, and a separate <VirtualHost> container for each in my apache .conf file.

 

Apache Error Notes

Later, if apache ever goes south and starts spitting 403 Forbidden, or some other error, check the error log. You can open it from inside Terminal: sub /var/log/apache2/error_log

If the problem is “Symbolic link not allowed or link target not accessible”, confirm that your symlinked folder, it’s parent directory, et al, have sufficient permissions for owner and group (http://forums.dropbox.com/topic.php?id=40992#post-337655).


Upgrading OS X?

Be aware that with every upgrade OS X is likely to overwrite your edits to Apache’s httpd.conf file. Specifically, you’ll probably need to edit /etc/apache2/httpd.conf once again and uncomment the lines for including PHP (L118) and enabling Virtual Hosts (L478).

This has at least been true both for upgrading to OS X Mountain Lion (10.8) and OS X Mavericks (10.9), and probably true in upgrading to releases before those.


The Optional (but recommended) Bits

Install Sequel Pro

This app is amazing, and it works brilliantly for manipulating both local and remote databases. And it’s free!
Download Sequel Pro

Install phpMyAdmin (if you hate living in the future and using Sequel Pro)

  1. Download latest version of phpMyAdmin from http://www.phpmyadmin.net/home_page/index.php
  2. Unzip to ~/Sites/phpMyAdmin/
  3. Rename config.sample.inc.php to config.ing.php
  4. On L36 change $cfg['Servers'][$i]['AllowNoPassword'] to true
  5. By default, your login will be root with no password

Install WordPress

  1. Download the latest version of WordPress from http://wordpress.org/download/
  2. Unzip to ~/Sites/wordpress/
  3. Create a new database for your install via phpMyAdmin to use during installation
    • Database server will be localhost
    • Username will be root
    • Password will be blank
  4. Pro-Tip: Once installed, edit wp-config.php add define('FS_METHOD','direct'); somewhere before the “That’s All, stop editing here” comment. This will enable direct access to the file system when running automatic updates and make your local dev experience mui guapo.

Install Git

Visit http://git-scm.com/ and download + install the latest version. Done.

Install SVN

For some reason, beginning in Mountain Lion (OS X 10.8), Apple stopped packaging SVN with Mac OS. So, you’ll need to download “XCode Command Line Tools” separately by signing in as a Developer (after registering for a free account using your Apple ID) here: https://developer.apple.com/downloads/index.action.

Alternatively, you can download SVN directly from WanDisco: http://www.wandisco.com/subversion/download#osx. I recommend using 1.7+.

Enable SSL

If you ever have need to test a site or service locally using https://, my co-worker @jtsternberg has written up a wonderfully detailed step-by-step of his experience doing just that. You can read it here: How to set up SSL with OSX Mountain Lion’s built-in Apache

22 comments on “Configuring a Local Apache/PHP/MySQL Dev Environment in OS X

  1. You’re working way too hard, especially if you want to keep this up to date. Use a package manager, such as homebrew or macports, and you’ll not only halve the time you spend in set up, but will make updates and security patching quick and painless as well. Not to mention that the Apple provided versions of PHP and Apache are generally slow and usually out of date.

    IIRC, MAMP Pro has an “always on” option, if that was one of your chief concerns.

    • Thanks for the feedback, Eric! I have to disagree, though.

      The entirety of what I do above takes me less than 20min, start-to-finish, on a fresh machine. I’m sure homebrew or macports is faster, but I’ve never been bothered with updating to the latest versions of anything because there is little for me to be on the most current setup when the hosts I’m interacting with are still several versions behind. I’ve also never noticed any lag in my local build, it’s always invariably faster than any remote dev I do.

      My cheif concern with MAMP was that I was annoyed to see it running in my dock, and that it cost money (via Pro) to get features like “always on” and the ability to use custom URLs instead of localhost:8888.

  2. Brain, Kudos on the geekery. I have a linux box that functions as a webserver and a network share. Don’t know the pros and cons of that (probably security concerns like Eric said) but I had to follow similar steps to get it up and running. I really love it because it’s always running and I can access the files from any home computer using SMB or AFP. I use terminal/ftp if I am away from home. I used to use WAMP on my windows machine because if I remember correctly it’s more of a hassle on Windows, but on *nix it’s a breeze. :-)

  3. I’d actually recommend using VirtualHostX — I migrated to it about six months ago, and it’s wicked simple to handle all your apache configuration and hosts stuff automagically.

    Also makes it really easy for me to set up a local.whatever.com install for each client site.

    I’m not normally a geek for GUIs over cli, but it just makes it ridiculously simple to do, and handles all the vhosting configs and such for you.

  4. Some extra notes on Apache errors:

    I just upgraded from Snow Leopard to Mountain Lion over the weekend, and along with being super annoyed at the butchering of some usability stuff that I had loved, my local sites were giving Forbidden errors, but no mention of symlinks in the log (at least not that I saw).

    I saw this post (http://brettterpstra.com/fixing-virtual-hosts-and-web-sharing-in-mountain-lion/) that had me re-enable a couple of things that were turned off in an apache config file, and then I also had to create a your-username-here.conf file in etc/apache2/users with this content:


    Options Indexes MultiViews FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all

    there was only Guest.conf in there after upgrading.

  5. Dude, you are too hard on yourself—this is an excellent post full of valuable information.

    The only thing I did differently was install mysql via homebrew. But I didn’t get the prefPane, or the startup items. I downloded the DMG for those.

    Thanks!

  6. It was hard to find your posts in google search results.
    I found it on 17 place, you have to build some quality backlinks , it will help you to get more visitors.
    I know how to help you, just search in google – k2 seo tricks

  7. “…it has always bothered me that MAMP bundled its own copies of PHP, Apache and MySQL when the only missing component that doesn’t come pre-loaded with OS X is MySQL.”

    If you only have one site to make a dev environment for, I agree that MAMP is overkill. Note that I’m not echoing “why not just install MAMP” but rather, “you ought to use it if it is the right tool for the job.” The thing about bundling its own copies of PHP and Apache is that OS X comes with PHP 5.4.24 while MAMP bundles 5.1.6, 5.2.17, 5.3.28, 5.4.26, and 5.5.10 which gives you a much better chance of matching the environment on the production webserver. You can also customize the environments specifically for each site. If you’ve ever wasted a bunch of time tracking down a bug on your production server that doesn’t appear on your local machine, well that is what MAMP is for. Not as an out-of-the-box replacement for production webservers.

    If it bothers you that MAMP bundles PHP and Apache, you’re missing the point. By which I don’t mean to suggest that you’re dense—you clearly know what you’re talking about. MAMP just serves needs you don’t seem to have.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>