{"id":13646959,"url":"https://github.com/jdauphant/ansible-role-nginx","last_synced_at":"2025-12-29T23:24:31.782Z","repository":{"id":13415346,"uuid":"16103903","full_name":"jdauphant/ansible-role-nginx","owner":"jdauphant","description":"Ansible role to install and manage nginx configuration","archived":true,"fork":false,"pushed_at":"2024-03-07T11:12:54.000Z","size":199,"stargazers_count":655,"open_issues_count":22,"forks_count":302,"subscribers_count":29,"default_branch":"master","last_synced_at":"2024-12-17T11:44:24.364Z","etag":null,"topics":["ansible","ansible-role","nginx"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdauphant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-01-21T13:55:42.000Z","updated_at":"2024-09-17T15:17:01.000Z","dependencies_parsed_at":"2024-08-02T01:25:18.959Z","dependency_job_id":"af4bd119-c11d-47ab-bb70-0f6ff426aea1","html_url":"https://github.com/jdauphant/ansible-role-nginx","commit_stats":null,"previous_names":[],"tags_count":88,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdauphant%2Fansible-role-nginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdauphant%2Fansible-role-nginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdauphant%2Fansible-role-nginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdauphant%2Fansible-role-nginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdauphant","download_url":"https://codeload.github.com/jdauphant/ansible-role-nginx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235399012,"owners_count":18983814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-role","nginx"],"created_at":"2024-08-02T01:03:16.761Z","updated_at":"2025-10-05T13:30:32.320Z","avatar_url":"https://github.com/jdauphant.png","language":"Jinja","funding_links":[],"categories":["Roles","nginx","Automation","Others","Jinja"],"sub_categories":["Ansible"],"readme":"nginx\n=====\n\nThis role installs and configures the nginx web server. The user can specify\nany http configuration parameters they wish to apply their site. Any number of\nsites can be added with configurations of your choice.\n\n[![Build Status](https://travis-ci.org/jdauphant/ansible-role-nginx.svg?branch=master)](https://travis-ci.org/jdauphant/ansible-role-nginx)\n[![Ansible Galaxy](https://img.shields.io/ansible/role/466.svg)](https://galaxy.ansible.com/jdauphant/nginx/)\n\nRequirements\n------------\n\nThis role requires Ansible 2.4 or higher and platform requirements are listed\nin the metadata file. (Some older version of the role support Ansible 1.4)\nFor FreeBSD a working pkgng setup is required (see: https://www.freebsd.org/doc/handbook/pkgng-intro.html )\nInstallation of Nginx Amplify agent is only supported on CentOS, RedHat, Amazon, Debian and Ubuntu distributions.\n\nInstall\n-------\n\n```sh\nansible-galaxy install jdauphant.nginx\n```\n\nRole Variables\n--------------\n\nThe variables that can be passed to this role and a brief description about\nthem are as follows. (For all variables, take a look at [defaults/main.yml](defaults/main.yml))\n\n```yaml\n# The user to run nginx\nnginx_user: \"www-data\"\n\n# A list of directives for the events section.\nnginx_events_params:\n - worker_connections 512\n - debug_connection 127.0.0.1\n - use epoll\n - multi_accept on\n\n# A list of hashes that define the servers for nginx,\n# as with http parameters. Any valid server parameters\n# can be defined here.\nnginx_sites:\n default:\n     - listen 80\n     - server_name _\n     - root \"/usr/share/nginx/html\"\n     - index index.html\n foo:\n     - listen 8080\n     - server_name localhost\n     - root \"/tmp/site1\"\n     - location / { try_files $uri $uri/ /index.html; }\n     - location /images/ { try_files $uri $uri/ /index.html; }\n bar:\n     - listen 9090\n     - server_name ansible\n     - root \"/tmp/site2\"\n     - location / { try_files $uri $uri/ /index.html; }\n     - location /images/ {\n         try_files $uri $uri/ /index.html;\n         allow 127.0.0.1;\n         deny all;\n       }\n\n# A list of hashes that define additional configuration\nnginx_configs:\n  proxy:\n      - proxy_set_header X-Real-IP  $remote_addr\n      - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for\n  upstream:\n      - upstream foo { server 127.0.0.1:8080 weight=10; }\n  geo:\n      - geo $local {\n          default 0;\n          127.0.0.1 1;\n        }\n  gzip:\n      - gzip on\n      - gzip_disable msie6\n\n# A list of hashes that define configuration snippets\nnginx_snippets:\n  error_pages:\n    - error_page 500 /http_errors/500.html\n    - error_page 502 /http_errors/502.html\n    - error_page 503 /http_errors/503.html\n    - error_page 504 /http_errors/504.html\n\n# A list of hashes that define user/password files\nnginx_auth_basic_files:\n   demo:\n     - foo:$apr1$mEJqnFmy$zioG2q1iDWvRxbHuNepIh0 # foo:demo , generated by : htpasswd -nb foo demo\n     - bar:$apr1$H2GihkSo$PwBeV8cVWFFQlnAJtvVCQ. # bar:demo , generated by : htpasswd -nb bar demo\n\n# Enable Real IP for CloudFlare requests\nnginx_set_real_ip_from_cloudflare: True\n\n# Enable Nginx Amplify\nnginx_amplify: true\nnginx_amplify_api_key: \"your_api_key_goes_here\"\nnginx_amplify_update_agent: true\n\n# Define modules to enable in configuration\n#\n# Nginx installed via EPEL and APT repos will also install some modules automatically.\n# For official Nginx repo use you will need to install module packages manually.\n#\n# When using with EPEL and APT repos, specify this section as a list of configuration\n# file names, minus the .conf file name extension.\n\n# When using the official Nginx repo, specify this section as list of module file\n# names, minus the .so file name extension.\n#\n# Available module config files in EPEL and APT repos:\n# (APT actually has several more, see https://wiki.debian.org/Nginx/)\n# - mod-http-geoip\n# - mod-http-image-filter\n# - mod-http-perl\n# - mod-http-xslt-filter\n# - mod-mail\n# - mod-stream\n#\n# Available module filenames in Official NGINX repo:\n# - ngx_http_geoip_module\n# - ngx_http_image_filter_module\n# - ngx_http_perl_module\n# - ngx_http_xslt_filter_module\n# - ngx_http_js_module\n#\n# Custom compiled modules are ok too if the .so file exists in same location as a packaged module would be:\n# - ngx_http_modsecurity_module\n#\nnginx_module_configs:\n  - mod-http-geoip\n```\n\nExamples\n========\n\n## 1) Install nginx with HTTP directives of choice, but with no sites configured and no additional configuration:\n\n```yaml\n- hosts: all\n  roles:\n  - {role: nginx,\n     nginx_http_params: [\"sendfile on\", \"access_log /var/log/nginx/access.log\"]\n                          }\n```\n\n## 2) Install nginx with different HTTP directives than in the previous example, but no\nsites configured and no additional configuration.\n\n```yaml\n- hosts: all\n  roles:\n  - {role: nginx,\n     nginx_http_params: [\"tcp_nodelay on\", \"error_log /var/log/nginx/error.log\"]}\n```\n\nNote: Please make sure the HTTP directives passed are valid, as this role\nwon't check for the validity of the directives. See the nginx documentation\nfor details.\n\n## 3) Install nginx and add a site to the configuration.\n\n```yaml\n- hosts: all\n\n  roles:\n  - role: nginx\n    nginx_http_params:\n      - sendfile \"on\"\n      - access_log \"/var/log/nginx/access.log\"\n    nginx_sites:\n      bar:\n        - listen 8080\n        - location / { try_files $uri $uri/ /index.html; }\n        - location /images/ { try_files $uri $uri/ /index.html; }\n    nginx_configs:\n      proxy:\n        - proxy_set_header X-Real-IP  $remote_addr\n        - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for\n```\n\n## 4) Install nginx and add extra variables to default config\n\n```yaml\n-hosts: all\n  vars:\n    - my_extra_params:\n      - client_max_body_size 200M\n# retain defaults and add additional `client_max_body_size` param\n  roles:\n    - role: jdauphant.nginx\n      nginx_http_params: \"{{ nginx_http_default_params + my_extra_params }}\"\n```\n\nNote: Each site added is represented by a list of hashes, and the configurations\ngenerated are populated in /etc/nginx/site-available/ and linked from /etc/nginx/site-enable/ to /etc/nginx/site-available.\n\nThe file name for the specific site configuration is specified in the hash\nwith the key \"file_name\", any valid server directives can be added to the hash.\nAdditional configurations are created in /etc/nginx/conf.d/\n\n## 5) Install Nginx, add 2 sites (different method) and add additional configuration\n\n```yaml\n---\n- hosts: all\n  roles:\n    - role: nginx\n      nginx_http_params:\n        - sendfile on\n        - access_log /var/log/nginx/access.log\n      nginx_sites:\n         foo:\n           - listen 8080\n           - server_name localhost\n           - root /tmp/site1\n           - location / { try_files $uri $uri/ /index.html; }\n           - location /images/ { try_files $uri $uri/ /index.html; }\n         bar:\n           - listen 9090\n           - server_name ansible\n           - root /tmp/site2\n           - location / { try_files $uri $uri/ /index.html; }\n           - location /images/ { try_files $uri $uri/ /index.html; }\n      nginx_configs:\n         proxy:\n            - proxy_set_header X-Real-IP  $remote_addr\n            - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for\n```\n\n## 6) Install Nginx, add 2 sites, add additional configuration and an upstream configuration block\n\n```yaml\n---\n- hosts: all\n  roles:\n    - role: nginx\n      nginx_error_log_level: info\n      nginx_http_params:\n        - sendfile on\n        - access_log /var/log/nginx/access.log\n      nginx_sites:\n        foo:\n           - listen 8080\n           - server_name localhost\n           - root /tmp/site1\n           - location / { try_files $uri $uri/ /index.html; }\n           - location /images/ { try_files $uri $uri/ /index.html; }\n        bar:\n           - listen 9090\n           - server_name ansible\n           - root /tmp/site2\n           - if ( $host = example.com ) { rewrite ^(.*)$ http://www.example.com$1 permanent; }\n           - location / {\n             try_files $uri $uri/ /index.html;\n             auth_basic            \"Restricted\";\n             auth_basic_user_file  auth_basic/demo;\n           }\n           - location /images/ { try_files $uri $uri/ /index.html; }\n      nginx_configs:\n        proxy:\n            - proxy_set_header X-Real-IP  $remote_addr\n            - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for\n        upstream:\n            # Results in:\n            # upstream foo_backend {\n            #   server 127.0.0.1:8080 weight=10;\n            # }\n            - upstream foo_backend { server 127.0.0.1:8080 weight=10; }\n      nginx_auth_basic_files:\n        demo:\n           - foo:$apr1$mEJqnFmy$zioG2q1iDWvRxbHuNepIh0 # foo:demo , generated by : htpasswd -nb foo demo\n           - bar:$apr1$H2GihkSo$PwBeV8cVWFFQlnAJtvVCQ. # bar:demo , generated by : htpasswd -nb bar demo\n```\n\n## 7) Install Nginx, add a site and use special yaml syntax to make the location blocks multiline for clarity\n\n```yaml\n---\n- hosts: all\n  roles:\n    - role: nginx\n      nginx_http_params:\n        - sendfile on\n        - access_log /var/log/nginx/access.log\n      nginx_sites:\n        foo:\n           - listen 443 ssl\n           - server_name foo.example.com\n           - set $myhost foo.example.com\n           - |\n             location / {\n               proxy_set_header Host foo.example.com;\n             }\n           - |\n             location ~ /v2/users/.+?/organizations {\n               if ($request_method = PUT) {\n                 set $myhost bar.example.com;\n               }\n               if ($request_method = DELETE) {\n                 set $myhost bar.example.com;\n               }\n               proxy_set_header Host $myhost;\n             }\n```\n## 8) Example to use this role with my ssl-certs role to generate or copy ssl certificate ( https://galaxy.ansible.com/jdauphant/ssl-certs )\n```yaml\n - hosts: all\n   roles:\n     - jdauphant.ssl-certs\n     - role: jdauphant.nginx\n       nginx_configs:\n          ssl:\n               - ssl_certificate_key {{ssl_certs_privkey_path}}\n               - ssl_certificate     {{ssl_certs_cert_path}}\n       nginx_sites:\n          default:\n               - listen 443 ssl\n               - server_name _\n               - root \"/usr/share/nginx/html\"\n               - index index.html\n```\n## 9) Site configuration using a custom template.\nInstead of defining a site config file using a list of attributes,\nyou may use a hash/dictionary that includes the filename of an alternate template.\nAdditional values are accessible within the template via the `item.value` variable.\n```yaml\n- hosts: all\n\n  roles:\n  - role: nginx\n    nginx_sites:\n      custom_bar:\n        template: custom_bar.conf.j2\n        server_name: custom_bar.example.com\n```\nCustom template: custom_bar.conf.j2:\n```handlebars\n# {{ ansible_managed }}\nupstream backend {\n  server 10.0.0.101;\n}\nserver {\n  server_name {{ item.value.server_name }};\n  location / {\n    proxy_pass http://backend;\n  }\n}\n```\nUsing a custom template allows for unlimited flexibility in configuring the site config file.\nThis example demonstrates the common practice of configuring a site server block\nin the same file as its complementary upstream block.\nIf you use this option:\n* _The hash **must** include a `template:` value, or the configuration task will fail._\n* _This role cannot check tha validity of your custom template.\nIf you use this method, the conf file formatting provided by this role is unavailable,\nand it is up to you to provide a template with valid content and formatting for NGINX._\n\n## 10) Install Nginx, add 2 sites, use snippets to configure access controls\n```yaml\n---\n- hosts: all\n  roles:\n    - role: nginx\n      nginx_http_params:\n        - sendfile on\n        - access_log /var/log/nginx/access.log\n      nginx_snippets:\n        accesslist_devel:\n          - allow 192.168.0.0/24\n          - deny all\n      nginx_sites:\n        foo:\n           - listen 8080\n           - server_name localhost\n           - root /tmp/site1\n           - include snippets/accesslist_devel.conf\n           - location / { try_files $uri $uri/ /index.html; }\n           - location /images/ { try_files $uri $uri/ /index.html; }\n        bar:\n           - listen 9090\n           - server_name ansible\n           - root /tmp/site2\n           - location / { try_files $uri $uri/ /index.html; }\n           - location /images/ { try_files $uri $uri/ /index.html; }\n```\n\nDependencies\n------------\n\nNone\n\nLicense\n-------\nBSD\n\nAuthor Information\n------------------\n\n- Original : Benno Joy\n- Modified by : DAUPHANT Julien\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdauphant%2Fansible-role-nginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdauphant%2Fansible-role-nginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdauphant%2Fansible-role-nginx/lists"}