A neat and simple nginx setup with Homebrew on OSX

I’m a huge fan of nginx. It’s fast, efficient, secure and easy to set up. I run it on various servers, so it makes sense to have it running in my local development environment too.

Thanks to the wonderful Homebrew, that’s fairly straightforward to accomplish on OS X. Homebrew is a package manager, so instead of you having to download and run a .dmg file for all the software you want to install, you can just type a command into your terminal and it’ll do it all for you.

Make it neat with a local testing domain

Before installing the server, we can take a step that will avoid us having to browse our site on an ugly domain like http://localhost/.

Let’s assume you’re aiming to create a coffee-related website. Perhaps you’ve already registered the coffee.com domain. For neatness then, we’ll set up the local version of our site to run on a domain called coffee.l - that’s ‘l’ as in ‘local’. You could use anything you want instead - I’ve just chosen that because it’s quick to type, and doesn’t interfere with any real TLDs.

Getting this fake domain to work is just a matter of editing the /etc/hosts file on the Mac. Add a couple of lines at the end to make sure that any requests for coffee.l or www.coffee.l get routed to your local machine, so your local nginx server can process them:

127.0.0.1    coffee.l
127.0.0.1    www.coffee.l

Get Homebrew running

As the Homebrew instructions say, you can install by pasting a one-liner command at a terminal prompt:

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

From there, Homebrew will show you instructions for how to continue. It’ll ask you to [install XCode]((https://developer.apple.com/downloads/index.action) if you don’t already have it, which provides some OS X developer tools necessary for Homebrew to run. If you’re short on bandwidth, time, or inclination to try out the XCode IDE, consider using the “Command Line Tools for Xcode” package instead, with minimal extra software.

Install nginx

All being well, you now have a working version of Homebrew installed, and can install nginx by entering the following on the command line:

brew install nginx

It’ll take a few minutes while it downloads the packages it needs, then compiles nginx on your computer. Once that’s done, it’s time to browse to the nginx config directory, which lies within Homebrew’s /usr/local area:

cd /usr/local/etc/nginx

Let’s open up nginx.conf, which is the main configuration file for nginx, and make a couple of changes. Within the http section, it’s worth adding a line to include the contents of a sites-enabled directory. This gives a place where you can save a config file for each of the websites you want to run.

http {
	include /usr/local/etc/nginx/sites-enabled/*;
	...

Just below that, there should be a server section, where I recommend declaring that you want to run your server on port 80. That avoids having to append an ugly, non-standard port number like :8080 on the end of all your local URLs.

listen 80;

With that done, let’s save nginx.conf, and move on to creating a configuration file for the coffee website. Create that sites-enabled directory, and put a configuration file in there for your website:

mkdir sites-enabled
cd sites-enabled
vim coffee

And now paste in a minimal configuration file:

# Rewrite www.coffee.l to coffee.l
server {
	listen 80;
	server_name www.coffee.l;
	return 301 $scheme://coffee.l$request_uri;
}

server {
	listen 80;
	server_name coffee.l;
	access_log /usr/local/var/log/nginx/coffee.l.access.log;
	error_log /usr/local/var/log/nginx/coffee.l.error.log;

	root /Users/graeme/Sites/coffee;
}

You’ll want to edit the root declaration there, making sure to provide a valid path to your website directory. When you’re happy, save and close the file.

Start it up

Once that’s done, let’s try firing up nginx on the command line. Homebrew should have installed a handy startup script in /usr/local/sbin/nginx, so we can type the following to start the server:

sudo nginx

Then go to http://coffee.l in your browser and see what happens! All being well there’s a working website there now. If not, it’s just a matter of tweaking the configuration file, saving the changes, then reloading the nginx configuration to ensure the changes are working:

sudo nginx -s reload

There are also a couple of extra options provided by that script, which may come in useful:

sudo nginx -s restart
sudo nginx -s stop

Any issues, let me know on on Twitter!