Nginx is a lightweight HTTP proxy server. Easy on resources, and great at what it does.

Suppose you want to run Nginx to serve some static assets off your development machine, for demonstration purposes. But you also want to use Pow for your Rails and Rack work. If you have already tried to run both, you may have noticed that Pow takes port 80 using a ipfw rule, and no requests make it to Nginx. There’s a fairly easy solution.

What we are looking to have is:

• http://localhost/ to Nginx
• http://myapp.dev/ to Pow
• http://dev.example.com/ to development machine to Nginx
• http://myapp.dev.example.com/ to development machine to Pow

Those last two are only if you want external access to these services. They will require you to have your DNS setup properly to redirect dev.example.com and *.dev.example.com to your development machine (substituting your own domain of course).

From the Top

I’m going to assume you’re running Snow Leopard (10.6) or newer — Pow doesn’t run on older OS X versions. You should also have Nginx and Pow installed. I’m using Pow 0.3.2 and Nginx 1.0.14 on Mac OS 10.7.3.

Pow uses a resolver and an ipfw rule to redirect requests from *.dev to your Rack app. Take a look:

$ cat /etc/resolver/dev
# Lovingly generated by Pow
nameserver 127.0.0.1
port 20560

$ sudo ipfw list
00100 0 0 fwd 127.0.0.1,20559 tcp from any to me dst-port 80
65535 allow ip from any to any

That first rule, 00100, redirects any requests to port 80 to Pow at 127.0.0.1:20559. We can’t just remove the rule, as Pow will re-add it with a Launch Daemon on startup. And we can’t just remove the Launch Daemon, as pow needs it to run. (I tried). Instead, let’s let Pow take over a port we don’t care about.

$ echo "export POW_DST_PORT=19999" >> ~/.powconfig

And reinstall pow to pick up the new configuration:

$ curl get.pow.cx | sh

With that gone, if you try to load http://localhost/ you should get Nginx’s welcome page (if it is running)! One caveat: we can’t access our Rack servers from the http://*.dev/ domain anymore. This is where Nginx’s config comes into play.

Step into Nginx

Open Nginx’s config (/usr/local/etc/nginx/nginx.conf if you’re using Homebrew) in your favourite editor, and we will add some new server blocks.

Look for the existing server block, and adjust it’s server_name to include your external address.

server {
  listen       80;
  server_name  localhost dev.example.com;

  #charset koi8-r;
  ...

If you save it and reload Nginx now (sudo nginx -s reload), you should see the Nginx welcome page at your domain. Nice!

Back to the conf file, add two new server blocks above the existing server directive.

server {
  listen 80;
  server_name *.dev;
  location / {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
    proxy_pass http://localhost:20559;
  }
}

server {
  listen 80;
  server_name myapp.dev.example.com;
  location / {
    proxy_set_header Host "myapp.dev"; # Host for Pow
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
    proxy_pass http://localhost:20559;
  }
}

server {
    listen       80;
    server_name  localhost dev.example.com;
    ...

Save and reload Nginx. localhost now goes to Nginx. myapp.dev now goes to Pow. And externally, dev.example.com goes to Nginx, and myapp.dev.example.com goes to Pow.

Now that you’ve skimmed the basics of mounting your Rack app (e.g. API) in your Rails app without touching your rackup file, you’re all set for the next step: throttling! testing!

Let’s go over a quick example with Cucumber. Don’t worry, I’ll keep it simple.

Go ahead and install cucumber-rails and database_cleaner into your Gemfile, if you aren’t using them already.

Note: You can use anything for your Rack app here, Sinatra, Grape, etc. as long as it returns a 200 status code for its base path. If you want to follow along, you can use this dumb rack app. There’s a link to a Github repo at the end of the post.

Here it is, a simple Rack app (a proc!) mounted in your Rails app at “/api”. It always responds “OK”, with status code 200.

# routes.rb
RailsApp::Application.routes.draw do
  mount proc { |env|
    [200, {}, ["OK"]]
  } => "/api"

  # your other Rails routes
end

At this point, you can start up the Rails server and hit your “API” at http://localhost:3000/api. You should see the word “OK” — that means it’s running. You just created a Rack app in your Rails app. Wasn’t that easy?

Now for the cuking. A simple feature to start off:

# features/my_dumb_api.feature
Feature: My Dumb API
  In order to retrieve an API response
  As a web API developer
  I want an API to respond to my requests

  Scenario: API is available
    When I send a GET request for "http://example.com/api/"
    Then the response code should be "200"

And some step definitions:

When /^I send a GET request for "([^"]*)"$/ do |path|
    get path
end

Then /^the response code should be "([^"]*)"$/ do |code|
    last_response.status.should == code.to_i
end

Now give cucumber a run.

$ cucumber features/my_dumb_api.feature

Using the default profile...
# features/my_dumb_api.feature
Feature: My Dumb API
  In order to retrieve an API response
  As a web API developer
  I want an API to respond to my requests

  Scenario: API is available                                # features/my_dumb_api.feature:7
    When I send a GET request for "http://example.com/api/" # features/step_definitions/api_steps.rb:1
    Then the response code should be "200"                  # features/step_definitions/api_steps.rb:5

1 scenario (1 passed)
2 steps (2 passed)
0m0.154s

Excellent! It picked it up right away. Now we can start thinking about throttling. Jump over to your Gemfile and add rack-throttle:

gem 'rack-throttle', :require => 'rack/throttle'

Update your bundle. Now, let’s start with the Cucumber feature this time.

Feature: My Dumb API
  In order to retrieve an API response
  As a web API developer
  I want an API to respond to my requests

  Scenario: API is available
    When I send a GET request for "http://example.com/api/"
    Then the response code should be "200"

  Scenario: Exceeding API Query Rate
    When I send more than one GET request in a second to "http://example.com/api"
    Then the response code should be "403"

And it’s corresponding steps file:

When /^I send a GET request for "([^"]*)"$/ do |path|
    get path
end

When /^I send more than one GET request in a second to "([^"]*)"$/ do |path|
    # We'll assume this happens in < 1 second
    get path
    get path
end

Then /^the response code should be "([^"]*)"$/ do |code|
    last_response.status.should == code.to_i
end

If we run this through Cucumber, it fails, because we haven’t done throttling yet. Jump to your routes file, and switch it to:

RailsApp::Application.routes.draw do
  mount Rack::Builder.new {
    use Rack::Throttle::Interval, :min => 1.0
    run proc { |env|
      [200, {}, ["OK"]]
    }
  } => "/api"
end

There, we just built a Rack app with middleware (the Rack::Throttle line), which defers to our Rack app (the proc) when the middleware passes the request onwards. Now when you run Cucumber, everything passes! You may think you’re ready to Cuke out the rest of your API, but you’re about to hit a roadblock — throttling hits all your Cucumber features. I have considered two ways to deal with this:

1. Stub out Rack::Throttle and tell it which features you specifically want to throttle using Cucumber tags.
2. Use a separate Rack app for Cucumber testing, and turn throttling on for certain features with Cucumber tags.

I chose the second option. First, I added the @no-throttle tag to the scenarios where throttling was not relevant:

Feature: My Dumb API
  In order to retrieve an API response
  As a web API developer
  I want an API to respond to my requests

  @no-throttle
  Scenario: API is available
    When I send a GET request for "http://example.com/api/"
    Then the response code should be "200"

  Scenario: Exceeding API Query Rate
    When I send more than one GET request in a second to "http://example.com/api"
    Then the response code should be "403"

And then a before filter in the steps file:

Before "@no-throttle" do
  @app = Rack::Builder.new {
    map "/api" do
      run proc { |env|
        [200, {}, ["OK"]]
      }
    end
  } 
end

When /^I send a GET request for "([^"]*)"$/ do |path|
    get path
end

When /^I send more than one GET request in a second to "([^"]*)"$/ do |path|
    # We'll assume this happens in < 1 second
    get path
    get path
end 
      
Then /^the response code should be "([^"]*)"$/ do |code|
    last_response.status.should == code.to_i
end

Now when you run your Cucumber features, the unthrottled scenarios will use a separate rack app, mounted without throttling. The downside to this method is that your have to keep the Rack app in api_steps.rb up to date with the one in routes.rb. A small price to pay, but less work than stubbing out Rack::Throttle.

You can browse the source code for this example Rails app on Github.

I also rebuilt a binary version of the action, which is incredibly simple to install: just double-click. It is also compatible with both PPC and Intel Macs, I had success running it with 10.4 on a G4 Mac Mini. You can download from Github or download from my site.

Additionally, it is now open source so if you see any changes (the code has been changed in over five years), fork it on Github and let me know!

Special Thanks:
StackOverflow — Create Universal Automator Action
Google Fodder — 64-bit Automator and Snow Leopard