I’ve been using this particular configuration for several years, but when I picked up a new laptop recently, I decided to start from scratch. There were a ton of settings, scripts, and programs installed on my old machine that I no longer used, and I wanted them gone.

Feel free to use this guide on any Mac, but you may find that there are differences on your machine if it’s not a fresh install of Mavericks or Mountain Lion (10.9 or 10.8). These are the exact steps I used to get things running on my MacBook Pro, and to be sure I followed the guide and repeated the steps on a Mac Mini. Both worked well, but please let me know if you encounter any issues on your machine.

Why Not Just Use MAMP?

MAMP is a package that will install MySQL, PHP, and Apache on your Mac all with one download, and a quick install. It’s a great option and MAMP Pro, the paid version, will provide most of the features you need to run multiple web sites on your machine. I don’t use it because most of what it offers is already a part of OS X, and I prefer to customize my environment beyond what MAMP provides out of the box. If I’m already going to be playing around with the config files, I may as well go the distance. The main benefit of MAMP is that it leaves all your default system settings alone, sandboxing your development environment. I don’t get any benefit out of that. It also allows you to easily turn on and off services. I don’t ever turn them off, so that’s not any help to me either.

Housekeeping

Mac OS X  is a great operating system for developers, but many of the features important to us are turned off to make the OS more easy to use for everyday tasks, and more secure. Many of the configuration files we need to edit are hidden away in directories that do not show up in the Finder by default. I’m not going to tell you how to edit files here. Some people prefer command-line tools like Vim or Pico. I change my mind a lot, but currently like to use Sublime Text for everyday text file editing. It’s not free, but I find the features well worth the price. If you’re going to be using a text editor every day, you’re going to want to pay for a good one. Sublime Text can open files like any other GUI text editor, and can also be invoked from the command line. Make sure you’re familiar with editing config files in the text editor of your choice before continuing.

Everything we’ll be installing here is free software, and you can certainly go a long way without having to pay a cent for any of your software. However, don’t be afraid to pay good money for great apps. If you’ve bought a Mac, you already understand that spending money on something of quality usually saves you time in the long run. Software works the same way. Below are some of the programs I use regularly. Yes, I know there are four different IDEs listed—I can’t make up my mind.

Xcode

First, you need to have Xcode (Apple’s development bundle) installed for a few of these tools to work. You can get by without it if you try really hard, but if you’re a developer, you’re probably going to need to have it at some point. It’s massive, so start downloading it now. Grab it from the App Store, and then grab a coffee or play with your kid or dog.

For OS X 10.9 (Mavericks), the developer command line tools can be installed by running the following command within terminal.

xcode-select --install

This will trigger a software update dialog box. Click install and wait for it to complete. If this does not work, download the installation package from Apple. You will need an Apple developer account to do this.

For OS X 10.8 (Mountain Lion), install the developer command line tools from within Xcode. Open Xcode (you can close the start-up dialog that will come up). Go to Preferences and click “Downloads”, then the “Components” tab. The developer command lines tools can be installed from that tab.

Macports

Macports is open-source software that helps you install and keep up-to-date thousands of open source applications for the Mac. Many how-to guides for installing development tools involve Macports or one of the other similar installers. The installation page has simple instructions for installing Macports on Mavericks, and other recent versions of OS X. You must wait until the Xcode installation is complete, as MacPorts depends on it.

You’ll be downloading an up-to-date version, so there should be no need to run the built-in self updating command, but do it anyway. It’s good practice and confirms that your installation was successful. In your terminal, run the following:

sudo port -v selfupdate

MySQL

This is technically optional. You may prefer another kind of DB, or no DB at all. Feel free to skip this if you don’t need it, but really, you probably do. MySQL no longer comes pre-installed on Mountain Lion as it did with previous versions. Download it here. Pick the latest version of MySQL for the latest version of OS X. There is currently no version specifically for 10.9, but the 10.7 one works fine. Choose the 64bit “DMG Archive” one. You will need to install the main package, the startup item package, and the preferences pane package. All will be included in the DMG. Once this is done, you can start up MySQL from your system preferences.

Your Hosts File

Your machine has a little file located at /private/etc/hosts that tells your machine which IP addresses to use for the URL you type into your browser. normally these are passed on to your DNS server, but the hosts file allows you to bypass that. This allows you to pick any domain you like, and tell your computer to assume that domain should map to your local machine.

I use the domain http://home.dev to refer to my machine. We need to tell our computer to point all requests for that domain to our local IP. I add IPv6 entries for these domains as well, since OS X Lion and Mountain Lion seem to resolve the domain much faster when both are present.

  1  ##
  2  # Host Database
  3  #
  4  # localhost is used to configure the loopback interface
  5  # when the system is booting.  Do not change this entry.
  6  ##
  7  127.0.0.1  localhost
  8  255.255.255.255    broadcasthost
  9  ::1             localhost 
 10  fe80::1%lo0    localhost
 11  
 12  
 13  127.0.0.1     home.dev
 14  fe80::1%lo0   home.dev
 15

Save the file. This takes effect immediately, and does not require a restart. It’s magic.

dnsmasq

This is a great little tool to that allows us to use wildcard subdomain names.

With the default apache settings, you can add as many sites as you like in subfolders of the web root. You can have sites like this:

However, that creates a problem. When you have each site in a folder, it’s more difficult to manage the settings for each site. Each one must then have a different absolute root. The solution is to create a subdomain for each site, and use URLs like these:

We can accomplish this by placing all three sites in our hosts file, but then we need to keep adding entries every time we add a new site. dnsmasq allows us to do this by interrupting each request that ends with .dev and forwarding it to a designated IP address (127.0.0.1 in our case).

To install dnsmasq, we use the previously installed Macports. In your terminal window type:

sudo port install dnsmasq

dnsmasq will be downloaded and installed on your machine. A message will be displayed that gives you an additional command that needs to be executed to launch dnsmasq at startup.  For me it was:

sudo port load dnsmasq

The next step is to edit the dsnmasq configuration file. We need to tell it that all domains that end in .dev are to point to our local IP address. Open up the file: /opt/local/etc/dnsmasq.conf

Look for this section, and add the part in blue

 64  # Add domains which you want to force to an IP address here.
 65  # The example below send any host in double-click.net to a local
 66  # web-server.
 67  #address=/double-click.net/127.0.0.1
 68  address=/.dev/127.0.0.1

Save the file and run the following three commands to reload the dnsmasq configuration and clear your machine’s DNS cache.

sudo launchctl unload -w /Library/LaunchDaemons/org.macports.dnsmasq.plist
sudo launchctl load -w /Library/LaunchDaemons/org.macports.dnsmasq.plist
dscacheutil -flushcache

There’s one more small thing that needs to be done to allow dnsmasq to work its magic. It needs to be able to intercept DNS requests that your computer makes. We allow it to do this by using your local IP address as the primary DNS server. Your existing DNS server(s) will be listed after your local IP. You can edit you DNS servers from the Network section of your System Preferences. With you current connection selected, click the Advanced button and select the DNS tab. Add 127.0.0.1 before your existing settings. Make sure it’s before your existing DNS address.

We’re now done with dnsmasq, and if all goes well, you’ll never need to think about it again. Now, to get Apache going.

Your Local Web Root

Apache has a default location for storing website files, but I prefer to create my own web root that is independent of Apache. You can place your web files anywhere you wish, but I just put them in a directory called /www on my main hard drive. Put yours wherever you wish. In that folder, I have a few subfolders. /www/home is a main website that I use to list all my local sites (I’ll show you how to make that site dynamic later on).  /www/sites is the folder in which I place each of my other sites. Each of those site folders has a webroot (/www/sites/client1/wwwroot), and an assets folder (/www/sites/client1/assets), where I keep photoshop comps or other documents related to the site.

Apache

Step one is easy. It’s actually almost done. Mountain Lion is the first version of OS X without Apache in the “sharing” section of the preferences pane. No big deal though, since you just need to start it up once using the terminal. Open up the Terminal app, and enter the following command. You’ll be asked for your administrator password.

sudo apachectl start

That’s it. Test it out by visiting http://localhost in your browser. You should see a simple page that says “It Works”. Apache is up and running, and is ready to serve your sites. It will stay on until you turn it off (I never turn it off), and will start up automatically each time you start your computer. Don’t worry about taxing your computer’s resources by running Apache. It won’t be a problem.

You should also try http://home.dev, which should work since that domain is mapped to your local IP in your hosts file, and http://ANYTHING.dev should also work, since dnsmasq is pointing all *.dev domains to the local IP as well.

Apache will serve up sites as is, but there are a few quick changes we need to make to the configuration files before we are ready to go. Using your favorite text editor, open up /private/etc/apache2/httpd.conf

If you’re going to be using PHP, you need to tell Apache to use the PHP module to handle .php files. On line 117 (could be different on your system), you need to uncomment this line (remove the “#”)

116  #LoadModule perl_module libexec/apache2/mod_perl.so
117  #LoadModule php5_module libexec/apache2/libphp5.so
118  LoadModule hfs_apple_module libexec/apache2/mod_hfs_apple.so

becomes

116  #LoadModule perl_module libexec/apache2/mod_perl.so
117  LoadModule php5_module libexec/apache2/libphp5.so
118  LoadModule hfs_apple_module libexec/apache2/mod_hfs_apple.so

and on line 477, in order to allow us to add multiple websites to Apache:

476  # Virtual hosts
477  #Include /private/etc/apache2/extra/httpd-vhosts.conf
478

becomes

476  # Virtual hosts
477  Include /private/etc/apache2/extra/httpd-vhosts.conf
478

Then we need to edit the httpd-vhosts.conf file in the /private/etc/apache2/extra/ directory. You can leave everything in the file as is, and add the following to the end of the file.

43   
44   <Virtualhost *:80>
45   VirtualDocumentRoot "/www/home/wwwroot"
46   ServerName home.dev
47   UseCanonicalName Off
48   </Virtualhost>
49
50   <Virtualhost *:80>
51   VirtualDocumentRoot "/www/sites/%1/wwwroot"
52   ServerName sites.dev
53   ServerAlias *.dev
54   UseCanonicalName Off
55   </Virtualhost>
56

Then run the following to force Apache to load your new config files:

sudo apachectl restart

This configuration allows you to use the URL http://client1.dev on your local machine with your site files stored in /www/sites/client1/wwwroot

Now, you don’t need to update config files every time you add a new site. Simply add the necessary folders to your “sites” directory, and the site will work locally with its own subdomain.

A Custom Home Page

Now that you have a bunch of local sites running on your machine, you can bookmark them all, or you could do something fancy, and create your own custom home page that lists all the sites currently available on your machine.

If you’ve got the development chops to build this yourself, go right ahead. All you need is some kind of script that can analyze your sites directory, and a way to output it. I have a PHP script that I’ve used for years to do this. Disclaimer: I do not use PHP very much, and my code is probably less than great. If you’re better at PHP than me, which is likely, and have suggestions for improvement, by all means let me know.

The small site I use for my local home page is available on GitHub.

Suggestions?

Hopefully this has been of some use to you. If you have any comments of better ways to do things, leave a comment here or find me on twitter.