nginx_server Cookbook

Table of Contents

1. Overview
2. Requirements
3. Attributes
4. Usage
   • nginx_server_vhost
   • nginx_server_upstream
5. Contributing
6. License & Authors

Overview

This module manages the installation and configuration of NGINX.

Requirements

Requires Chef 12.5 or later as this cookbook makes use of Custom Resources.

Attributes

yumserver::default

Usage

You always need to include the main recipe:

include_recipe 'nginx_server::default'

This recipe:

• Sets up the NGINX repo (stable repo by default).
• Installs the nginx package.
• Writes the main config to /etc/nginx/nginx.conf.
• zaps any files in /etc/nginx/conf.d/ not managed by Chef.
• Enables & starts the nginx service.

nginx_server_vhost

This resource defines a standard NGINX vhost.

Each nginx_server_vhost has the following attributes:

To setup a basic vhost for example:

nginx_server_vhost 'example.org' do
  server_name [
    'example.org',
    'www.example.org'
  ]
  root '/var/www/example.org'
  action :create
end

listen

The listen statement is an array of hashes that consists of:

• ipaddress
• port
• options

All parts of each hash are options and have sane defaults:

• ipaddress = 0.0.0.0
• port = 80
• options = N/A

For example to listen on the loopback address with SSL:

listen [
  {
    'ipaddress': '127.0.0.1',
    'port': 443,
    'options': 'ssl'
  }
]

this produces a line like this:

listen 127.0.0.1:443 ssl;

For more examples see the cookbook's integration test cookbook.

config

The config is a hash of additional config for the vhost not provided by the other properties.

This supports nested config such as location statements as well, for example:

config ({
    'error_page' => '404 /404.html',
    'location ~ \.php$' => {
      'try_files' => '$uri =404',
      'fastcgi_pass' => 'unix:/var/run/php5-fpm.sock',
      'fastcgi_index' => 'index.php',
      'fastcgi_param' => 'SCRIPT_FILENAME $document_root$fastcgi_script_name',
      'include' => 'fastcgi_params'
    }
  })

this is rendered as:

error_page 404 /404.html;
location ~ \.php$ {
  try_files $uri =404;
  fastcgi_pass unix:/var/run/php5-fpm.sock;
  fastcgi_index index.php;
  fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
  include fastcgi_params;
}

For more examples see the cookbook's integration test cookbook.

nginx_server_upstream

The nginx_server_upstream defines an NGINX upstream to be used in tandem with a nginx_server_vhost that uses proxy_pass or similar to proxy connections to backend servers.

Each nginx_server_upstream has the following attributes:

To proxy through to a group of application servers for example:

nginx_server_upstream 'appservers' do
  ip_hash true
  least_conn true
  servers [
    ['192.168.0.100:8080', 'max_fails=3', 'fail_timeout=30s'],
    ['192.168.0.101:8080', 'max_fails=3', 'fail_timeout=30s'],
    ['192.168.0.102:8080', 'max_fails=3', 'fail_timeout=30s']
  ]
  action :create
end

will render as:

upstream appservers {
  ip_hash;
  least_conn;

  server 192.168.0.100:8080 max_fails=3 fail_timeout=30s;
  server 192.168.0.101:8080 max_fails=3 fail_timeout=30s;
  server 192.168.0.102:8080 max_fails=3 fail_timeout=30s;
}

Contributing

If you would like to contribute to this cookbook please follow these steps;

1. Fork the repository on Github.
2. Create a named feature branch (like add_component_x).
3. Write your change.
4. Write tests for your change (if applicable).
5. Write documentation for your change (if applicable).
6. Run the tests, ensuring they all pass.
7. Submit a Pull Request using GitHub.

License and Authors

License: [BSD 2-clause](https://tldrlegal.com/license/bsd-2-clause-license-\(freebsd\)

Authors:

• Danny Roberts
• All Contributors