When your http://localhost/~username/ sites go haywire, it’s time to dig into your Apache config files

As Rails pros know, Phusion Passenger allows you to serve multiple Rails apps on the same Apache webserver instance with few configuration or deployment headaches. When you install it in your local Mac dev environment, you can easily work on a bunch of Rails projects simultaneously without having to manually start and stop individual server instances all the time. The OS X Passenger preference pane makes deployment even easier. Just add a project, give it a custom local URL, and point it at a directory. You’re good to go.

But what happens if you’re already using OS X’s built-in Apache webserver to dish up local content such as PHP applications or static HTML? When I first got Passenger up and running, all of my local sites in /Users/<username>/Sites/ stopped working. It took a bunch of digging, but I eventually realized that something in my Apache configuration had gotten messed up during the Passenger installation process. I was missing the configuration file for my OS X user account. OS X generates this file the first time you enable web sharing for any individual user. It’s responsible for mapping your /Sites subdirectory to localhost URLs, so that http://localhost/~<username>/myapplication/ points to /Sites/myapplication/index.html.

The file should live here:

/private/etc/apache2/users/<username>.conf

If it gets blown away, all you need to do is replace it and populate it with meaningful instructions. The contents should look like this:

<Directory "/Users/<username>/Sites/">
	Options Indexes MultiViews
	AllowOverride None
	Order allow,deny
	Allow from all
</Directory>

Once you’ve created and populated the file, just bounce Apache by turning Web Sharing off and then on again in the Sharing prefpane of System Preferences. Voila, your http://localhost/~username/ URLs should start working again.

Just in case you want a little more background, here’s how this file gets executed by Apache:

• The root Apache config file is here:

  /private/etc/apache2/httpd.conf
  

• It includes the userdir module for serving local user content:

  LoadModule userdir_module libexec/apache2/mod_userdir.so
  

• Further down, it includes a separate config file for user directories:

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

• Inside that file, you should see code like this:

  # Settings for user home directories
  #
  # Required module: mod_userdir
  
  #
  # UserDir: The name of the directory that is appended onto a user's home
  # directory if a ~user request is received.  Note that you must also set
  # the default access control for these directories, as in the example below.
  #
  UserDir Sites
  
  #
  # Users might not be in /Users/*/Sites, so use user-specific config files.
  #
  Include /private/etc/apache2/users/*.conf
  

• Finally the line Include /private/etc/apache2/users/*.conf calls the <username>.conf file we created above.

Share/Bookmark