https://github.com/s-hamann/ansible-nginx
Ansible role to set up nginx and optionally PHP and Python
https://github.com/s-hamann/ansible-nginx
ansible-role nginx php-fpm
Last synced: 2 months ago
JSON representation
Ansible role to set up nginx and optionally PHP and Python
- Host: GitHub
- URL: https://github.com/s-hamann/ansible-nginx
- Owner: s-hamann
- Created: 2019-11-01T16:58:26.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-12-09T19:33:06.000Z (7 months ago)
- Last Synced: 2025-12-26T22:48:57.174Z (6 months ago)
- Topics: ansible-role, nginx, php-fpm
- Language: Jinja
- Homepage:
- Size: 106 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Nginx
=====
This role sets up nginx as a web server or reverse proxy.
PHP support can be enabled using PHP-FPM.
Python support can be enabled using [Gunicorn](https://gunicorn.org/).
Deploying web content is outside the scope of this role.
Requirements
------------
If TLS encryption (i.e. HTTPS) is desired, the target system needs to have a suitable X.509 certificate.
This roles does not handle deploying certificates.
Role Variables
--------------
* `nginx_extra_groups`
A list of groups that the web server system user is added to.
This allows granting access to additional resources, such as the private key file.
All groups need to exist on the target system; this role does not create them.
Empty by default.
* `nginx_extra_packages`
A list of packages that should be installed in addition to those deemed necessary by this role.
This can be used, for example, to ensure that certain PHP extensions are present.
Empty by default.
* `nginx_extra_use_flags`
A dictionary with additional use flags.
The following keys are valid:
* `nginx`
* `php`
Each key holds a list of USE flags to enable or disable for the respective software in addition to those deemed necessary by this role.
This can be used, for example, to ensure that certain PHP extensions are present.
Empty by default.
Only used on Gentoo.
* `nginx_php_version`
The PHP version slot to use, i.e. the major and minor version only.
If not set, the latest version in portage that is not masked (by keyword, package mask, ...) is used.
Only used on Gentoo.
* `nginx_writable_paths`
If the target system uses systemd, the file system is mostly read-only to nginx (and PHP and Gunicorn).
A list of paths that should be writable can be given in `nginx_writable_paths`.
This typically includes upload paths.
Directories containing log files (defined by the appropriate variables) are automatically made writable.
By default, no paths are writable.
* `nginx_inaccessible_paths`
If the target system uses systemd, this option takes a list of paths, that should not be accessible at all for nginx (and PHP).
Regardless of this option, home directories are made inaccessible and the directories holding TLS private keys are made inaccessible for PHP and Gunicorn.
Optional.
* `nginx_config_template`
An alternative jinja2 template to generate `nginx.conf`.
The template may extend the default `nginx.conf.j2`, overriding only certain blocks.
Optional.
* `nginx_worker_processes`
The number of worker processes nginx uses to serve requests.
Defaults to `auto`, the number CPUs cores detected by nginx on startup.
* `nginx_tls13_only`
If set to `true`, nginx is configured to support only TLSv1.3.
The target system needs to have OpenSSL 1.1 or newer for this to work.
If set to `false` (the default) TLSv1.2 is supported in addition to TLSv1.3.
* `nginx_ciphers`
A string describing the enabled cipher suites as understood by OpenSSL.
The default contains only strong AEAD ciphers with PFS.
* `nginx_max_body_size`
Maximum allowable body size in MB.
In particular, this limits the maximum size of file uploads.
Default is `1`, which is usually more than enough for sites that do not accept file uploads.
* `nginx_keepalive_timeout`
The timeout (in seconds) for HTTP keep-alive connections.
Defaults to `65` seconds.
* `nginx_gzip_static`
Enable support for pre-compressed static responses.
This setting does not globally enable `gzip_static` in nginx, but does it in a location for certain compressible file types.
A script to generate or update the statically compressed files in all defined web roots is installed as `/usr/local/sbin/update_gzip_static.sh`.
The handler `nginx_update_gzip_static` may be notified to run this script.
`gzip_static` can be enabled for custom locations as well, if this is desired.
Defaults to `true`.
* `nginx_gzip_dynamic`
Enable dynamic response compression.
Only responses with certain content types and a minimal length are compresses in order to avoid a negative impact on performance.
Defaults to `true`.
* `nginx_access_log`
The global access log file.
This can be overwritten per vhost.
Defaults to `false`, which disables logging on the global level.
* `nginx_access_log_options`
Options to the `access_log` directive, such as `buffer` (cf. the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log)).
Optional.
* `nginx_log_format`
A custom access log format specification.
Refer to the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) on `log_format` for information on what to put here.
Optional.
* `nginx_error_log`
The global log file for errors.
This can be overwritten per vhost.
If not set, logs go to the systemd journal or syslog, as appropriate.
* `nginx_security_headers`
This role sets up a number of security relevant HTTP headers.
`nginx_security_headers` is a dictionary that allows tuning their values from the defaults or adding new headers.
Keys are header names and values are header values.
Optional.
* `nginx_caching_policy`
A dictionary describing the caching policy for each content type.
The keys are content types, such as `text/html`.
Regular expressions are also allowed when prefixed with `~` (case-sensitive matching) or `~*` (case-insensitive matching).
The special value `default` is for all responses that are not matched by any other key.
Values are caching times as accepted by the `expires` directive (cf. the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_headers_module.html#expires)).
* `nginx_extra_options`
A dictionary with additional options.
The following keys are valid:
* `nginx` (for the main part in `nginx.conf`)
* `nginx_http` (for the `http` block in `nginx.conf`)
Each key in turn holds a list of options for the respective configuration file or file section.
* `nginx_vhosts`
A list of dictionaries describing vhost configurations.
Each vhost is written to a separate configuration file on the target system.
For each list entry, the following keys are valid:
* `filename`
The name of the file to hold the vhost configuration.
Mandatory.
* `template`
Path to the jinja2 template file for this vhost.
See `nginx_config_template`.
Optional.
* `server_name`
A list of host names for this vhost.
The first vhost for a `ip` and `port` combination is the default one and accepts all names not set on any other vhosts.
Optional.
* `ip`
The IP address this vhost listens on.
This can be used to make nginx reachable on a specific network interface only.
Defaults to `[::]`, i.e. all interfaces on both IPv4 and IPv6.
* `port`
The TCP port on which this vhost is reachable.
Defaults to `443` when `use_tls` is set and `80` otherwise.
* `unencrypted_port`
When `use_tls` is set, this port is configured to accept unencrypted HTTP connection.
All connections are redirected to HTTPS.
Optional.
* `use_tls`
Whether to enable TLS (i.e. HTTPS) for this vhost.
Defaults to `false`.
* `tls_cert`
Path to a PEM-encoded X.509 certificate for this vhost.
The file needs to exist and be readable by the nginx user.
Mandatory if `use_tls` is set, ignored otherwise.
* `tls_cert_key`
Path to the PEM-encoded private key file for the certificate.
The file needs to exist and be readable by the nginx user.
Mandatory if `use_tls` is set, ignored otherwise.
* `use_php`
Whether to enable PHP for this vhost.
Defaults to `false`.
* `root`
Path to the web root directory for this vhost.
Mandatory, except in some special configurations.
* `index`
Index file names, separated by spaces.
Defaults to `index.php index.html index.htm` (where `index.php` is omitted if `use_php` is not set).
* `security_headers`
A dictionary containing vhost-specific overrides of `nginx_security_headers`.
Optional.
* `disabled_security_headers`
A list of header names that should *not* be set for this vhost.
Optional.
* `error_page`
A list of error pages for specific status codes.
Refer to `error_page` in the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page) for information on the format.
Optional.
* `access_log`
Sets the access log for this vhost.
This can be overwritten in locations.
If not set, the global access log file (cf. `nginx_access_log`) is used.
* `error_log`
Sets the error log for this vhost.
If not set, the global error log file (cf. `nginx_error_log`) is used.
* `static_assets`
A regular expression that matches all URLs of static assets.
The default value should match most common file types.
* `log_static_assets`
If set to `false`, access to static assets (cf. `static_assets`) is not logged.
Defaults to `true`.
* `static_extra_options`
A list of additional configuration options for the location block that handles static assets (cf. `static_assets`).
Optional.
* `extra_options`
A list of additional configuration options for this vhost.
Optional.
* `php_extra_options`
A list of additional configuration options for the location block that handles PHP URLs.
Only used when `use_php` is `true`.
Optional.
* `blocked_locations`
A list of paths relative to the web root directory that should not be served via HTTP (a 404 is returned).
The web server still has access to these files and may include them server-side.
This is useful, for instance, for configuration files and packaging artifacts.
The paths are interpreted as prefixes, i.e. all files and directories with these prefixes match.
Locations beginning with `=` override this and can make blocked path available.
* `locations`
A dictionary of location configurations.
Keys are location matching patterns as understood by nginx (cf. the `location` directive in the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_core_module.html#location)).
In short, they are matched against the URL relative to the web root directory and may be a prefix string (possibly prefixed with `=` or `^~`) or a regular expression (prefixed with `~` or `~*`).
Each location key in turn holds a dictionary containing the configuration for this location.
The following keys are valid for locations:
* `return`
This can be used to always return a specific status code.
See `return` in the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return) for further information.
* `gzip_dynamic`
Specifically enable or disable dynamic response compression for this location. Boolean.
See also: `nginx_gzip_dynamic`.
* `gzip_static`
Specifically enable or disable support for pre-compressed responses. Boolean.
See also: `nginx_gzip_static`.
* `access_log`
Sets the access log for this location.
If not set, the vhost's access log file is used.
* `upstream`
A dictionary of settings for the [HTTP Proxy module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html).
When set, nginx acts as a reverse proxy for this location.
Keys are directive names and values are their parameters.
Set the value to `null` for directives that do not expect parameters.
Set the value to a list of values to repeat the directive.
Refer to the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) for valid directives and their meaning.
The following key have a special meaning:
* `name`
The name of the upstream to proxy to, i.e. one of the key in the `upstreams` dictionary (see below).
Mandatory.
* `headers`
A dictionary of header fields and their values.
These fields will be sent to the proxied upstream server.
See [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) for more information.
A number of commonly useful header fields are set by default.
Set them to `omit` to not pass them to the proxied upstream.
Optional.
* `websocket`
Whether to support proxying WebSocket connections.
Defaults to `false`.
* `extra_options`
A list of additional configuration options for this location.
* `gunicorn_server`
When set, all requests to this location are passed to the given Gunicorn server instance.
The value must be the name of a Gunicorn server instance defined in `nginx_gunicorn_servers`.
* `upstreams`
A dictionary of upstream configurations.
Keys are upstream names and values are in turn dictionaries describing the settings for this upstream.
In this dictionary keys are interpreted as upstream directive names and values as their parameters.
Set the value to `null` for directives that do not expect parameters.
Set the value to a list of values to repeat the directive.
Refer to the [nginx documentation](https://nginx.org/en/docs/http/ngx_http_upstream_module.html) for valid directives and their meaning.
The following options are specific to PHP and are only used if at least one vhost has `use_php` set.
* `nginx_php_process_manager`
What process manager to use for PHP's resource pool.
One of `static`, `dynamic` or `ondemand`.
The default is `dynamic`.
* `nginx_php_max_children`
The maximum number of PHP processes to run simultaneously.
This is the limit for the number of requests that can be served simultaneously by PHP.
The default is `5`, but should usually be changed.
* `nginx_php_min_spare_children`, `nginx_php_max_spare_children`
If `nginx_php_process_manager` is `dynamic`, PHP keeps a number of spare processes to quickly handle new connections.
These two settings put a limit on the number of spare processes.
When using a different process manager, these settings have no effect.
The defaults are `1` and `3`, respectively, but should usually be changed.
* `nginx_php_process_idle_timeout`
If `nginx_php_process_manager` is `ondemand`, keeps idle processes alive to serve further requests.
This sets the time (in seconds) after which idle processes are killed to free up resources.
This setting is ignored when using a different process manager.
The default is `10` seconds.
* `nginx_php_user`
The name of the system user account to run PHP as.
Defaults to the same account as nginx.
* `nginx_php_group`
The name of the system group to run PHP as.
Defaults to the same group as nginx.
* `nginx_php_max_requests`
Respawn PHP processes after handling this number of requests.
The default value `0` disables this.
* `nginx_php_timeout`
The maximum time (in seconds) for PHP requests to be processed.
Defaults to `30` seconds.
* `nginx_php_status_path`
URL-path to the PHP status page, which displays information about the FPM pool.
The status page will be made available on every vhost that uses PHP and does not define a location with the same path.
By default, this is not set, i.e. there is no status page.
* `nginx_php_ping_path`
URL-path to the PHP ping page.
This page returns status code `200` and the body `pong` if PHP-FPM is working.
The ping page will be made available on every vhost that uses PHP and does not define a location with the same path.
By default, this is not set, i.e. there is no ping page.
* `nginx_php_monitor_ips`
A list of IP addresses that can access the ping and status pages.
If this is not set, access is not restricted.
* `nginx_php_timezone`
The system's time zone.
Can also be set using the variable `timezone`.
* `nginx_php_error_log`
The log file for PHP errors.
Defaults to `syslog`.
* `nginx_php_enabled_functions`
This role disables a number of functions in PHP that are a common source of security issues or allow system access.
To prevent breaking applications, `nginx_php_enabled_functions` can hold a list of functions that should explicitly not be disabled.
Empty by default.
* `nginx_php_extensions`
A list of PHP extensions to load, such as `curl` or `gd`.
Extensions that are not part of the PHP distribution are automatically installed using the target system's package management.
This may not work in all cases.
Empty by default.
* `nginx_php_zend_extensions`
A list of PHP Zend extensions to load, such as `opcache`.
Extensions that are not part of the PHP distribution are automatically installed using the target system's package management.
This may not work in all cases.
Empty by default.
* `nginx_php_extra_options`
Additional configuration options for PHP.
This variable is a dictionary with the following keys:
* `php-fpm` (for the `global` section of `php-fpm.conf`)
* `php-fpm_pool` (for the pool section of `php-fpm.conf`)
* any other key is added to `php.ini` as a section named like the key
The values are in turn dictionaries where keys are PHP configuration options for the appropriate section and values are the corresponding configuration values.
The following options are specific to Gunicorn and are only used if at least one location has `gunicorn_server` set.
* `nginx_gunicorn_servers`
A dictionary of Gunicorn server instance configurations.
The dictionary keys are the names of the instances and are referenced by the `gunicorn_server` setting of locations.
Dictionary values are in turn dictionaries that describe the settings for this Gunicorn instance.
The may have the following keys:
* `venv_path`
Directory of a virtual python environment in which the application is installed.
When set, the python installation in this venv is used to run Gunicorn.
This only works if Gunicorn is installed into the virtual environment or if the virtual environment has access to the system packages.
Note that this role does not create or set up the virtual environment.
Optional.
* `options`
A dictionary of configuration options for Gunicorn.
Dictionary keys are option names and dictionary values the respective values.
Refer to [Gunicorn's documentation](https://docs.gunicorn.org/en/stable/settings.html) for valid options and their meaning.
Note that these options are not passed on the command line, but are written to Gunicorn's configuration file.
To configure the WSGI application to run set the `wsgi_app` option.
Optional.
* `environment`
A dictionary of environment variables and their respective values that will be exported to gunicorn and the WSGI application it hosts.
Optional.
* `systemd_override`
If the target system uses systemd, appropriate unit files are created to start Gunicorn server instances.
This option allows customizing these units, e.g. to apply more security restrictions or loosen the default ones.
Must be a dictionary where keys are the names of options valid in the `[Service]` section of a systemd unit and dictionary values are the respective values.
Refer to `man 5 systemd.service`, `man 5 systemd.exec` and `man 5 systemd.kill` for valid settings and their meaning.
Optional.
Ignored if the target system does not use systemd.
Dependencies
------------
This role does not set up TLS certificates and therefore depends on a role that generates and deploys them, if HTTPS support is desired.
Example Configuration
---------------------
The following is a short example for some of the configuration options this role provides:
```yaml
nginx_writable_paths:
- '/var/www/example/uploads'
nginx_inaccessible_paths:
- '/mnt/backups'
nginx_max_body_size: 16
nginx_security_headers:
Content-Security-Policy: "default-src 'none'"
X-Frame-Options: 'DENY'
nginx_caching_policy:
default: off
text/css: 7d
~image/: 1h
nginx_vhosts:
- filename: example.conf
use_tls: true
unencrypted_port: 80
tls_cert: "/etc/ssl/private/{{ inventory_hostname }}.pem"
tls_cert_key: "/etc/ssl/private/{{ inventory_hostname }}.key"
use_php: true
root: '/var/www/example/'
access_log: '/var/log/nginx/example/access.log'
extra_options:
- 'rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last'
blocked_locations:
- '/config'
- '/backups'
- '\.zip$'
locations:
/doc:
access_log: false
gzip_static: true
extra_options:
- 'index index.html'
~\.log$:
return: 403
- filename: some_app.conf
locations:
/:
gunicorn_server: some_app
/static:
root: /opt/some_app/static
- filename: some_other_app.conf
root: /opt/some_other_app/static
locations:
/:
extra_options:
- 'try_files $uri @some_other_app'
'@some_other_app':
gunicorn_server: some_other_app
- filename: proxy.conf
upstreams:
proxy:
server:
- backend1.example.com weight=5
- 127.0.0.1:8080 max_fails=3 fail_timeout=30s
- unix:/tmp/backend3
- backup1.example.com backup
ip_hash: null
keepalive: 16
locations:
/:
upstream:
name: proxy
headers:
X-Example-Header: 'added by nginx'
proxy_redirect: false
nginx_php_enabled_functions:
- 'phpinfo'
nginx_php_extensions:
- 'curl'
- 'gd'
nginx_php_extra_options:
php-fpm:
emergency_restart_threshold: 3
php-fpm_pool:
request_terminate_timeout: 10
PHP:
precision: 16
variables_order: 'GPCS'
allow_url_include: true
bcmath:
bcmath.scale: 16
Session:
session.name: 'SessionID'
nginx_gunicorn_servers:
some_app:
venv_path: /opt/some_app/
options:
wsgi_app: some_app:run
workers: 2
systemd_override:
RestrictAddressFamilies:
- null
- AF_UNIX
some_other_app:
options:
chdir: /opt/some_other_app/
wsgi_app: some_other_app
```
License
-------
MIT