From b5baf3a2ae570d886a6acb6f6d6b9d5eea130e0f Mon Sep 17 00:00:00 2001 From: Alessandro Fael Garcia Date: Fri, 13 Dec 2019 12:11:30 -0800 Subject: [PATCH] Improve documentation (#206) * Create CONTRIBUTING.md * Add PR template * Tweak .yamllint * Update README playbook examples --- .github/pull_request_template.md | 10 +++ .yamllint | 1 - CONTRIBUTING.md | 72 +++++++++++++++ README.md | 55 ++++++++---- defaults/main/template.yml | 146 +++++++++++++++---------------- 5 files changed, 192 insertions(+), 92 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..d2cf8ae --- /dev/null +++ b/.github/pull_request_template.md @@ -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`) diff --git a/.yamllint b/.yamllint index e8f0190..cfab5e4 100644 --- a/.yamllint +++ b/.yamllint @@ -7,7 +7,6 @@ rules: brackets: max-spaces-inside: 1 level: error - comments: disable comments-indentation: disable line-length: disable truthy: disable diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ed7cc1e --- /dev/null +++ b/CONTRIBUTING.md @@ -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 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: + * + * diff --git a/README.md b/README.md index 404efd8..003b92b 100644 --- a/README.md +++ b/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 diff --git a/defaults/main/template.yml b/defaults/main/template.yml index 071bfe1..683c1b1 100644 --- a/defaults/main/template.yml +++ b/defaults/main/template.yml @@ -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: []