Setting up a local web server on OS X

Version 13
Last Modified: Jan 9, 2015 4:44 AM

Here is my definitive guide to getting a local web server running on OS X. This is meant to be a development platform so that you can build and test your sites locally, then deploy to an internet server. This User Tip contains instructions for configuring the Apache and PHP. I have another User Tip for installing and configuring MySQL and Perl.

Note: Yosemite introduces some significant changes. Pay attention to your OS version.

Another note: These instructions apply to the client versions of OS X, not Server. Server does a few specific tricks really well and is a good choice for those. For things like database, web, and mail services, I have found it easier to just setup the client OS version manually.


Requirements:

  1. Basic understanding of Terminal.app and how to run command-line programs.
  2. Basic understanding of web servers.
  3. Basic usage of vi. You can substitute nano if you want.

Optional:

  1. Xcode is required for adding PHP modules.

 

Lines in bold are what you will have to type in at the Terminal.

Replace <your local host> with the name of your machine. Ideally, it should be a one-word name with no spaces or punctuation. It just makes life easier.

Replace <your short user name> with your short user name.

 

Here goes... Enjoy!

 

Lion and later versions no longer create personal web sites by default. If you already had a Sites folder in Snow Leopard, it should still be there. To create one manually, enter the following:

mkdir ~/Sites

echo "<html><body><h1>My site works</h1></body></html>" > ~/Sites/index.html.en

 

PHP is not enabled in recent versions of OS X. To enable it, do:

sudo vi /etc/apache2/httpd.conf

 

Uncomment the following line:

#LoadModule php5_module libexec/apache2/libphp5.so

to

LoadModule php5_module libexec/apache2/libphp5.so

(if you aren't familiar with vi, just press 'x' over the '#' character to delete it. Then type ':w!' to save and then 'ZZ' to quit.)

10.7 Lion - line 111

10.8 Mountain Lion - line 117

10.9 Mavericks - line 118

10.10 Yosemite - line 169

 

For Yosemite only, uncomment the following line at line 166:

#LoadModule userdir_module libexec/apache2/mod_userdir.so

to

LoadModule userdir_module libexec/apache2/mod_userdir.so

 

and do the same at line 493:

#Include /private/etc/apache2/extra/httpd-userdir.conf

to

Include /private/etc/apache2/extra/httpd-userdir.conf

Save and exit.

 

And again, for Yosemite only, open the file above with:

sudo vi /etc/apache2/extra/httpd-userdir.conf

and uncomment the following line at line 16:

#Include /private/etc/apache2/users/*.conf

to

Include /private/etc/apache2/users/*.conf

Save and exit.

 

While you are in /etc/apache2, double-check to make sure you have a user config file. It should exist at the path: /etc/apache2/users/<your short user name>.conf. That file may not be created in Lion and if you upgrade to Mountain Lion, you still won't have it. It does appear to be created when you create a new user in Mountain Lion. If that file doesn't exist, you will need to create it with:

 

sudo vi /etc/apache2/users/<your short user name>.conf


For all systems other than Yosemite, use the following as the content:

<Directory "/Users/<your short user name>/Sites/">

    Options Indexes MultiViews

    AllowOverride None

    Order allow,deny

    Allow from localhost

</Directory>

 

For Yosemite, use this content:

<Directory "/Users/<your short user name>/Sites/">

    AddLanguage en .en

    LanguagePriority en fr de

    ForceLanguagePriority Fallback

    Options Indexes MultiViews

    AllowOverride None

    Order allow,deny

    Allow from localhost

     Require all granted

</Directory>


In vi, press <esc> and then ZZ to save and quit.

 

If you want to run Perl scripts, you will have to do something similar:

Note: This section cannot be done on Yosemite. Yosemite does not include /usr/libexec/apache2/mod_perl.so. It should be possible to build your own mod_perl, but that would be outside the scope of this User Tip.

 

Uncomment the following line: (In Lion this is on line 110. In Mountain Lion it is on line 116. In Mavericks it is on 117.)

#LoadModule perl_module libexec/apache2/mod_perl.so

to

LoadModule perl_module libexec/apache2/mod_perl.so

 

Then, in /etc/apache2/users/<your short user name>.conf change the line that says:

    Options Indexes MultiViews

to:

    AddHandler perl-script .pl

    PerlHandler ModPerl::Registry

    Options Indexes MultiViews FollowSymLinks ExecCGI

 

Now you are ready to turn on Apache itself.

 

In Lion, do the following:

To turn on Apache, go to System Preferences > Sharing and enable Web Sharing.

 

NOTE: There appears to be a bug in Lion for which I haven't found a workaround. If web sharing doesn't start, just keep trying.

 

In more recent versions of OS X, the Web Sharing checkbox in System Preferences > Sharing is gone. Instead, do the following:

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

 

In Safari, navigate to your web site with the following address:

http://<your local host>/

 

It should say:

 

It works!

Now try your user home directory:

http://<your local host>/~<your short user name>

 

It should say:

 

My site works

Now try PHP. Create a PHP info file with:

echo "<?php echo phpinfo(); ?>" > ~/Sites/info.php

 

And test it by entering the following into Safari's address bar:

http://<your local host>/~<your short user name>/info.php

 

You should see your PHP configuration information.

 

If you want to setup MySQL, see my User Tip on Installing MySQL.

 

If you want to add modules to PHP, I suggest the following site. I can't explain it any better.

 

If you want to make further changes to your Apache system or user config files, you will need to restart the Apache server with:

sudo apachectl graceful