Configuring Apache Wildcard Virtualhost on OS X 10.11 El Capitan


This is the second part of a series on BAMP. In this part we will configure Apache using a wildcard virtual host and explore virtual document root. This tutorial was made using OS X 10.11.3 El Capitan with Apache 2.4. My text editor of choice is TextMate and it’s command line utility is mate. So when you see that command, substitute the text editor of your preference.

Configure httpd.conf

Let’s open up our httpd.conf and get started. We’ll be loading mod_userdir, mod_rewrite, and libphp5. This will allow us to use the VirtualDocumentRoot directive, access local user websites (mymachine.local/~user), customize a user.conf, use pretty permalinks, and php.

If you’ve already edited your httpd.conf use the next two commands if not then skip ahead two.

–First we’ll back up your original httpd.conf in the same directory.

sudo cp /private/etc/apache2/httpd.conf  /private/etc/apache2/httpd.conf.backup

–Second copy over an original version.

sudo cp /private/etc/apache2/original/httpd.conf  /private/etc/apache2/httpd.conf

Now let’s open httpd.conf in our text editor.

sudo mate /etc/apache2/httpd.conf

In your text editor, find and uncomment (remove the # from) the following lines to load our desired Apache Modules.

LoadModule vhost_alias_module libexec/apache2/
LoadModule userdir_module libexec/apache2/
LoadModule rewrite_module libexec/apache2/
LoadModule php5_module libexec/apache2/

Now let’s uncomment and load the http-userdir.conf so that each user account on this computer can have their own local website.

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

That’s it. Save the changes to the file.

Configure httpd-userdir.conf

Again in your text editor open httpd-userdir.conf:

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

Change the line that reads: UserDir Sites so that we can tidily have more than just the mymachine.local/~user website stored in ~/Sites.

UserDir Sites/user-site

And uncomment the following line to allow each user to have their own unique Apache configuration.

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

Done! Now save it.

Create a user.conf

Whew, we’re on our final file. We are going to create a user.conf file in /private/etc/apache2/users. You’ll need to replace <-myusername-> with your actual user name in the commands that follow. If you already have a user.conf for your username, let’s save a copy of the original because we’ll need to overwrite it with all new directives soon.

So if you had one already execute the next two commands to save a copy to the same directory otherwise skip them.

–First we back up a copy to the same directory.

sudo cp /private/etc/apache2/users/<-myusername->.conf /private/etc/apache2/users/<-myusername->.conf.backup

–Second we make room for the fresh version.

sudo rm /private/etc/apache2/users/<-myusername->.conf

Then let’s open up our <-myusername->.conf file with a text editor.

sudo mate /private/etc/apache2/users/<-myusername->.conf

Grab this gist, add the text from it, and save the file.

Let’s review the contents:

<Directory "/Users/<-myusername->/Sites/*/">;

Defines options that will apply to all of our Sites

<VirtualHost *:80 >

The wildcard in the virtualhost allows the contained directives to be applied to requests from the localhost as well as our LAN ip address. This will make our virtualhost accessible to our LAN in the event that we run a DNS server (BIND).

VirtualDocumentRoot /Users/<-myusername->/Sites/%-2.0.%-1/%-3+

This directive will have Apache will look to the Sites folder in our home directory and navigate a specific file hierarchy for the document root of a requested domain.

The file path for VirtualDocumentRoot would then break out like this:


Here is an alternate diagram of an example folder structure for the VirtualDocumentRoot formula used above:

 |      |
 |      |----> _
 |      |
 |      |----> www
 |      |
 |      |----> accounts
 |      |
 |      |----> mail
 |      |
 |      |----> _

Notice the underscores. Those underscores are for the root domain where there is no www or other subdomain. Why the underscore? Apache will interpolate an underscore when the directive expects to receive more than the number of parts stated in the request. In other words there is no %-3+ in so Apache instead will serve up the underscore directory. Neat huh.


Using this nomenclature can make it difficult to anticipate the folder hierarchy of the various machine addresses on OS X. Here are the basics: would map to:


localhost would map to:


mymachine.local would map to:


And machine.local/~user will bypass VirtualDocumantRoot thanks to our UserDir statement in httpd-userdir.conf and map to:


Check Apache configuration and start it up:

Check your configuration.

apachectl -t

If the Syntax is OK then let’s load it and make it stick on restart.

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

For more Apache commands look here.

Let’s test things. We won’t be able to test any .dev domains yet since we don’t have BIND up and running yet; but we can test the mymachine.local and mymachine.local/~myusername.

Make sure <-mymachine-> mirrors the settings in the Sharing preference pane in System Preferences and <-myusername-> is actually your user name in the following commands.

mkdir -p  ~/Sites/<-mymachine->.local/_/test-computer-local
mkdir -p  ~/Sites/user-site/test-usr-local
open http://<-mymachine->.local && open http://<-mymachine->.local/~<-myusername->


Let me know what you think below and head on to the next article in this series:
Installing BIND on OS X El Capitan 10.11 with Homebrew

Post a Comment

Your email is never published nor shared. 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=""> <s> <strike> <strong>