nginx_site

Overview

This is an Ansible role for configuring nginx sites (actually domains, which on nginx also have the unfortunate name “servers”) on Debian or Ubuntu. It depends on nginx, which must also be listed as a role for the server. The minimal way to use it is this:

- role: nginx_site
  server_name: example.org

but the most usual will be like this:

- role: nginx_site
  server_name: example.org
  server_aliases:
    - www.example.org
  letsencrypt: true
  force_ssl: true

Except for configuration done through the variables specified below, other roles can also drop configuration files in /etc/nginx/snippets/DOMAIN_NAME/, and notify the Reload nginx handler. These snippets are included in the configuration.

Parameters

server_name

The canonical domain name.

server_aliases

A list of domain aliases, which will be redirected to the canonical server name.

server_aliases_without_redirect

Domain aliases to be served as is, not to be redirected to the canonical (this is intended for testing, for example when it’s not yet possible to transfer the main domain to a new server and an alternative domain needs to be used while the new server is being setup).

document_root

The document root. The default is /var/www/{{ server_name }}.

extras

A string with extra configuration to be added to the configuration file. You should generally not use this; dropping a snippet in /etc/nginx/snippets/SITE_NAME/ is usually a better solution.

nonssl_extras

Like extras, but this is configuration that will only be used for non-SSL. You are unlikely to need this; normally extras should suffice.

ssl_extras

Like extras, but this is configuration that will only be used for SSL (extras is also used for SSL). Ignored if cert is unset. You are unlikely to need this; normally extras should suffice.

letsencrypt

Can be “true” or “false” (the default) or a string. The usual value for Let’s Encrypt certificates is “true”, in which case the Let’s Encrypt certificates for server_name are used; if they don’t exist in /etc/letsencrypt, they are created with certbot. If a string is used, it’s the same thing, except that the string is used as the domain name instead of server_name. If letsencrypt is false and nginx_ssl is true, Debian’s automatically created self-signed “snakeoil” certificates are used.

letsencrypt_admin

The email that is registered with certbot. This must be specified if letsencrypt is specified. Let’s Encrypt will email that address if the certificate fails to renew.

nginx_ssl

Can be “true” (the default) or “false”. If “false”, SSL is disabled,

force_ssl

Can be “true” or “false” (the default). If “true”, visiting the non-ssl version will redirect to the ssl version. If force_ssl is “true”, letsencrypt must be specified.