Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status


nginx (112) Versions 2.5.0

Installs and configures nginx

cookbook 'nginx', '= 2.5.0', :supermarket
cookbook 'nginx', '= 2.5.0'
knife supermarket install nginx
knife supermarket download nginx
Quality -%

nginx Cookbook

Build Status

Installs nginx from package OR source code and sets up configuration handling similar to Debian's Apache2 scripts.



The following cookbooks are direct dependencies because they're used for common "default" functionality.

  • build-essential (for nginx::source)
  • ohai (for nginx::ohai_plugin)

The following cookbook is not a strict dependency because its use can be controlled by an attribute, so it may not be a common "default."

  • runit (for nginx::source)
  • On RHEL family distros, the "yum" cookbook is required for recipe[yum::epel].
  • On Ubuntu, when using's stable package, recipe[apt::default] is required.


The following platforms are supported and tested under test kitchen:

  • Ubuntu 10.04, Ubuntu 12.04
  • CentOS 5.8, 6.3

Other Debian and RHEL family distributions are assumed to work.


Node attributes for this cookbook are logically separated into different files. Some attributes are set only via a specific recipe.


Generally used attributes. Some have platform specific values. See attributes/default.rb. "The Config" refers to "nginx.conf" the main config file.

  • node['nginx']['dir'] - Location for Nginx configuration.
  • node['nginx']['log_dir'] - Location for Nginx logs.
  • node['nginx']['user'] - User that Nginx will run as.
  • node['nginx']['group] - Group for Nginx.
  • node['nginx']['binary'] - Path to the Nginx binary.
  • node['nginx']['init_style'] - How to run Nginx as a service when using nginx::source. Values can be "runit", "upstart", "init" or "bluepill". When using runit or bluepill, those recipes will be included as well and are dependencies of this cookbook. Recipes are not included for upstart, it is assumed that upstart is built into the platform you are using (ubuntu or el6). This attribute is not used in the nginx recipe because the package manager's init script style for the platform is assumed. Upstart is never set as a default as this represents a change in behavior, if you are running ubuntu or el6 and want to use upstart, please set this attribute in a role or similar.
  • node['nginx']['upstart']['foreground'] - Set this to true if you want upstart to run nginx in the foreground, set to false if you want upstart to detach and track the process via pid.
  • node['nginx']['upstart']['runlevels'] - String of runlevels in the format '2345' which determines which runlevels nginx will start at when entering and stop at when leaving.
  • node['nginx']['upstart']['respawn_limit'] - Respawn limit in upstart stanza format, count followed by space followed by interval in seconds.
  • node['nginx']['pid'] - Location of the PID file.
  • node['nginx']['keepalive'] - Whether to use keepalive_timeout, any value besides "on" will leave that option out of the config.
  • node['nginx']['keepalive_timeout'] - used for config value of keepalive_timeout.
  • node['nginx']['worker_processes'] - used for config value of worker_processes.
  • node['nginx']['worker_connections'] - used for config value of events { worker_connections }
  • node['nginx']['worker_rlimit_nofile'] - used for config value of worker_rlimit_nofile. Can replace any "ulimit -n" command. The value depend on your usage (cache or not) but must always be superior than worker_connections.
  • node['nginx']['multi_accept'] - used for config value of events { multi_accept }. Try to accept() as many connections as possible. Disable by default.
  • node['nginx']['event'] - used for config value of events { use }. Set the event-model. By default nginx looks for the most suitable method for your OS.
  • node['nginx']['server_tokens'] - used for config value of server_tokens.
  • node['nginx']['server_names_hash_bucket_size'] - used for config value of server_names_hash_bucket_size.
  • node['nginx']['disable_access_log'] - set to true to disable the general access log, may be useful on high traffic sites.
  • node['nginx']['access_log_options'] - Set to a string of additional options to be appended to the access log directive
  • node['nginx']['error_log_options'] - Set to a string of additional options to be appended to the error log directive
  • node['nginx']['default_site_enabled'] - enable the default site
  • node['nginx']['sendfile'] - Whether to use sendfile. Defaults to "on".
  • node['nginx']['install_method'] - Whether nginx is installed from packages or from source.
  • node['nginx']['types_hash_max_size'] - Used for the types_hash_max_size configuration directive.
  • node['nginx']['types_hash_bucket_size'] - Used for the types_hash_bucket_size configuration directive.
  • node['nginx']['proxy_read_timeout'] - defines a timeout (between two successive read operations) for reading a response from the proxied server.
  • node['nginx']['client_body_buffer_size'] - used for config value of client_body_buffer_size.
  • node['nginx']['client_max_body_size'] - specifies the maximum accepted body size of a client request, as indicated by the request header Content-Length.
  • node['nginx']['repo_source'] - when installed from a package this attribute affects which yum repositories, if any, will be added before installing the nginx package. The default value of 'epel' will use the yum::epel recipe, 'nginx' will use the nginx::repo recipe, and setting no value will not add any additional repositories.

Rate Limiting

  • node['nginx']['enable_rate_limiting'] - set to true to enable rate limiting (limit_req_zone in nginx.conf)
  • node['nginx']['rate_limiting_zone_name'] - sets the zone in limit_req_zone.
  • node['nginx']['rate_limiting_backoff'] - sets the backoff time for limit_req_zone.
  • node['nginx']['rate_limit'] - set the rate limit amount for limit_req_zone.

gzip module

  • node['nginx']['gzip'] - Whether to use gzip, can be "on" or "off"
  • node['nginx']['gzip_http_version'] - used for config value of gzip_http_version.
  • node['nginx']['gzip_comp_level'] - used for config value of gzip_comp_level.
  • node['nginx']['gzip_proxied'] - used for config value of gzip_proxied.
  • node['nginx']['gzip_vary'] - used for config value of gzip_vary.
  • node['nginx']['gzip_buffers'] - used for config value of gzip_buffers.
  • node['nginx']['gzip_types'] - used for config value of gzip_types - must be an Array.
  • node['nginx']['gzip_min_length'] - used for config value of gzip_min_length.
  • node['nginx']['gzip_disable'] - used for config value of gzip_disable.

Attributes set in recipes


  • node['nginx']['daemon_disable'] - Whether the daemon should be disabled which can be true or false; disable the daemon (run in the foreground) when using a service supervisor such as runit or bluepill for "init_style". This is automatically set in the nginx::source recipe when the init style is not bluepill or runit.


  • node['nginx']['remote_ip_var'] - The remote ip variable name to use.
  • node['nginx']['authorized_ips'] - IPs authorized by the module



  • node['nginx']['realip']['header'] - Header to use for the RealIp Module; only accepts "X-Forwarded-For" or "X-Real-IP"
  • node['nginx']['realip']['addresses'] - Addresses to use for the http_realip configuration.
  • node['nginx']['realip']['real_ip_recursive'] - If recursive search is enabled, the original client address that matches one of the trusted addresses is replaced by the last non-trusted address sent in the request header field. Can be on "on" or "off" (default).


These attributes are used in the nginx::source recipe. Some of them
are dynamically modified during the run. See attributes/source.rb
for default values.

  • node['nginx']['source']['url'] - (versioned) URL for the Nginx source code. By default this will use the version specified as `node['nginx']['version'].
  • node['nginx']['source']['prefix'] - (versioned) prefix for installing nginx from source
  • node['nginx']['source']['conf_path'] - location of the main config file, in node['nginx']['dir'] by default.
  • node['nginx']['source']['modules'] - Array of modules that should be compiled into Nginx by including their recipes in nginx::source.
  • node['nginx']['source']['default_configure_flags'] - The default flags passed to the configure script when building Nginx.
  • node['nginx']['configure_flags'] - Preserved for compatibility and dynamically generated from the node['nginx']['source']['default_configure_flags'] in the nginx::source recipe.
  • node['nginx']['source']['use_existing_user'] - set to true if you do not want nginx::source recipe to create system user with name node['nginx']['user'].


These attributes are used in the nginx::http_geoip_module recipe.
Please note that the country_dat_checksum and city_dat_checksum
are based on downloads from a datacenter in Fremont, CA, USA. You
really should override these with checksums for the geo tarballs from
your node location.

Note The upstream,, may block access for repeated
downloads of the data files. It is recommended that you download and
host the data files, and change the URLs in the attributes.

  • node['nginx']['geoip']['path'] - Location where to install the geoip libraries.
  • node['nginx']['geoip']['enable_city'] - Whether to enable City data
  • node['nginx']['geoip']['country_dat_url'] - Country data tarball URL
  • node['nginx']['geoip']['country_dat_checksum'] - Country data tarball checksum
  • node['nginx']['geoip']['city_dat_url'] - City data tarball URL
  • node['nginx']['geoip']['city_dat_checksum'] - City data tarball checksum
  • node['nginx']['geoip']['lib_version'] - Version of the GeoIP library to install
  • node['nginx']['geoip']['lib_url'] - (Versioned) Tarball URL of the GeoIP library
  • node['nginx']['geoip']['lib_checksum'] - Checksum of the GeoIP library tarball


These attributes are used in the nginx::upload_progress_module

  • node['nginx']['upload_progress']['url'] - URL for the tarball.
  • node['nginx']['upload_progress']['checksum'] - Checksum of the tarball.
  • node['nginx']['upload_progress']['javascript_output'] - Output in javascript. Default is true for backwards compatibility.
  • node['nginx']['upload_progress']['zone_name'] - Zone name which will be used to store the per-connection tracking information. Default is proxied.
  • node['nginx']['upload_progress']['zone_size'] - Zone size in bytes. Default is 1m (1 megabyte).


These attributes are used in the nginx::passenger recipe.

  • node['nginx']['passenger']['version'] - passenger gem version
  • node['nginx']['passenger']['root'] - passenger gem root path
  • node['nginx']['passenger']['max_pool_size'] - maximum passenger pool size (default=10)
  • node['nginx']['passenger']['ruby'] - Ruby path for Passenger to use (default=$(which ruby))
  • node['nginx']['passenger']['spawn_method'] - passenger spawn method to use (default=smart-lv2)
  • node['nginx']['passenger']['buffer_response'] - turns on or off response buffering (default=on)
  • node['nginx']['passenger']['max_pool_size'] - passenger maximum pool size (default=6)
  • node['nginx']['passenger']['min_instances'] - minimum instances (default=1)
  • node['nginx']['passenger']['max_instances_per_app'] - maximum instances per app (default=0)
  • node['nginx']['passenger']['pool_idle_time'] - passenger pool idle time (default=300)
  • node['nginx']['passenger']['max_requests'] - maximum requests (default=0)


These attributes are used in the nginx::http_echo_module recipe.

  • node['nginx']['echo']['version'] - The version of http_echo you want (default: 0.40)
  • node['nginx']['echo']['url'] - URL for the tarball.
  • node['nginx']['echo']['checksum'] - Checksum of the tarball.


These attributes are used in the nginx::http_stub_status_module recipe.

  • node['nginx']['status']['port'] - The port on which nginx will serve the status info (default: 8090)


These attributes are used in the nginx::openssl_source recipe.

  • node['nginx']['openssl_source']['version'] - The version of OpenSSL you want to download and use (default: 1.0.1e)
  • node['nginx']['openssl_source']['url'] - The url for the OpenSSL source


This cookbook provides three main recipes for installing Nginx.

  • default.rb - Use this recipe if you have a native package for Nginx.
  • repo.rb - The developer of Nginx also maintain stable packages for several platforms.
  • source.rb - Use this recipe if you do not have a native package for Nginx, or if you want to install a newer version than is available, or if you have custom module compilation needs.

Several recipes are related to the source recipe specifically. See
that recipe's section below for a description.


The default recipe will install Nginx as a native package for the
system through the package manager and sets up the configuration
according to the Debian site enable/disable style with sites-enabled
using the nxensite and nxdissite scripts. The nginx service will
be managed with the normal init scripts that are presumably included
in the native package.

Includes the ohai_plugin recipe so the plugin is available.


This recipe provides an Ohai plugin as a template. It is included by
both the default and source recipes.


Sets up configuration for the authorized_ip nginx module.


This recipe is responsible for building Nginx from source. It ensures
that the required packages to build Nginx are installed (pcre,
openssl, compile tools). The source will be downloaded from the
node['nginx']['source']['url']. The node['nginx']['user'] will be
created as a system user. If you want to use existing user set
node['nginx']['source']['use_existing_user'] to true. The appropriate
configuration and log directories and config files will be created
as well according to the attributes node['nginx']['dir'] and

The recipe attempts to detect whether additional modules should be
added to the configure command through recipe inclusion (see below),
and whether the version or configuration flags have changed and should
trigger a recompile.

The nginx service will be set up according to
node['nginx']['init_style']. Available options are:

  • runit: uses runit cookbook and sets up runit_service.
  • bluepill: uses bluepill cookbook and sets up bluepill_service.
  • anything else (e.g., "init") will use the nginx init script template.

RHEL/CentOS This recipe should work on RHEL/CentOS with "init" as
the init style.

The following recipes are used to build module support into Nginx. To
use a module in the nginx::source recipe, add its recipe name to the
attribute node['nginx']['source']['modules'].

  • ipv6.rb - enables IPv6 support
  • http_echo_module.rb - downloads the http_echo_module module and enables it as a module when compiling nginx.
  • http_geoip_module.rb - installs the GeoIP libraries and data files and enables the module for compilation.
  • http_gzip_static_module.rb - enables the module for compilation.
  • http_perl_module.rb - enables embedded Perl for compilation.
  • http_realip_module.rb - enables the module for compilation and creates the configuration.
  • http_ssl_module.rb - enables SSL for compilation.
  • http_stub_status_module.rb - provides nginx_status configuration and enables the module for compilation.
  • naxsi_module - enables the naxsi module for the web application firewall for nginx.
  • passenger - builds the passenger gem and configuration for "mod_passenger".
  • upload_progress_module.rb - builds the upload_progress module and enables it as a module when compiling nginx.
  • openssl_source.rb - downloads and uses custom OpenSSL source when compiling nginx


The cookbook provides a definition. At some point in the future
these definitions may be refactored into lightweight resources and
providers as suggested by
foodcritic rule FC015.


Manage a template resource for a Server Block (VirtualHost) site, and enable it with
nxensite script. This is commonly done for managing web applications
such as Ruby on Rails, PHP or Django, and the default behavior
reflects that. However it is flexible.

It will then configure the template (see Parameters and
Examples below), and enable or disable the site per the enable


Current parameters used by the definition:

  • name - The name of the site. The template will be written to #{node['nginx']['dir']}/sites-available/#{params['name']}
  • cookbook - Optional. Cookbook where the source template is. If this is not defined, Chef will use the named template in the cookbook where the definition is used.
  • template - Default default-site.erb, source template file.
  • enable - Default true. Uses nxensite or nxdissite script as appropriate.

Additional parameters can be defined when the definition is called in
a recipe, see Examples.


All parameters are passed into the template. You can use whatever you
like. The nginx cookbook comes with a default-site.erb template as
an example. The following parameters are used in the template:

  • server_name - Default node['hostname'], Sets server_name directive.
  • port - Default 80, Used to set the port for the listen directive.
  • default_server - Used in listen directive. Will set default_server option on nginx >= 0.8.21 and default on nginx < 0.8.21.
  • docroot - Default node['nginx']['default_root'], root directive for default location / block.
  • directory_index - Allow overriding the default index setting, optional

To use the default nginx_site, for example:

nginx_site 'test-site' do
  cookbook 'nginx'
  server_name ''
  default_server true
  docroot '/var/www/test-site'
  directory_index 'index.html index.htm'

The parameters specified will be used as:

  • @params[:server_name]
  • @params[:default_server]
  • @params[:docroot]
  • @params[:directory_index]

In the template. When you write your own, the @ is significant.

For more information about Definitions and parameters, see the
Chef Wiki

Adding New Modules

To add a new module to be compiled into nginx in the source recipe,
the node's run state is manipulated in a recipe, and the module as a
recipe should be added to node['nginx']['source']['modules']. For

node.run_state['nginx_configure_flags'] =
  node.run_state['nginx_configure_flags'] | ['--with-http_stub_status_module']

The recipe will be included by recipe[nginx::source] automatically,
adding the configure flags. Add any other configuration templates or
other resources as required. See the recipes described above for

Ohai Plugin

The ohai_plugin recipe includes an Ohai plugin. It will be
automatically installed and activated, providing the following
attributes via ohai, no matter how nginx is installed (source or

  • node['nginx']['version'] - version of nginx
  • node['nginx']['configure_arguments'] - options passed to ./configure when nginx was built
  • node['nginx']['prefix'] - installation prefix
  • node['nginx']['conf_path'] - configuration file path

In the source recipe, it is used to determine whether control
attributes for building nginx have changed.


Include the recipe on your node or role that fits how you wish to
install Nginx on your system per the recipes section above. Modify the
attributes as required in your role to change how various
configuration is applied per the attributes section above. In general,
override attributes in the role should be used when changing

There's some redundancy in that the config handling hasn't been
separated from the installation method (yet), so use only one of the
recipes, default or source.

License & Authors

Copyright 2008-2013, Opscode, Inc

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

Dependent cookbooks

apt ~> 2.2
bluepill ~> 2.3
build-essential ~> 2.0
ohai ~> 1.1
runit ~> 1.2
yum-epel ~> 0.3

Contingent cookbooks

aegir Applicable Versions
aegir3 Applicable Versions
alfresco-webserver Applicable Versions
app Applicable Versions
application_nginx Applicable Versions
application_static Applicable Versions
archiva Applicable Versions
base_image Applicable Versions
berkshelf Applicable Versions
berkshelf-api-server Applicable Versions
berkshelf-api-server-ya Applicable Versions
boxbilling Applicable Versions
cabot Applicable Versions
cassandra-opscenter Applicable Versions
certbot Applicable Versions
chef-jellyfish Applicable Versions
chef-server Applicable Versions
cloudfoundry-cloud_controller Applicable Versions
cloudfoundry-nginx Applicable Versions
config-driven-helper Applicable Versions
cyclesafe_chef Applicable Versions
devpi Applicable Versions
docker-registry2 Applicable Versions
dokku Applicable Versions
drone Applicable Versions
elasticsearch_cluster Applicable Versions
elkstack Applicable Versions
errbit Applicable Versions
etherpad-lite Applicable Versions
eulipion-slate Applicable Versions
fanfare Applicable Versions
frog Applicable Versions
gem_server Applicable Versions
geminabox Applicable Versions
gemirro Applicable Versions
ghost Applicable Versions
github_connector Applicable Versions
gitlab Applicable Versions
gitlab-server Applicable Versions
gitpaste Applicable Versions
grafana Applicable Versions
huginn Applicable Versions
ice Applicable Versions
insight Applicable Versions
iptables_web Applicable Versions
ipynb Applicable Versions
ish Applicable Versions
jenkins Applicable Versions
jenkins-server Applicable Versions
kibana5-gm Applicable Versions
kibana_lwrp Applicable Versions
kloudspeaker Applicable Versions
kong Applicable Versions
lemur Applicable Versions
looker Applicable Versions
lxc-web-panel Applicable Versions
magento Applicable Versions
maven-deploy Applicable Versions
mediacore Applicable Versions
met-jenkins Applicable Versions
mirage Applicable Versions
modcloth-hubot Applicable Versions
moodle Applicable Versions
mozilla-firefox-sync Applicable Versions
mozilla-sync Applicable Versions
mruby Applicable Versions
munin Applicable Versions
myusa Applicable Versions
nagios Applicable Versions
nexus Applicable Versions
nginx-hardening Applicable Versions
nginx-proxy Applicable Versions
nginx_conf Applicable Versions
nginx_fallback_to_apache Applicable Versions
nginx_simplecgi Applicable Versions
nginxsite Applicable Versions
ngx Applicable Versions
nodejs-deploy Applicable Versions
nodestack Applicable Versions
noosfero Applicable Versions
oc-id Applicable Versions
ohmage Applicable Versions
omakase Applicable Versions
opennms Applicable Versions
opsworks_ruby Applicable Versions
owncloud Applicable Versions
paramount Applicable Versions
passenger_enterprise Applicable Versions
phabricator Applicable Versions
phpstack Applicable Versions
pita Applicable Versions
piwik Applicable Versions
postfixadmin Applicable Versions
prose Applicable Versions
pythonstack Applicable Versions
rackbox Applicable Versions
rackspace_nginx_php Applicable Versions
rails_application Applicable Versions
railsbox Applicable Versions
redirect Applicable Versions
redmine2 Applicable Versions
reprepro Applicable Versions
request_tracker Applicable Versions
roundcube Applicable Versions
rubycas Applicable Versions
rundeck-alt Applicable Versions
sensu_admin Applicable Versions
sinatra Applicable Versions
snipe-it Applicable Versions
spree Applicable Versions
stack_commons Applicable Versions
storj Applicable Versions
strongloop Applicable Versions
sudo_consul Applicable Versions
supermarket Applicable Versions
symfony Applicable Versions
teleport-le Applicable Versions
thumbor Applicable Versions
thumbor_ng Applicable Versions
webapp Applicable Versions
wordpress Applicable Versions
ya-piwik Applicable Versions
zabbix Applicable Versions
zabbix_lwrp Applicable Versions
zammad Applicable Versions

No quality metric results found