+++
title = "minimal nginx configuration"
date = "2015-03-25T22:11:20+00:00"
author = "Gibheer"
draft = false
+++

As I was asked today, how I manage the nginx setup, I thought I write it down.

The configuration was inpsired by the [blog entry of Zach Orr](http://blog.zachorr.com/nginx-setup/)
(looks like the blog post is gone since 2014).
The setup consists of one main configuration and multiple domain specific
 configuration files which get sourced in the main config.
If a domain is using certificates, these are pulled in in their respective files.

I will leave out the performance stuff to make the config more readable. As the
location of the config files differs per platform, I will use $CONF_DIR as a
placeholder.

## main configuration

The main configuration `$CONF_DIR/nginx.conf` first sets some global stuff.

    # global settings
    user www www;
    pid /var/run/nginx.pid;

This will take care of dropping the privileges after the start to the *www* user
group.

Next is the http section, which sets the defaults for all server parts.

    http {
      include      mime.types;
      default_type application/octet-stream;
      charset      UTF-8;
    
      # activate some modules
      gzip on;
      # set some defaults for modules
      ssl_protocols TLSv1.2 TLSv1.1 TLSv1;
    
      include sites/*.conf;
    }

This part sets some default options for all server sections and helps to make the
separate configuration easier.
In this example the mime types are included (a large file with mime type definitions),
the default charset and mime type is set.

In this section we can also active modules like gzip ([see gzip on nginx](http://nginx.org/en/docs/http/ngx_http_gzip_module.html)) or set some options for modules like ssl ([see ssl on nginx](http://nginx.org/en/docs/http/ngx_http_ssl_module.html)).

The last option is to include more config files from the sites directory. This is
the directive which makes it possible to split up the configs.

## server section config

The server section config may look different for each purpose. Here are some
smaller config files just to show, what is possible.

### static website

For example the file *$CONF_DIR/sites/static.zero-knowledge.org.conf* looks like this:

    server {
      listen 80;
      server_name static.zero-knowledge.org;
    
      location / {
        root /var/srv/static.zero-knowledge.org/htdocs;
        index index.html;
      }
    }

In this case a domain is configured delivering static content from the directory
`/var/src/static.zero-knowledge.org/htdocs` on port 80 for the domain *static.zero-knowledge.org`.
If the root path is called in the browser, nginx will look for the *index.html* to show.

### reverse proxy site

For a reverse proxy setup, the config *$CONF_DIR/sites/zero-knowledge.org.conf* might look like this.

    server {
      listen 80;
      server_name zero-knowledge.org;
    
      location / {
        proxy_pass http://unix:/tmp/reverse.sock;
        include proxy_params;
      }
    }

In this case, nginx will also listen on port 80, but for the host zero-knowledge.org.
All incoming requests will be forwarded to the local unix socket */tmp/reverse.sock*.
You can also define IPs and ports here, but for an easy setup, unix sockets might be
easier.
The parameter `include proxy_params;` includes the config file proxy_params to
set some headers when forwarding the request, for example *Host* or *X-Forwarded-For*.
There should be a number of config files already included with the nginx package,
so best is to tkae a look in $CONF_DIR.

### uwsgi setup

As I got my graphite setup running some days ago, I can also provide a very bare
uwsgi config, which actually looks like the reverse proxy config.

    server {
      listen 80;
      server_name uwsgi.zero-knowledge.org;
    
      location / {
        uwsgi_pass uwsgi://unix:/tmp/uwsgi_graphite.sock;
        include uwsgi_params;
      }
    }


So instead of `proxy_pass` `uwsgi_pass` is used to tell nginx, that it has to use
the uwsgi format. Nginx will also include the uwsgi parameters, which is like the
proxy_params file a collection of headers to set.

## conclusion

So this is my pretty minimal configuration for nginx. It helped me automate the
configuration, as I just have to drop new config files in the directory and
reload the server.

I hope you liked it and have fun.
