Tuesday, September 25, 2012

Installing nginx / PHP / MySQL on Mac OS X Mountain Lion

** Update: See a quicker way to do this using Homebrew (this method uses Macports, and it's considerably more difficult). **

... are you sure you want to use Macports to do this? (See the link above for Homebrew instructions instead!) ...

... okay, fine, continue on if you're sure ....


Even though OS X comes with Apache server pre-installed, our production environment at work is nginx. While nginx has downloads for Windows and Linux, there's no official mac port. Fortunately, there's Macports.

Okay, true: Macports isn't required to install nginx on a Mac. It's said that installing nginx without Macports is as easy as wget, ./configure, make, and make install. Unfortunately, I usually run into problems when compiling and installing from source. I'm definitely no Macports junkie, but I am too pressed for time to debug someone else's huge code base to compile on my machine.

That said, here's the lazy way to install a complete web development environment on your Mac. These instructions are designed for a clean install of Mountain Lion (mine is 10.8.2). It's not as bad as it looks, I promise. Except the "prep" section, skip anything you don't want installed. And hey, you'll learn a lot in the process (like I did). It's actually pretty systematic...


Install Xcode. Sorry, it's gotta happen. Macports needs it. While it's downloading, hop over to Macports.org and get the latest pkg for your system. Or run: wget https://distfiles.macports.org/MacPorts/MacPorts-2.1.2-10.8-MountainLion.pkg from the terminal.

Run Xcode and accept the license agreement. Then go to Preferences --> Downloads and install the "Command Line Tools." It's another 100+ MB to download, but think of this way: you'll be prepared with pretty much every Apple dev tool you'll ever need after today.

Ensure other web servers are off and disabled. This is a great activity while you wait for Xcode to install. On Mountain Lion, you have to use the command line to enable the default Apache server, so never-mind if you've never done that. Lion and prior, it's easily enabled in Sharing preferences ("Web"). Ensure these are off by running ps aux | grep apache or going to http://localhost in your browser.

Install Macports. Just run the .pkg file you downloaded. Make sure you've completed the previous steps first. By default, Macports and all ports will go into /opt/localThe readme file you see at install is super-helpful to know. (By the way, I had a hard time finding that exact readme file anywhere, so I'm hosting my own copy of it on my Raspberry Pi sitting on my windowsill, just for fun.) To be sure, run sudo port selfupdate when it's done installing to be up-to-date.



Run sudo port install nginx to install nginx. Twiddle thumbs... and at the end of the install, you'll be shown a command that causes it to run at system start: sudo port load nginx.

Configure nginx. Start by setting the default config files:
  • cd /opt/local/etc/nginx
  • sudo cp nginx.conf.default nginx.conf
  • sudo cp mime.types.default mime.types
  • sudo nginx -s reload
  • Load http://localhost in your browser to see that it's working. You're now done installing nginx.


Type: sudo port install mysql5-server and twiddle your thumbs again. When it's done, it gives you a command to have it run at start-up if you wish: sudo port load mysql5-server. For some reason, I had to restart my computer to get MySQL to start, but you can do that later. And the default, "root" user password is simply blank which is nice for dev environments.

PHP with FastCGI

Install PHP 5 and FastCGI. The command is long because you have to include all the extensions / helper libraries you want it compiled with. You can pick and choose, but be sure to include some essential ones like mysql, http, etc. I did it in two pieces like this:
  • sudo port install php5 +fastcgi fcgi
  • sudo port install php5-openssl php5-curl php5-gd php5-iconv php5-http php5-mcrypt php5-xdebug php5-mysql
At this point, your development tools and environment should be all there, and now we just need to configure them.

Configure nginx

Edit nginx.conf. In order to develop multiple sites on my Mac, I prefer to use a separate directory in the nginx folder which contains the config files for each domain I'm developing on. I call this "sites-enabled," located in /opt/local/etc/nginx. You can use the default conf file if you want, but you'll want to make sure a line like this appears somewhere before the final curly brace:

include sites-enabled/*;

This pulls in the configuration files from the sites-enabled folder.

Configure nginx site config files. For each domain/site you are developing, create a file inside /opt/local/etc/nginx/sites-enabled (make that directory if you want) called something like "mysite.dev.conf." A basic config file looks like this:

server {
listen 80;
server_name mysite.dev;
root /Users/matt/Sites/whatever/.../path/no-trailing-slash;

location / {
try_files $uri $uri/ /index.html;

try_files $uri $uri.html =404;

Now don't forget to update your host file: sudo nano /etc/hosts -- this will open your hosts file. Add an entry for each dev domain you use:    mysite.dev

Ctrl+O, Enter, Ctrl+X to save and exit. Make sure to reload nginx: sudo nginx -s reload. Now when you type http://mysite.dev in your browser, it will talk to your localhost nginx which should serve up that site based on the domain you are requesting.

If your dev site uses PHP...

...then some special stuff needs to be added to your site config file. To have nginx talk to PHP through FastCGI, my conf file (sites-enabled/mysite.dev.conf) looks kind of like this:

server {
  listen 80;
  server_name mysite.dev;
  root /Users/.../no-trailing-slash/directory;
  index index.php index.html;

  location / {
    #try_files $uri $uri/ /index.php;  # this line was causing the index.php file to be loaded twice...

  location ~ \.php$ {
    fastcgi_split_path_info ^(.+\.php)(.*)$;
    fastcgi_index index.php;
    include fastcgi.conf;
    if (-f $request_filename) {

  try_files $uri $uri.php $uri.html =404;

Again, don't forget to reload nginx when you make changes.

Last thing: we need to tell nginx where to find translation information for FastCGI, so it knows how to talk to it. Run this command: sudo cp /opt/local/etc/nginx/fastcgi.conf.default /opt/local/etc/nginx/fastcgi.conf

Don't forget to reload nginx!

Run php-cgi (FastCGI) when the Mac boots

Almost done! PHP's CGI needs a little help in order to run when the Mac boots up. This gave me a headache for hours after banging my head against the desk. It's actually simple using launchctl with a plist file all ready for you:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

I put this in a file: /Library/LaunchDaemons/org.macports.php-cgi.plist. Important: No spaces allowed between "-b" and "" I don't know why. But that's just how it is. You're welcome to customize anything else if you want.

To finish, then, run: sudo launchctl load org.macports.php-cgi.plist

Now the FastCGI wrapper for PHP will load when your system does, along with MySQL and nginx.

Restart your system and try loading your PHP dev website in your browser! (e.g. http://mysite.dev) -- everything should be working. If not, check your system console to see if FastCGI is failing to start and re-spawning every 10 seconds. That means you have a problem in your plist file.

If MySQL can't connect via PHP and you get a funny error on mysqli_connect kinds of functions, try switching the host from "localhost" to "" in your connection parameters in your PHP script. This might be related to the plist file we created or something in hosts, maybe even the default MySQL config. I'm not sure, but switching that fixed it for me.

Have fun on your shiny new dev environment!