{"id":29702606,"url":"https://github.com/devgateway/ansible-role-nginx","last_synced_at":"2026-04-14T04:02:43.895Z","repository":{"id":78413105,"uuid":"122389882","full_name":"devgateway/ansible-role-nginx","owner":"devgateway","description":"Configure Nginx web server or sites","archived":false,"fork":false,"pushed_at":"2019-08-02T20:06:33.000Z","size":113,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-23T13:00:10.558Z","etag":null,"topics":["ansible","ansible-role","jinja2","nginx","nginx-configuration"],"latest_commit_sha":null,"homepage":"","language":"Python","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/devgateway.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,"zenodo":null}},"created_at":"2018-02-21T20:30:57.000Z","updated_at":"2023-05-24T09:51:43.000Z","dependencies_parsed_at":"2023-03-20T18:05:24.289Z","dependency_job_id":null,"html_url":"https://github.com/devgateway/ansible-role-nginx","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/devgateway/ansible-role-nginx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgateway%2Fansible-role-nginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgateway%2Fansible-role-nginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgateway%2Fansible-role-nginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgateway%2Fansible-role-nginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devgateway","download_url":"https://codeload.github.com/devgateway/ansible-role-nginx/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devgateway%2Fansible-role-nginx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31781292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","jinja2","nginx","nginx-configuration"],"created_at":"2025-07-23T12:39:45.042Z","updated_at":"2026-04-14T04:02:43.889Z","avatar_url":"https://github.com/devgateway.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# devgateway.nginx\n\nThis is a low-level utility role to configure Nginx daemon *or* an individual site (`server` block\nand related directives).\n\nIn a nutshell, this role translates YAML structures of certain grammar into Nginx grammar. Invoke\nthis role (which knows *how* to generate Nginx syntax) from a higher level role (which knows *what*\nto generate). For example:\n\n    - name: Configure a PHP site\n      include_role:\n        name: devgateway.nginx\n        tasks_from: site\n      vars:\n        site:\n          server: \n            include: fastcgi_params\n            fastcgi_index: index.php\n            server_name: \"{{ server_name }}\"\n            listen: \"{{ ssl | default(true) | ternary(443, 80) }}\"\n            ssl: \"{{ ssl }}\"\n\nThus, this role provides four independent modes:\n\n* Daemon configuration which configures `nginx.conf` using `tasks_from: nginx`.\n\n* Site configuration which configures `conf.d/`*`site`*`.conf` using `tasks_from: site`.\n\n* SSL key pair installation and DH params generation.\n\n## Role Grammar\n\nThe role grammar is based on [Nginx configuration\n*contexts*](http://nginx.org/en/docs/beginners_guide.html#conf_structure). Site and daemon\nconfiguration mode take just one dictionary each, which contains:\n\n* Nginx directives applicable in current context and their values, as described below, and\n* other contexts, potentially nested, with their directives and values.\n\n**Be advised**, that although this role is idempotent, it operates on templates, and thus, on\nentire files, not individual directives. If you manually add a directive to the target file, it\nwill be overwritten.\n\nDictionary members are expanded into Nginx directives, so that the key becomes the directive name,\nand the value - its arguments. Directives, except blocks, are output in alphabetical order. Certain\nkey names are special, those are described below. The following rules are used for the values.\n\n### Scalars\n\n*   **Integers** are printed verbatim.\n\n*   **Strings** get single-quoted if they contain spaces:\n\n        auth_basic: You shall not pass\n\n    becomes:\n\n        auth_basic 'You shall not pass';\n\n*   **Booleans** (except when in `upstream` or `map` blocks) become `on`/`off`:\n\n        ssl: true\n\n    becomes:\n\n        ssl on;\n\n### Lists\n\n*   Simple **lists** become positional arguments, maintaining the given order:\n\n        server_name:\n          - bob.example.org\n          - alice.example.org\n\n    becomes:\n\n        server_name bob.example.org alice.example.org;\n\n*   However, if the first value of a **list** is also a list, only that child list is evaluated. It\nyields multiple directives, with each value expanded as per these rules:\n\n        fastcgi_hide_header:\n          - - X-Drupal-Version\n            - Debian: X-Dpkg\n              RedHat: X-Rpm\n\n    in Debian becomes:\n\n        fastcgi_hide_header X-Drupal-Version;\n        fastcgi_hide_header X-Dpkg;\n\n### Dictionaries\n\n*   If a **dictionary** contains special members `args` (list) or `kwargs` (dictionary), they\nbecome positional and keyworded arguments, respectively. Keyworded arguments get sorted; positional\ndon't. Keyworded arguments that are lists, are joined using a colon:\n\n        proxy_cache_path:\n          args:\n            - /var/cache/nginx/php\n          kwargs:\n            levels:\n              - 1\n              - 2\n            keys_zone:\n              - php\n              - 40m\n            inactive: 14d\n            max_size: 512m\n\n    becomes:\n\n        proxy_cache_path /var/cache/nginx/php inactive=14d keys_zone=php:40m levels=1:2 max_size=512m;\n\n*   If a **dictionary** contains a key which is the same as `ansible_os_family` value, then its\nvalue is expanded further, according to these rules:\n\n        ssl_certificate_key:\n          Debian: /etc/ssl/private/snakeoil.pem\n          RedHat: /etc/pki/tls/certs/snakeoil.pem\n\n    in Debian becomes:\n\n        ssl_certificate_key /etc/ssl/private/snakeoil.pem;\n\n*   Otherwise, a **dictionary** expands to multiple directives, keys becoming the first positional\nargument, and values expanded further as described above:\n\n        access_log:\n          /var/log/nginx/access.log: common\n          /var/log/nginx/detailed.log:\n            args:\n              - longformat\n            kwargs:\n              gzip: 3\n              flush: 1h\n\n    becomes:\n\n        access_log /var/log/nginx/access.log common;\n        access_log /var/log/nginx/detailed.log longformat flush=1h gzip=3;\n\n## Daemon Configuration Mode (`nginx.conf`)\n\nThis mode uses a dictionary called `ngx_settings`. All members are optional contexts:\n\n* `main`\n* `events`\n* `http`\n\nExample:\n\n    ngx_settings:\n      main:\n        user:\n          RedHat: nginx\n          Debian: www-data\n      events:\n        worker_connections: 1024\n      http:\n        sendfile: true\n\n### Optional Variable: `automatic_ssl_redirects`\n\nIf *true*, a `server` block is generated to redirect from plaintext to SSL site. See below for\ndetails.\n\nDefault: *false*\n\n### Optional Variable: `ngx_config_path`\n\nPath to Nginx main configuration file.\n\nDefault: `/etc/nginx/nginx.conf`\n\n## Site Configuration Mode (`conf.d/`*`site`*`.conf`)\n\nThis mode uses a dictionary called `site`. The following members are special:\n\n* `server` is the only required context. This will be referred to hereinafter as the main server.\n\n* `redirect_from` is an optional list of `server_name`'s. If defined, it will yield a `server`\nblock with a redirect to the main server (two server blocks - SSL and plaintext, if the main server\nuses SSL). See Redirect Servers below for details.\n\n* `name` is an optional base name (without extension) of the config file to generate. Use this\nvariable, for instance, if your `server_name` is a regex. Otherwise, the first `server_name` will\nbe used, with the leading dot removed.\n\n* Other recognized contexts are `http`, `maps`, and `upstreams`. Each is described below.\n\n### `http` Context\n\nThese directives appear in the beginning of the file, and belong to the `http` context of Nginx\nconfiguration, where the file is `include`'d.\n\n### `maps` Context\n\nThis context is a list of dictionaries, each representing a [`map`\nblock](http://nginx.org/en/docs/http/ngx_http_map_module.html#map). The following members are\nrecognized in a dictionary:\n\n* `hostnames` and `volatile` - booleans;\n* `default` - scalar;\n* `string` - the first argument of Nginx `map` directive, the string being evaluated;\n* `var` - the second argument, dollar sign before the variable name may be omitted;\n* `map` - dictionary, keys and values of the map.\n\nExample:\n\n    maps:\n      - string: \"$http_user_agent\"\n        var: compatible_browser\n        default: 1\n        map:\n          \"~MSIE\": 0\n          \"~Lynx\": 1\n\n### `upstreams` Context\n\nThis context is a dictionary. Keys are upstream names, values are dictionaries of their directives.\n\nExample:\n\n    upstreams:\n      backend:\n        ip_hash: true\n        server:\n          - - localhost:9001\n            - otherhost:9001\n\n### Redirect Servers\n\nDepending on the main server SSL settings, one or two (SSL-enabled and plaintext) extra `server`\nblocks are generated. Each contains nothing but unconditional permanent redirect to the main\nserver. The logic of main server domain name detection is described below.\n\nAdditionally, if SSL is enabled for the main site and `automatic_ssl_redirects` is *true*, the\nthird `server` block is generated, with the same `server_name` as the main server. This block\ncontains a permanent redirect from plaintext site to SSL.\n\n### Main Server Block\n\nThe main server block may contain an `ifs` member (a list of dictionaries), representing `if`\nblocks. Each of those blocks must contain at least an `if` member - the conditional expression.\n\nExample:\n\n    server:\n      ifs:\n        - if: $http_referer ~ mallory\\.example\\.com\n          return: 403\n\nThe main server block may also contain a `locations` member (also a list of dictionaries). Each of\nthose must contain at least a `location` member (which may also include matching operators like `~`\nor `=`), and may contain nested `locations` members, as well as `ifs`.\n\nExample:\n\n    server:\n      locations:\n        - location: /scripts\n          locations:\n            - location: ~ \\.php$\n              fastcgi_pass: unix:/var/run/php\n\n## Certificate/DH Mode\n\nThis mode uses at least two variables: `ngx_key` and `ngx_cert` which are the private key and the\ncertificate, respectively.\n\n### Optional Variables\n\n* `ngx_keypair_name` sets the base name (without extension) for the key and the certificate, and\ndefaults to *nginx*.\n\n* `ngx_cert_chain` can be either a list of certificates in the chain (from intermediate to root\nCA), or a string with the said chain prebuilt.\n\n* `ngx_dhparam_bits` is the length of DH parameter to generated, default is 2048.\n\n* `ngx_key_dir`, `ngx_cert_dir`, and `ngx_dhparam_path` are dictionaries with `ansible_os_family`\nas keys, and define default directories and filename for the above.\n\nPlaybook example:\n\n    - hosts: webservers\n      tasks:\n        - name: Install key pair\n          import_role:\n            name: devgateway.nginx\n            tasks_from: certificate\n          vars:\n            ngx_keypair_name: snakeoil\n            ngx_key: |-\n              -----BEGIN RSA PRIVATE KEY-----\n              My private key\n              -----END RSA PRIVATE KEY-----\n            ngx_cert: |-\n              -----BEGIN CERTIFICATE-----\n              My certificate\n              -----END CERTIFICATE-----\n            ngx_cert_chain:\n              - |-\n                -----BEGIN CERTIFICATE-----\n                Intermediate vendor\n                -----END CERTIFICATE-----\n              - |-\n                -----BEGIN CERTIFICATE-----\n                Root CA\n                -----END CERTIFICATE-----\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevgateway%2Fansible-role-nginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevgateway%2Fansible-role-nginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevgateway%2Fansible-role-nginx/lists"}