Improve documentation (#206)
* Create CONTRIBUTING.md * Add PR template * Tweak .yamllint * Update README playbook examples
This commit is contained in:
parent
36ba93a5d7
commit
b5baf3a2ae
10
.github/pull_request_template.md
vendored
Normal file
10
.github/pull_request_template.md
vendored
Normal file
@ -0,0 +1,10 @@
|
||||
### Proposed changes
|
||||
Describe the use case and detail of the change. If this PR addresses an issue on GitHub, make sure to include a link to that issue here in this description (not in the title of the PR).
|
||||
|
||||
### Checklist
|
||||
Before creating a PR, run through this checklist and mark each as complete.
|
||||
|
||||
- [ ] I have read the [CONTRIBUTING](https://github.com/nginxinc/ansible-role-nginx/blob/master/CONTRIBUTING.md) document
|
||||
- [ ] I have added Molecule tests that prove my fix is effective or that my feature works
|
||||
- [ ] I have checked that all unit tests pass after adding my changes
|
||||
- [ ] If required, I have updated necessary documentation (`defaults/main/` and `README.md`)
|
@ -7,7 +7,6 @@ rules:
|
||||
brackets:
|
||||
max-spaces-inside: 1
|
||||
level: error
|
||||
comments: disable
|
||||
comments-indentation: disable
|
||||
line-length: disable
|
||||
truthy: disable
|
||||
|
72
CONTRIBUTING.md
Normal file
72
CONTRIBUTING.md
Normal file
@ -0,0 +1,72 @@
|
||||
# Contributing Guidelines
|
||||
|
||||
The following is a set of guidelines for contributing to the NGINX Ansible role. We really appreciate that you are considering contributing!
|
||||
|
||||
#### Table Of Contents
|
||||
|
||||
[Ask a Question](#ask-a-question)
|
||||
|
||||
[Getting Started](#getting-started)
|
||||
|
||||
[Contributing](#contributing)
|
||||
|
||||
[Code Guidelines](#code-guidelines)
|
||||
* [Git Guidelines](#git-guidelines)
|
||||
* [Ansible Guidelines](#ansible-guidelines)
|
||||
|
||||
[Code of Conduct](https://github.com/nginxinc/ansible-role-nginx/blob/master/CODE_OF_CONDUCT.md)
|
||||
|
||||
## Ask a Question
|
||||
|
||||
Please open an Issue on GitHub with the label `question`.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Follow our [Installation Guide](https://github.com/nginxinc/ansible-role-nginx/blob/master/README.md#Installation) to install Ansible and Molecule and get ready to use the NGINX Ansible role.
|
||||
|
||||
### Project Structure
|
||||
|
||||
* The NGINX Ansible role is written in `yaml` and supports open source NGINX, NGINX Plus, NGINX Amplify, NGINX Controller, and NGINX Unit.
|
||||
* The project follows the standard [Ansible role directory structure](https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html)
|
||||
* The main code is found at `tasks/`
|
||||
* The main variables can be found at `defaults/main/`
|
||||
* Configuration templates for NGINX can be found at `templates/`
|
||||
* [Molecule](https://molecule.readthedocs.io/) tests can be found in `molecule/`.
|
||||
* CI/CD is done via Travis using `.travis.yml` Deployment yaml files, and Helm files are found at `deployments/`
|
||||
|
||||
## Contributing
|
||||
|
||||
### Report a Bug
|
||||
|
||||
To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the issue has not already been reported.
|
||||
|
||||
### Suggest an Enhancement
|
||||
|
||||
To suggest an enhancement, please create an issue on GitHub with the label `enhancement` using the available feature issue template.
|
||||
|
||||
### Open a Pull Request
|
||||
|
||||
* Fork the repo, create a branch, submit a PR when your changes are tested and ready for review
|
||||
* Fill in [our pull request template](https://github.com/nginxinc/ansible-role-nginx/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
|
||||
|
||||
Note: if you’d like to implement a new feature, please consider creating a feature request issue first to start a discussion about the feature.
|
||||
|
||||
## Code Guidelines
|
||||
|
||||
### Git Guidelines
|
||||
|
||||
* Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR
|
||||
* Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/> and summarised in the next few points
|
||||
* In the subject line, use the present tense ("Add feature" not "Added feature")
|
||||
* In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
|
||||
* Limit the subject line to 72 characters or less
|
||||
* Reference issues and pull requests liberally after the subject line
|
||||
* Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in your text editor to write a good message instead of `git commit -am`)
|
||||
|
||||
### Ansible Guidelines
|
||||
|
||||
* Run `molecule lint` over your code to automatically resolve a lot of `yaml` and Ansible style issues.
|
||||
* Run `molecule test --all` on your code to catch any other issues.
|
||||
* Follow these guides on some good practices for Ansible:
|
||||
* <https://www.ansible.com/blog/ansible-best-practices-essentials>
|
||||
* <https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html>
|
55
README.md
55
README.md
@ -13,14 +13,29 @@ Requirements
|
||||
|
||||
**Ansible**
|
||||
|
||||
This role was developed and tested with [maintained](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#release-status) versions of
|
||||
Ansible. Backwards compatibility is not guaranteed.
|
||||
This role was developed and tested with [maintained](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#release-status) versions of Ansible. Backwards compatibility is not guaranteed.
|
||||
|
||||
Instructions on how to install Ansible can be found in the [Ansible website](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html).
|
||||
|
||||
**Molecule**
|
||||
|
||||
Molecule is used to test the various functionailities of the role. Instructions on how to install Molecule can be found in the [Molecule website](https://molecule.readthedocs.io/en/stable/installation.html).
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
**Ansible Galaxy**
|
||||
|
||||
Use `ansible-galaxy install nginxinc.nginx` to install the role on your system.
|
||||
Use `ansible-galaxy install nginxinc.nginx` to install the latest stable release of the role on your system.
|
||||
|
||||
It supports all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html#mainline) and [NGINX Plus](https://www.nginx.com/products/technical-specs/):
|
||||
**Git**
|
||||
|
||||
Use `git clone https://github.com/nginxinc/ansible-role-nginx.git` to pull the latest edge commit of the role from GitHub.
|
||||
|
||||
Platforms
|
||||
---------
|
||||
|
||||
The NGINX Ansible role supports all platforms supported by [NGINX Open Source](https://nginx.org/en/linux_packages.html#mainline), [NGINX Plus](https://www.nginx.com/products/technical-specs/), the [NGINX Amplify agent](https://github.com/nginxinc/nginx-amplify-doc/blob/master/amplify-faq.md#21-what-operating-systems-are-supported), the [NGINX Controller agent](https://docs.nginx.com/nginx-controller/technical-specs/#nginx-controller-agent-technical-specifications), and [NGINX Unit](https://unit.nginx.org/installation/#official-packages):
|
||||
|
||||
**NGINX Open Source**
|
||||
|
||||
@ -120,7 +135,6 @@ Debian:
|
||||
- stretch
|
||||
Ubuntu:
|
||||
versions:
|
||||
- trusty
|
||||
- xenial
|
||||
- bionic
|
||||
RedHat:
|
||||
@ -245,18 +259,23 @@ This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a
|
||||
template_file: http/default.conf.j2
|
||||
conf_file_name: default.conf
|
||||
conf_file_location: /etc/nginx/conf.d/
|
||||
port: 80
|
||||
server_name: localhost
|
||||
error_page: /usr/share/nginx/html
|
||||
autoindex: false
|
||||
web_server:
|
||||
locations:
|
||||
default:
|
||||
location: /
|
||||
html_file_location: /usr/share/nginx/html
|
||||
html_file_name: index.html
|
||||
autoindex: false
|
||||
http_demo_conf: false
|
||||
servers:
|
||||
server1:
|
||||
listen:
|
||||
listen_localhost:
|
||||
# ip: 0.0.0.0
|
||||
port: 80
|
||||
server_name: localhost
|
||||
error_page: /usr/share/nginx/html
|
||||
autoindex: false
|
||||
web_server:
|
||||
locations:
|
||||
default:
|
||||
location: /
|
||||
html_file_location: /usr/share/nginx/html
|
||||
html_file_name: index.html
|
||||
autoindex: false
|
||||
http_demo_conf: false
|
||||
```
|
||||
|
||||
This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost and installing the open source version of NGINX as a reverse proxy.
|
||||
@ -278,7 +297,7 @@ This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a
|
||||
server1:
|
||||
listen:
|
||||
listen_localhost:
|
||||
#ip: 0.0.0.0
|
||||
# ip: 0.0.0.0
|
||||
port: 80
|
||||
opts:
|
||||
- default_server
|
||||
|
@ -17,7 +17,7 @@ nginx_main_template:
|
||||
conf_file_location: /etc/nginx/
|
||||
user: nginx
|
||||
worker_processes: auto
|
||||
#worker_rlimit_nofile: 1024
|
||||
# worker_rlimit_nofile: 1024
|
||||
error_log:
|
||||
location: /var/log/nginx/error.log
|
||||
level: warn
|
||||
@ -39,15 +39,15 @@ nginx_main_template:
|
||||
cache: false
|
||||
rate_limit: false
|
||||
keyval: false
|
||||
#server_tokens: "off"
|
||||
# server_tokens: "off"
|
||||
http_global_autoindex: false
|
||||
#http_custom_options: []
|
||||
# http_custom_options: []
|
||||
stream_enable: false
|
||||
#stream_custom_options: []
|
||||
#auth_request_http: /auth
|
||||
#auth_request_set_http:
|
||||
#name: $auth_user
|
||||
#value: $upstream_http_x_user
|
||||
# stream_custom_options: []
|
||||
# auth_request_http: /auth
|
||||
# auth_request_set_http:
|
||||
# name: $auth_user
|
||||
# value: $upstream_http_x_user
|
||||
|
||||
# Enable creating dynamic templated NGINX HTTP configuration files.
|
||||
# Defaults will not produce a valid configuration. Instead they are meant to showcase
|
||||
@ -62,9 +62,9 @@ nginx_http_template:
|
||||
server1:
|
||||
listen:
|
||||
listen_localhost:
|
||||
ip: localhost # Wrap in square brackets for IPv6 addresses
|
||||
ip: localhost # Wrap in square brackets for IPv6 addresses
|
||||
port: 8081
|
||||
opts: [] # Listen opts like http2 which will be added (ssl is automatically added if you specify 'ssl:').
|
||||
opts: [] # Listen opts like http2 which will be added (ssl is automatically added if you specify 'ssl:').
|
||||
server_name: localhost
|
||||
include_files: []
|
||||
error_page: /usr/share/nginx/html
|
||||
@ -75,26 +75,26 @@ nginx_http_template:
|
||||
location: /var/log/nginx/error.log
|
||||
level: warn
|
||||
root: /usr/share/nginx/html
|
||||
#https_redirect: $host
|
||||
# https_redirect: $host
|
||||
autoindex: false
|
||||
auth_basic: null
|
||||
auth_basic_user_file: null
|
||||
try_files: $uri $uri/index.html $uri.html =404
|
||||
#auth_request: /auth
|
||||
#auth_request_set:
|
||||
#name: $auth_user
|
||||
#value: $upstream_http_x_user
|
||||
# auth_request: /auth
|
||||
# auth_request_set:
|
||||
# name: $auth_user
|
||||
# value: $upstream_http_x_user
|
||||
client_max_body_size: 1m
|
||||
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
|
||||
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
|
||||
add_headers:
|
||||
strict_transport_security:
|
||||
name: Strict-Transport-Security
|
||||
value: max-age=15768000; includeSubDomains
|
||||
always: true
|
||||
#header_name:
|
||||
#name: Header-X
|
||||
#value: Value-X
|
||||
#always: false
|
||||
# header_name:
|
||||
# name: Header-X
|
||||
# value: Value-X
|
||||
# always: false
|
||||
ssl:
|
||||
cert: /etc/ssl/certs/default.crt
|
||||
key: /etc/ssl/private/default.key
|
||||
@ -108,63 +108,63 @@ nginx_http_template:
|
||||
trusted_cert: /etc/ssl/certs/root_CA_cert_plus_intermediates.crt
|
||||
stapling: true
|
||||
stapling_verify: true
|
||||
#custom_options: []
|
||||
# custom_options: []
|
||||
web_server:
|
||||
locations:
|
||||
default:
|
||||
location: /
|
||||
include_files: []
|
||||
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
|
||||
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
|
||||
add_headers:
|
||||
strict_transport_security:
|
||||
name: Strict-Transport-Security
|
||||
value: max-age=15768000; includeSubDomains
|
||||
always: true
|
||||
#header_name:
|
||||
#name: Header-X
|
||||
#value: Value-X
|
||||
#always: false
|
||||
# header_name:
|
||||
# name: Header-X
|
||||
# value: Value-X
|
||||
# always: false
|
||||
html_file_location: /usr/share/nginx/html
|
||||
html_file_name: index.html
|
||||
autoindex: false
|
||||
auth_basic: null
|
||||
auth_basic_user_file: null
|
||||
try_files: $uri $uri/index.html $uri.html =404
|
||||
#auth_request: /auth
|
||||
#auth_request_set:
|
||||
#name: $auth_user
|
||||
#value: $upstream_http_x_user
|
||||
# auth_request: /auth
|
||||
# auth_request_set:
|
||||
# name: $auth_user
|
||||
# value: $upstream_http_x_user
|
||||
client_max_body_size: 1m
|
||||
#returns:
|
||||
#return302:
|
||||
#code: 302
|
||||
#url: https://sso.somehost.local/?url=https://$http_host$request_uri
|
||||
#custom_options: []
|
||||
# returns:
|
||||
# return302:
|
||||
# code: 302
|
||||
# url: https://sso.somehost.local/?url=https://$http_host$request_uri
|
||||
# custom_options: []
|
||||
http_demo_conf: false
|
||||
reverse_proxy:
|
||||
locations:
|
||||
backend:
|
||||
location: /
|
||||
include_files: []
|
||||
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
|
||||
proxy_hide_headers: [] # A list of headers which shouldn't be passed to the application
|
||||
add_headers:
|
||||
strict_transport_security:
|
||||
name: Strict-Transport-Security
|
||||
value: max-age=15768000; includeSubDomains
|
||||
always: true
|
||||
#header_name:
|
||||
#name: Header-X
|
||||
#value: Value-X
|
||||
#always: false
|
||||
# header_name:
|
||||
# name: Header-X
|
||||
# value: Value-X
|
||||
# always: false
|
||||
proxy_connect_timeout: null
|
||||
proxy_pass: http://backend
|
||||
#rewrites:
|
||||
# - /foo(.*) /$1 break
|
||||
#proxy_pass_request_body: off
|
||||
#allows:
|
||||
# - 192.168.1.0/24
|
||||
#denies:
|
||||
# - all
|
||||
# rewrites:
|
||||
# - /foo(.*) /$1 break
|
||||
# proxy_pass_request_body: off
|
||||
# allows:
|
||||
# - 192.168.1.0/24
|
||||
# denies:
|
||||
# - all
|
||||
proxy_set_header:
|
||||
header_host:
|
||||
name: Host
|
||||
@ -178,18 +178,18 @@ nginx_http_template:
|
||||
header_x_forwarded_proto:
|
||||
name: X-Forwarded-Proto
|
||||
value: $scheme
|
||||
#header_upgrade:
|
||||
#name: Upgrade
|
||||
#value: $http_upgrade
|
||||
#header_connection:
|
||||
#name: Connection
|
||||
#value: "Upgrade"
|
||||
#header_random:
|
||||
#name: RandomName
|
||||
#value: RandomValue
|
||||
#internal: false
|
||||
#proxy_store: off
|
||||
#proxy_store_acccess: user:rw
|
||||
# header_upgrade:
|
||||
# name: Upgrade
|
||||
# value: $http_upgrade
|
||||
# header_connection:
|
||||
# name: Connection
|
||||
# value: "Upgrade"
|
||||
# header_random:
|
||||
# name: RandomName
|
||||
# value: RandomValue
|
||||
# internal: false
|
||||
# proxy_store: off
|
||||
# proxy_store_acccess: user:rw
|
||||
proxy_read_timeout: null
|
||||
proxy_send_timeout: null
|
||||
proxy_ssl:
|
||||
@ -227,15 +227,15 @@ nginx_http_template:
|
||||
auth_basic: null
|
||||
auth_basic_user_file: null
|
||||
try_files: $uri $uri/index.html $uri.html =404
|
||||
#auth_request: /auth
|
||||
#auth_request_set:
|
||||
#name: $auth_user
|
||||
#value: $upstream_http_x_user
|
||||
#returns:
|
||||
#return302:
|
||||
#code: 302
|
||||
#url: https://sso.somehost.local/?url=https://$http_host$request_uri
|
||||
#custom_options: []
|
||||
# auth_request: /auth
|
||||
# auth_request_set:
|
||||
# name: $auth_user
|
||||
# value: $upstream_http_x_user
|
||||
# returns:
|
||||
# return302:
|
||||
# code: 302
|
||||
# url: https://sso.somehost.local/?url=https://$http_host$request_uri
|
||||
# custom_options: []
|
||||
health_check_plus: false
|
||||
returns:
|
||||
return301:
|
||||
@ -280,8 +280,8 @@ nginx_http_template:
|
||||
port: 8081
|
||||
weight: 1
|
||||
health_check: max_fails=1 fail_timeout=10s
|
||||
#custom_options: []
|
||||
#custom_options: []
|
||||
# custom_options: []
|
||||
# custom_options: []
|
||||
|
||||
# Enable NGINX status data.
|
||||
# Will enable 'stub_status' in NGINX Open Source and 'status' in NGINX Plus.
|
||||
@ -330,7 +330,7 @@ nginx_stream_template:
|
||||
verify_depth: 1
|
||||
session_reuse: true
|
||||
health_check_plus: false
|
||||
#custom_options: []
|
||||
# custom_options: []
|
||||
upstreams:
|
||||
upstream1:
|
||||
name: backend
|
||||
@ -344,5 +344,5 @@ nginx_stream_template:
|
||||
port: 8080
|
||||
weight: 1
|
||||
health_check: max_fails=1 fail_timeout=10s
|
||||
#custom_options: []
|
||||
#custom_options: []
|
||||
# custom_options: []
|
||||
# custom_options: []
|
||||
|
Loading…
Reference in New Issue
Block a user