Installs Nginx on RedHat/CentOS or Debian/Ubuntu Linux, or FreeBSD servers.
Installs Nginx on RedHat/CentOS, Debian/Ubuntu, Archlinux, FreeBSD or OpenBSD servers.
This role installs and configures the latest version of Nginx from the Nginx yum repository (on RedHat-based systems) or via apt (on Debian-based systems) or pkgng (on FreeBSD systems). You will likely need to do extra setup work after this role has installed Nginx, like adding your own [virtualhost].conf file inside `/etc/nginx/conf.d/`, describing the location and options to use for your particular website.
This role installs and configures the latest version of Nginx from the Nginx yum repository (on RedHat-based systems), apt (on Debian-based systems), pacman (Archlinux), pkgng (on FreeBSD systems) or pkg_add (on OpenBSD systems). You will likely need to do extra setup work after this role has installed Nginx, like adding your own [virtualhost].conf file inside `/etc/nginx/conf.d/`, describing the location and options to use for your particular website.
## Requirements
@ -16,16 +16,20 @@ Available variables are listed below, along with default values (see `defaults/m
nginx_vhosts: []
A list of vhost definitions (server blocks) for Nginx virtual hosts. If left empty, you will need to supply your own virtual host configuration. See the commented example in `defaults/main.yml` for available server options. If you have a large number of customizations required for your server definition(s), you're likely better off managing the vhost configuration file yourself, leaving this variable set to `[]`.
A list of vhost definitions (server blocks) for Nginx virtual hosts. Each entry will create a separate config file named by `server_name`. If left empty, you will need to supply your own virtual host configuration. See the commented example in `defaults/main.yml` for available server options. If you have a large number of customizations required for your server definition(s), you're likely better off managing the vhost configuration file yourself, leaving this variable set to `[]`.
nginx_vhosts:
- listen: "80 default_server"
- listen: "443 ssl http2"
server_name: "example.com"
server_name_redirect: "www.example.com"
root: "/var/www/example.com"
index: "index.php index.html index.htm"
error_page: ""
access_log: ""
error_log: ""
state: "present"
template: "{{ nginx_vhost_template }}"
filename: "example.com.conf"
extra_parameters: |
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
@ -34,18 +38,27 @@ A list of vhost definitions (server blocks) for Nginx virtual hosts. If left emp
An example of a fully-populated nginx_vhosts entry, using a `|` to declare a block of syntax for the `extra_parameters`.
Please take note of the indentation in the above block. The first line should be a normal 2-space indent. All other lines should be indented normally relative to that line. In the generated file, the entire block will be 4-space indented. This style will ensure the config file is indented correctly.
nginx_remove_default_vhost: false
- listen: "80"
server_name: "example.com www.example.com"
return: "301 https://example.com$request_uri"
filename: "example.com.80.conf"
Whether to remove the 'default' virtualhost configuration supplied by Nginx. Useful if you want the base `/` URL to be directed at one of your own virtual hosts configured in a separate .conf file.
An example of a secondary vhost which will redirect to the one shown above.
nginx_vhosts_filename: "vhosts.conf"
*Note: The `filename` defaults to the first domain in `server_name`, if you have two vhosts with the same domain, eg. a redirect, you need to manually set the `filename` so the second one doesn't override the first one*
nginx_remove_default_vhost: false
The filename to use to store vhosts configuration. If you run the role multiple times (e.g. include the role with `with_items`), you can change the name for each run, effectively creating a separate vhosts file per vhost configuration.
Whether to remove the 'default' virtualhost configuration supplied by Nginx. Useful if you want the base `/` URL to be directed at one of your own virtual hosts configured in a separate .conf file.
nginx_upstreams: []
@ -53,7 +66,7 @@ If you are configuring Nginx as a load balancer, you can define one or more upst
nginx_user: "nginx"
The user under which Nginx will run. Defaults to `nginx` for RedHat, and `www-data` for Debian.
The user under which Nginx will run. Defaults to `nginx` for RedHat, `www-data` for Debian and `www` on FreeBSD and OpenBSD.
@ -77,6 +90,10 @@ TCP connection options. See [this blog post](https://t37.net/nginx-optimization-
Nginx keepalive settings. Timeout should be set higher (10s+) if you have more polling-style traffic (AJAX-powered sites especially), or lower (<10s)ifyouhaveasitewheremostusersvisitafewpagesanddon'tsendanyfurtherrequests.
nginx_server_tokens: "on"
Nginx server_tokens settings. Controls whether nginx responds with it's version in HTTP headers. Set to `"off"` to disable.
nginx_client_max_body_size: "64m"
This value determines the largest file upload possible, as uploads are passed through Nginx before hitting a backend like `php-fpm`. If you get an error like `client intended to send too large body`, it means this value is set too low.
@ -100,6 +117,24 @@ Extra lines to be inserted in the top-level `http` block in `nginx.conf`. The va
See the template in `templates/nginx.conf.j2` for more details on the placement.
nginx_extra_conf_options: ""
Extra lines to be inserted in the top of `nginx.conf`. The value should be defined literally (as you would insert it directly in the `nginx.conf`, adhering to the Nginx configuration syntax - such as `;` for line termination, etc.), for example:
nginx_extra_conf_options: |
worker_rlimit_nofile 8192;
See the template in `templates/nginx.conf.j2` for more details on the placement.
(For Debian/Ubuntu only) Allows you to set a different repository for the installation of Nginx. As an example, if you are running Debian's wheezy release, and want to get a newer version of Nginx, you can install the `wheezy-backports` repository and set that value here, and Ansible will use that as the `-t` option while installing Nginx.
@ -109,6 +144,77 @@ Extra lines to be inserted in the top-level `http` block in `nginx.conf`. The va
(For Ubuntu only) Allows you to use the official Nginx PPA instead of the system's package. You can set the version to `stable` or `development`.
nginx_yum_repo_enabled: true
(For RedHat/CentOS only) Set this to `false` to disable the installation of the `nginx` yum repository. This could be necessary if you want the default OS stable packages, or if you use Satellite.
## Overriding configuration templates
If you can't customize via variables because an option isn't exposed, you can override the template used to generate the virtualhost configuration files or the `nginx.conf` file.
```yaml
nginx_conf_template: "nginx.conf.j2"
nginx_vhost_template: "vhost.j2"
```
If necessary you can also set the template on a per vhost basis.
You can either copy and modify the provided template, or extend it with [Jinja2 template inheritance](http://jinja.pocoo.org/docs/2.9/templates/#template-inheritance) and override the specific template block you need to change.
### Example: Configure gzip in nginx configuration
Set the `nginx_conf_template` to point to a template file in your playbook directory.
1. Make the test shim executable: `chmod +x tests/test.sh`.
1. Run (from the role root directory) `distro=[distro] playbook=[playbook] ./tests/test.sh`
If you don't want the container to be automatically deleted after the test playbook is run, add the following environment variables: `cleanup=false container_id=$(date +%s)`
Chris Wells
7 years ago