nginx is a free and open source HTTP server and reverse proxy, with a strong focus on performance, high concurrency and low memory usage.
Its popularity has been rising for years, and in May 2013 it became the second most common web server within the top million busiest websites.

nginx has become a staple component in several web application stacks, where it acts as a reverse proxy and load balancer in front of clusters of application servers.

Ruby on Rails is no exception. Whether you prefer to forward traffic to independent application processes (e.g. Unicorns, Pumas or Thins), or to rely on Phusion Passenger, nginx is now an industry standard.

Getting started with nginx is easy and lots of resources are available online.
Since there is no lack of tutorials, I’ve taken another route and prepared an example configuration file. It contains extractions from real-world configurations, and will set up nginx to forward traffic to a number of Rails server processes.

Here it is, complete with self documenting comments.

Understand the Configuration Structure

Nginx configuration files have a simple structure, based on levels and inheritance.
Each configuration directive can be used in specific contexts, often more than one (see the docs). Most directives will be inherited from the parent levels unless explicitly overridden.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# root level

events {
}

http {
  # general server configuration

  upstream name {
    # a destination for reverse proxying
    # and load balancing
  }

  server {
    # specific server configuration

    location pattern_or_name {
      # this matches the request URI
    }
  }
}

At the root level we have process-related directives, for example to set the pid file, the user and group the workers will run as, and the error log.

nginx is event-based, and the events block contains directives to control how such events are handled.

The http block is where the configuration starts to focus on web traffic. Most directives allowed at the http level can be redeclared in its child blocks.

Upstream blocks are destinations to which nginx can forward incoming web traffic (when it’s configured to act as a reverse proxy). Typically, an upstream block represents a back end application.

When nginx receives a request from a client, the request is passed to the server block that matches the request’s host name. In fact, server blocks contain information that identifies specific websites, such as the domain names, the listened port, the root directory on the file system, https configuration, etc. They are what in Apache would be called a virtual host.

Used within server blocks, location blocks contain specific configurations to be used in precise contexts.
Location blocks can either be identified by a pattern (string or regex) or a name. Patterns are matched against the request URI (the path component), whereas named locations are only used as target of internal request redirections.

Links!

The official docs look bare and minimal, but they contain a full index of all configuration directives and several articles on specific use cases. The nginx wiki is another great resource with articles and tutorials.

The book The Architecture of Open Source Applications features a chapter on nginx, by Andrew Alexeev, with an explanation of nginx’s non-blocking event-based model.

Also, I recommend a series of articles by Martin Fjordvald:

• nginx configuration primer
• from Apache to nginx
• understanding the nginx configuration inheritance model