Blog Post

How To Setup Development Domains On OS X

Stay on Top of Emerging Technology Trends

Get updates impacting your industry from our GigaOm Research Community
Join the Community!

I do quite a bit of design and development with my company. To keep things streamlined I’ve setup my machine as a local development server to avoid the obvious hassle of having to FTP files every time I make a change that I want to see. Setting up your machine as a development server is another post for another day, but since OS X comes with Apache, this really should work for pretty much anybody on OS X.

One of the hassles with developing locally is having to access the various sites I’m working on with something like: http://localhost/theappleblog/

This isn’t very convenient in term of things like absolute links to images or other pages within the site. Ideally you’d have something like:

Notice the “.dev” instead of “.com”? That’s what we’ll be setting up. This way you won’t need to worry about the method you are linking to images and other pages. Is it a necessity for development? No. Is it nice to have? Very.

The Setup

The first thing we need to do is edit the hosts file. This file will let us override what the browser thinks of the .dev TLD since .dev doesn’t really exist in the domain world.

  1. First, fire up terminal and type in: sudo pico /etc/hosts
    This will give you something like this screenshot.
  2. Next, you’d want to type in:
    This basically tells your browser that should point to localhost and not try to search for it elsewhere.
  3. After typing in that, you’ll want to save that file (Control+X). Keep Terminal open though.
  4. Now we need to edit the httpd.conf file for Apache. For me, this is located in /private/etc/httpd/ though your setup could vary. Open up the file in your favorite code editor and do a quick search for “NameVirtualHost”. Make sure it’s not commented out. If it’s comment out, uncomment it out. If it’s not there, then add it. Either way, you should have a line with this: NameVirtualHost
  5. Below that, we’ll add a VirtualHost rule to tell our where to point to.

    DocumentRoot "/Users/UserName/Development/yourdomain"

    The DocumentRoot needs to be set to wherever your development folder is for whatever you are working on.
  6. Finally, we need to save the file and then restart Apache. Restart Apache within Terminal by typing in something like sudo apachectl graceful (depending on your setup).

After restarting Apache, you should be good to go! Fire up your browser of choice and type in your new development domain and you should see your main index file!


39 Responses to “How To Setup Development Domains On OS X”

  1. It’s worth mentioning that in the default httpd.conf for Apache2 that comes with OS X 10.5, that the vhosts go in /private/etc/apache2/extra/httpd-vhosts.conf and that the include line for that file in httpd.conf needs to be uncommented. Caused me a bit of a run around looking for the issue.

  2. Chip Brown

    So are there any ‘gotchas’ to watch out for?

    This is the kind of thing I’ve wanted to setup for months. I had no problem getting it to work at the office, but now I’m trying to set it up on my home machine with no luck.

    Both are OSX 10.4 using the default install.

    I’m trying to setup multiple testing domains with very erratic results, mostly 403 errors, then it will start working but pointing the wrong directory.

  3. Josh,

    thank you for your tutorial – although I tried the other solutions (NetInfo, Headdress) they did not really work for me. I guess I did something wrong with NetInfo and I didn’t really dug into Headress (plus I need more than just two development domains).

    I don’t think doing it the manual way by editing some files is to difficult.

    Again, thanks a lot, I definitely like my new shiny .dev-Domains :).

    Best regards

  4. That’s good if you were the only one working on said project. If you have a team then it is pretty useless. And I hope you’re running the same PHP, Ruby, SQL version as the host you paid for or is again, useless. Is it too hard to setup a hock key in your editing app to auto-upload when you save? – Ryan Merket

    If you’re working on a team, I’d hope you’d have subversion or CVS set up to check them out to your domain.

    And running the same versions as your host isn’t hard. But I’ve had no trouble developing in the latest version of PHP and MySQL on a Mac and running it using an old version of both on our Linux production server.

    And why would you want to auto-upload when you save? Shouldn’t you do testing first?

  5. I agree that this is a pretty good solution, but why go through the trouble? Why not just use MAMP?
    For each project that I’m working on I create a seperate “htdocs” directory with a “.projectname” suffix (ex. htdocs.theappleblog). Whatever project I’m currently working on, I simply rename the folder to “htdocs”. I use this technique to manage multiple sites. Some running Movable Type, some running WordPress.
    I guess the only drawback is that this is only going to work for the PHP world. Any RAILS development would have to be done through the standard Apache server or through Locomotive.

  6. Great tips everybody! Here’s mine:

    I’m a one-man shop developing small to medium sites, so I don’t need a complicated system. Here’s my super simple technique:

    Super easy, browser-bookmark based access to everyone of your dev sites.

    Here’s how:

    I keep my dev sites in the ~sites folder (PhP enabled in Apache) on my Mac. Then I saved a bookmark of the ~sites folder ( in my browser’s Bookmarks Toolbar for fast, easy access. I name the bookmark “Local Sites Index.”

    Clicking this bookmark opens a webpage listing an index of (dev) site folders in the ~sites directory; but they are listed alphabetically. Click on the “Last Modified” column header and the list re-sorts by date modified to force the most recent to the top of the list. Notice that the address in the address bar now reads: (

    Next, modify the saved bookmark’s address accordingly:

    Then put this bookmark in the Bookmarks Toolbar of ALL of your browsers that you need to test in.

    THAT’S IT! Now to see your sites, just open any browser and hit the Toolbar Bookmark you’ve just created to display a clickable index of all of your dev sites; all in their Apache/PHP glory–with the most current ones at the top of the list. (You can re-sort alphbetically by clicking the “Name” header.)

    I go one step further: I make this ~sites directory page the Homepage in my main dev browsers. Now I merely start any browser and up pops a clickable list of all my dev sites; with the most recent ones right at the top of the list!

    Summary: No typing of URLs neccessary, just launch your browser, and click once to see any site that you’re working on.

  7. Actually you should really start getting used to doing these things in directories. Both Linux and MacOs (and Windows for that matter) have started using the directories for these things. in MacOs X the /etc/hosts is there more for backward compatability. Use the “Application -> Utilities -> NetInfo Manager” utility to manage your local directory. Or even better if you are on a mac os x server domain use the networks directory to add the hosts table to all computers in one go.

  8. We use a dev server a live server and gl for local testing (svn checkouts)

    We use a dns server to route all .dev domains to the development server and all .gl domains to

    So maybe somebody can write a tutorial for installing and configuring a dns server on OS X this way.

  9. Ryan Merket said:
    > That’s good if you were the only one working on said project.
    >If you have a team then it is pretty useless.

    Assuming you have a single development computer, this method still works except instead of putting, put the IP address of the development computer. Everyone who wants to access the development site needs to put the line into their hosts file. linux, windows and mac all have a hosts file.

    This is a bit messy of course having to edit many hosts files over many computers.

    Another problem is you can’t use catchall subdomains in the hosts files eg. * like you can with DNS. I end up having multiple lines for testing eg:

    The solution to all these problems is to use DNS properly although I’ve never figured out how. Does anyone know any good tutorials?


  10. If you are using the built in apache webserver that comes with OS X (apache 1.4) I recommend the following.

    Rather than editing httpd.conf (which contains global settings), you can add the virtual host information into /etc/httpd/users/.conf.

    This is file is appended to httpd.conf once you login to OS X.

    Also, rather than editing the hosts file directly, I recommend using the tool that comes with OS X (Applications/Utilities/Netinfo Manager).

    Select Machines->localhost. Click on Duplicate. Enter your details.


  11. I wrote a script that we extensively use in the office to do just this. The script takes care of setting up Apache and Mac OS X to recognize the development host name.

    To setup a host, you would just type:


    Answer a couple prompts including what you want the virtual host’s DocumentRoot to be, and away you go. To remove a virtual host you’ve created:

    sudo virtualhost –delete

    Note that this script is assuming the stock install of Apache that comes with Mac OS X, and that you haven’t already messed around too much in httpd.conf.

  12. @ Ryan Merket – Auto upload when you save.. to what?

    My 2 cents..

    If you’re working with a team, I’ve found a great setup is to have each person do their cvs or svn checkout into a vhost directory, and have apache set up to do mass hosting. for example, i always check out to This way, everyone is working off the same machine, so you only need to maintain 1 dev database and apache setup. You also don’t have to mess with hosts files, if you know how to set up your DNS the right way. Everyone has their own checkout.

  13. That’s good if you were the only one working on said project. If you have a team then it is pretty useless. And I hope you’re running the same PHP, Ruby, SQL version as the host you paid for or is again, useless. Is it too hard to setup a hock key in your editing app to auto-upload when you save?

  14. Pretty good hint here. Doesn’t completely eliminate the Find & Replace step of replacing the local paths with the ones for the server though. Might be better to setup the host file to redirect from the actual server to the local copy and just change the host file as needed.