forked from CCCHH/ansible-infra
June
4adf39d969
Document the role arguments in the README instead of in the argument_specs for better discoverability and readability.
77 lines
3.4 KiB
Markdown
77 lines
3.4 KiB
Markdown
# Role `nginx`
|
|
|
|
Makes sure the `nginx` package is installed from the NGINX repos on the specified hosts.
|
|
Also makes sure a desirable baseline of NGINX configs is deployed on the specified hosts.
|
|
For the NGINX site configurations the config template below can be used.
|
|
|
|
## Entry Points
|
|
|
|
The entry points available for external use are:
|
|
|
|
- `main`
|
|
|
|
## Supported Distributions
|
|
|
|
The following distributions are supported:
|
|
|
|
- Debian 11
|
|
|
|
## Required Arguments
|
|
|
|
None.
|
|
|
|
## Optional Arguments
|
|
|
|
- `nginx__deploy_redirect_conf`: Whether or not to deploy a config redirecting from HTTP to HTTPS, while still forwarding the `/.well-known/acme-challenge/` to localhost Port 31820 for certificate issuing.
|
|
See [`files/redirect.conf`](./files/redirect.conf) for the configuration that would be deployed.
|
|
Defaults to `true`.
|
|
- `nginx__deploy_tls_conf`: Whether or not to deploy a config configuring some TLS settings reasonably.
|
|
See [`files/tls.conf`](./files/tls.conf) for the configuration that would be deployed.
|
|
Defaults to `true`.
|
|
- `nginx__deploy_logging_conf`: Whether or not to deploy a config configuring logging to journald.
|
|
See [`files/logging.conf`](./files/logging.conf) for the configuration that would be deployed.
|
|
Defaults to `true`.
|
|
- `nginx__configurations`: List of nginx configurations to ensure are deployed.
|
|
- `nginx__configurations.*.name`: This name with `.conf` appended will be used for the configurations file name under `/etc/nginx/conf.d/`.
|
|
`tls` and `redirect` are reserved names.
|
|
- `nginx__configurations.*.content`: This configurations content.
|
|
- `nginx__use_custom_nginx_conf`: Whether or not to use a custom `/etc/nginx/nginx.conf`.
|
|
If set to true, you must provide the content for a custom `nginx.conf` via `nginx__custom_nginx_conf`.
|
|
Defaults to `false`.
|
|
- `nginx__custom_nginx_conf`: The content to use for the custom `nginx.conf`.
|
|
Needs `nginx__use_custom_nginx_conf` to be set to true to work.
|
|
You should probably still make sure that your custom `nginx.conf` includes `/etc/nginx/conf.d/*.conf`, so that the other configuration files still work.
|
|
|
|
## `hosts`
|
|
|
|
The `hosts` for this role need to be the machines, for which you want to make sure the `nginx` package is installed from the NGINX repos and a desirable baseline of NGINX configs is deployed.
|
|
|
|
## Config Template
|
|
|
|
Here's a config template, which can be used for new NGINX site configs, which you can supply to this role using the `nginx__configurations` argument.
|
|
Just replace the placeholder values with real ones and extend and edit it as needed.
|
|
|
|
```
|
|
# partly generated 2022-01-08, Mozilla Guideline v5.6, nginx 1.17.7, OpenSSL 1.1.1k, intermediate configuration
|
|
# https://ssl-config.mozilla.org/#server=nginx&version=1.17.7&config=intermediate&openssl=1.1.1k&guideline=5.6
|
|
server {
|
|
listen 443 ssl http2;
|
|
#listen [::]:443 ssl http2;
|
|
server_name replace_me;
|
|
|
|
ssl_certificate /path/to/signed_cert_plus_intermediates;
|
|
ssl_certificate_key /path/to/private_key;
|
|
# verify chain of trust of OCSP response using Root CA and Intermediate certs
|
|
ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;
|
|
|
|
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
|
|
add_header Strict-Transport-Security "max-age=63072000" always;
|
|
|
|
# replace with the IP address of your resolver
|
|
resolver 127.0.0.1;
|
|
}
|
|
```
|
|
|
|
## Links & Resources
|
|
|
|
- <https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#installing-prebuilt-debian-packages>
|