{"id":13448407,"url":"https://github.com/voxpupuli/puppet-nginx","last_synced_at":"2025-12-17T22:29:26.449Z","repository":{"id":37579821,"uuid":"1791219","full_name":"voxpupuli/puppet-nginx","owner":"voxpupuli","description":"Puppet Module to manage NGINX on various UNIXes","archived":false,"fork":false,"pushed_at":"2025-03-19T19:10:02.000Z","size":3164,"stargazers_count":472,"open_issues_count":125,"forks_count":876,"subscribers_count":79,"default_branch":"master","last_synced_at":"2025-04-03T10:22:10.211Z","etag":null,"topics":["archlinux-puppet-module","bsd-puppet-module","centos-puppet-module","debian-puppet-module","freebsd-puppet-module","hacktoberfest","linux-puppet-module","nginx","openbsd-puppet-module","puppet","redhat-puppet-module","sles-puppet-module","ubuntu-puppet-module"],"latest_commit_sha":null,"homepage":"https://forge.puppet.com/puppet/nginx","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voxpupuli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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},"funding":{"open_collective":"vox-pupuli","github":"voxpupuli"}},"created_at":"2011-05-24T01:53:48.000Z","updated_at":"2025-03-01T16:40:40.000Z","dependencies_parsed_at":"2023-12-15T04:03:25.357Z","dependency_job_id":"3aaa4f34-b4b9-411a-a5da-2493ef2c320c","html_url":"https://github.com/voxpupuli/puppet-nginx","commit_stats":{"total_commits":1430,"total_committers":368,"mean_commits":3.885869565217391,"dds":0.8587412587412587,"last_synced_commit":"071c48d4f8d20d2adbc4282588d9a0246182737d"},"previous_names":["jfryman/puppet-nginx"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-nginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-nginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-nginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-nginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voxpupuli","download_url":"https://codeload.github.com/voxpupuli/puppet-nginx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247392122,"owners_count":20931726,"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":["archlinux-puppet-module","bsd-puppet-module","centos-puppet-module","debian-puppet-module","freebsd-puppet-module","hacktoberfest","linux-puppet-module","nginx","openbsd-puppet-module","puppet","redhat-puppet-module","sles-puppet-module","ubuntu-puppet-module"],"created_at":"2024-07-31T05:01:44.686Z","updated_at":"2025-12-17T22:29:26.431Z","avatar_url":"https://github.com/voxpupuli.png","language":"Ruby","funding_links":["https://opencollective.com/vox-pupuli","https://github.com/sponsors/voxpupuli"],"categories":["Ruby"],"sub_categories":[],"readme":"# NGINX module for Puppet\n\n[![Build Status](https://github.com/voxpupuli/puppet-nginx/workflows/CI/badge.svg)](https://github.com/voxpupuli/puppet-nginx/actions?query=workflow%3ACI)\n[![Code Coverage](https://coveralls.io/repos/github/voxpupuli/puppet-nginx/badge.svg?branch=master)](https://coveralls.io/github/voxpupuli/puppet-nginx)\n[![Puppet Forge](https://img.shields.io/puppetforge/v/puppet/nginx.svg)](https://forge.puppetlabs.com/puppet/nginx)\n[![Puppet Forge - downloads](https://img.shields.io/puppetforge/dt/puppet/nginx.svg)](https://forge.puppetlabs.com/puppet/nginx)\n[![Puppet Forge - endorsement](https://img.shields.io/puppetforge/e/puppet/nginx.svg)](https://forge.puppetlabs.com/puppet/nginx)\n[![Puppet Forge - scores](https://img.shields.io/puppetforge/f/puppet/nginx.svg)](https://forge.puppetlabs.com/puppet/nginx)\n\nThis module was migrated from James Fryman \u003cjames@frymanet.com\u003e to Vox Pupuli.\n\n## INSTALLING OR UPGRADING\n\nThis module manages NGINX configuration.\n\n### Requirements\n\n* Puppet 4.6.1 or later.  Puppet 3 was supported up until release 0.6.0.\n* apt is now a soft dependency. If your system uses apt, you'll need to\n  configure an appropriate version of the apt module. Version 9.2.0 or higher is\n  recommended because of supporting \"modern keyrings\".\n\n### Additional Documentation\n\n* [A Quickstart Guide to the NGINX Puppet Module](https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md)\n\n### Install and bootstrap an NGINX instance\n\n```puppet\ninclude nginx\n```\n\n### A simple reverse proxy\n\n```puppet\nnginx::resource::server { 'kibana.myhost.com':\n  listen_port =\u003e 80,\n  proxy       =\u003e 'http://localhost:5601',\n}\n```\n\n### A virtual host with static content\n\n```puppet\nnginx::resource::server { 'www.puppetlabs.com':\n  www_root =\u003e '/var/www/www.puppetlabs.com',\n}\n```\n\n### A more complex proxy example\n\n```puppet\nnginx::resource::upstream { 'puppet_rack_app':\n  members =\u003e {\n    'localhost:3000' =\u003e {\n      server =\u003e 'localhost',\n      port   =\u003e 3000,\n      weight =\u003e 1,\n    },\n    'localhost:3001' =\u003e {\n      server =\u003e 'localhost',\n      port   =\u003e 3001,\n      weight =\u003e 1,\n    },\n    'localhost:3002' =\u003e {\n      server =\u003e 'localhost',\n      port   =\u003e 3002,\n      weight =\u003e 2,\n      },\n  },\n}\n\nnginx::resource::server { 'rack.puppetlabs.com':\n  proxy =\u003e 'http://puppet_rack_app',\n}\n```\n\n### Add a smtp proxy\n\n```puppet\nclass { 'nginx':\n  mail =\u003e true,\n}\n\nnginx::resource::mailhost { 'domain1.example':\n  auth_http       =\u003e 'server2.example/cgi-bin/auth',\n  protocol        =\u003e 'smtp',\n  listen_port     =\u003e 587,\n  ssl_port        =\u003e 465,\n  starttls        =\u003e 'only',\n  xclient         =\u003e 'off',\n  proxy_protocol  =\u003e 'off',\n  proxy_smtp_auth =\u003e 'off',\n  ssl             =\u003e true,\n  ssl_cert        =\u003e '/tmp/server.crt',\n  ssl_key         =\u003e '/tmp/server.pem',\n}\n```\n\n### Convert upstream members from Array to Hash\n\nThe datatype Array for members of a nginx::resource::upstream is replaced by a\nHash. The following configuration is no longer valid:\n\n```puppet\nnginx::resource::upstream { 'puppet_rack_app':\n  members =\u003e {\n    'localhost:3000',\n    'localhost:3001',\n    'localhost:3002',\n  },\n}\n```\n\nFrom now on, the configuration must look like this:\n\n```puppet\nnginx::resource::upstream { 'puppet_rack_app':\n  members =\u003e {\n    'localhost:3000' =\u003e {\n      server =\u003e 'localhost',\n      port   =\u003e 3000,\n    },\n    'localhost:3001' =\u003e {\n      server =\u003e 'localhost',\n      port   =\u003e 3001,\n    },\n    'localhost:3002' =\u003e {\n      server =\u003e 'localhost',\n      port   =\u003e 3002,\n    },\n  },\n}\n```\n\n## SSL configuration\n\nBy default, creating a server resource will only create a HTTP server. To also\ncreate a HTTPS (SSL-enabled) server, set `ssl =\u003e true` on the server. You will\nhave a HTTP server listening on `listen_port` (port `80` by default) and a HTTPS\nserver listening on `ssl_port` (port `443` by default). Both servers will have\nthe same `server_name` and a similar configuration.\n\nTo create only a HTTPS server, set `ssl =\u003e true` and also set `listen_port` to the\nsame value as `ssl_port`. Setting these to the same value disables the HTTP server.\nThe resulting server will be listening on `ssl_port`.\n\n### Idempotency with nginx 1.15.0 and later\n\nBy default, this module might configure the deprecated `ssl on` directive.  When\nyou next run puppet, this will be removed since the `nginx_version` fact will now\nbe available. To avoid this idempotency issue, you can manually set the base\nclass's `nginx_version` parameter.\n\n### Locations\n\nLocations require specific settings depending on whether they should be included\nin the HTTP, HTTPS or both servers.\n\n#### HTTP only server (default)\n\nIf you only have a HTTP server (i.e. `ssl =\u003e false` on the server) make sure you\ndon't set `ssl =\u003e true` on any location you associate with the server.\n\n#### HTTP and HTTPS server\n\nIf you set `ssl =\u003e true` and also set `listen_port` and `ssl_port` to different\nvalues on the server you will need to be specific with the location settings since\nyou will have a HTTP server listening on `listen_port` and a HTTPS server listening\non `ssl_port`:\n\n* To add a location to only the HTTP server, set `ssl =\u003e false` on the location\n  (this is the default).\n* To add a location to both the HTTP and HTTPS server, set `ssl =\u003e true` on the\n  location, and ensure `ssl_only =\u003e false` (which is the default value for `ssl_only`).\n* To add a location only to the HTTPS server, set both `ssl =\u003e true`\n  and `ssl_only =\u003e true` on the location.\n\n#### HTTPS only server\n\nIf you have set `ssl =\u003e true` and also set `listen_port` and `ssl_port` to the\nsame value on the server, you will have a single HTTPS server listening on\n`ssl_port`. To add a location to this server set `ssl =\u003e true` and\n`ssl_only =\u003e true` on the location.\n\n## Hiera Support\n\nDefining nginx resources in Hiera.\n\n```yaml\nnginx::nginx_upstreams:\n  'puppet_rack_app':\n    ensure: present\n    members:\n      'localhost:3000':\n        server: 'localhost'\n        port: 3000\n      'localhost:3001':\n        server: 'localhost'\n        port: 3001\n      'localhost:3002':\n        server: 'localhost'\n        port: 3002\nnginx::nginx_servers:\n  'www.puppetlabs.com':\n    www_root: '/var/www/www.puppetlabs.com'\n  'rack.puppetlabs.com':\n    proxy: 'http://puppet_rack_app'\nnginx::nginx_locations:\n  'static':\n    location: '~ \"^/static/[0-9a-fA-F]{8}\\/(.*)$\"'\n    server: www.puppetlabs.com\n    www_root: /var/www/html\n  'userContent':\n    location: /userContent\n    server: www.puppetlabs.com\n    www_root: /var/www/html\nnginx::nginx_mailhosts:\n  'smtp':\n    auth_http: server2.example/cgi-bin/auth\n    protocol: smtp\n    listen_port: 587\n    ssl_port: 465\n    starttls: only\n```\n\n### A stream syslog UDP proxy\n\n```yaml\n\nnginx::stream: true\n\nnginx::nginx_cfg_prepend:\n  include:\n    - '/etc/nginx/modules-enabled/*.conf'\n\nnginx::nginx_streamhosts:\n  'syslog':\n    ensure:                 'present'\n    listen_port:            514\n    listen_options:         'udp'\n    proxy:                  'syslog'\n    proxy_read_timeout:     '1'\n    proxy_connect_timeout:  '1'\n    raw_append:\n      - 'error_log off;'\n\nnginx::nginx_upstreams:\n  'syslog':\n    context: 'stream'\n    members:\n      '10.0.0.1:514':\n        server: '10.0.0.1'\n        port: 514\n      '10.0.0.2:514':\n        server: '10.0.0.2'\n        port: 514\n      '10.0.0.3:514':\n        server: '10.0.0.3'\n        port: 514\n```\n\n## Nginx with precompiled Passenger\n\nExample configuration for Debian and RHEL / CentOS (\u003e6), pulling the Nginx and\nPassenger packages from the Phusion repo. See additional notes in\n[https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md](https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md)\n\n```puppet\nclass { 'nginx':\n  package_source  =\u003e 'passenger',\n  http_cfg_append =\u003e {\n    'passenger_root' =\u003e '/usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini',\n  }\n}\n```\n\nHere the example for OpenBSD:\n\n```puppet\nclass { 'nginx':\n  package_flavor =\u003e 'passenger',\n  service_flags  =\u003e '-u'\n  http_cfg_append =\u003e {\n    passenger_root          =\u003e '/usr/local/lib/ruby/gems/2.1/gems/passenger-4.0.44',\n    passenger_ruby          =\u003e  '/usr/local/bin/ruby21',\n    passenger_max_pool_size =\u003e '15',\n  }\n}\n```\n\nPackage source `passenger` will add [Phusion Passenger repository](https://oss-binaries.phusionpassenger.com/apt/passenger)\nto APT sources. For each virtual host you should specify which ruby should be used.\n\n```puppet\nnginx::resource::server { 'www.puppetlabs.com':\n  www_root          =\u003e '/var/www/www.puppetlabs.com',\n  server_cfg_append =\u003e {\n    'passenger_enabled' =\u003e 'on',\n    'passenger_ruby'    =\u003e '/usr/bin/ruby',\n  }\n}\n```\n\n### Puppet master served by Nginx and Passenger\n\nVirtual host config for serving puppet master:\n\n```puppet\nnginx::resource::server { 'puppet':\n  ensure               =\u003e present,\n  server_name          =\u003e ['puppet'],\n  listen_port          =\u003e 8140,\n  ssl                  =\u003e true,\n  ssl_cert             =\u003e '/var/lib/puppet/ssl/certs/example.com.pem',\n  ssl_key              =\u003e '/var/lib/puppet/ssl/private_keys/example.com.pem',\n  ssl_port             =\u003e 8140,\n  server_cfg_append    =\u003e {\n    'passenger_enabled'      =\u003e 'on',\n    'passenger_ruby'         =\u003e '/usr/bin/ruby',\n    'ssl_crl'                =\u003e '/var/lib/puppet/ssl/ca/ca_crl.pem',\n    'ssl_client_certificate' =\u003e '/var/lib/puppet/ssl/certs/ca.pem',\n    'ssl_verify_client'      =\u003e 'optional',\n    'ssl_verify_depth'       =\u003e 1,\n  },\n  www_root             =\u003e '/etc/puppet/rack/public',\n  use_default_location =\u003e false,\n  access_log           =\u003e '/var/log/nginx/puppet_access.log',\n  error_log            =\u003e '/var/log/nginx/puppet_error.log',\n  passenger_cgi_param  =\u003e {\n    'HTTP_X_CLIENT_DN'     =\u003e '$ssl_client_s_dn',\n    'HTTP_X_CLIENT_VERIFY' =\u003e '$ssl_client_verify',\n  },\n}\n```\n\n### Example puppet class calling nginx::server with HTTPS FastCGI and redirection of HTTP\n\n```puppet\n\n$full_web_path = '/var/www'\n\ndefine web::nginx_ssl_with_redirect (\n  $backend_port         = 9000,\n  $php                  = true,\n  $proxy                = undef,\n  $www_root             = \"${full_web_path}/${name}/\",\n  $location_cfg_append  = undef,\n) {\n  nginx::resource::server { \"${name}.${facts['networking']['domain']}\":\n    ensure              =\u003e present,\n    www_root            =\u003e \"${full_web_path}/${name}/\",\n    location_cfg_append =\u003e {\n      'rewrite' =\u003e '^ https://$server_name$request_uri? permanent'\n    }‚,\n  }\n\n  if !$www_root {\n    $tmp_www_root = undef\n  } else {\n    $tmp_www_root = $www_root\n  }\n\n  nginx::resource::server { \"${name}.${facts['networking']['domain']} ${name}\":\n    ensure                =\u003e present,\n    listen_port           =\u003e 443,\n    www_root              =\u003e $tmp_www_root,\n    proxy                 =\u003e $proxy,\n    location_cfg_append   =\u003e $location_cfg_append,\n    index_files           =\u003e [ 'index.php' ],\n    ssl                   =\u003e true,\n    ssl_cert              =\u003e '/path/to/wildcard_mydomain.crt',\n    ssl_key               =\u003e '/path/to/wildcard_mydomain.key',\n  }\n\n\n  if $php {\n    nginx::resource::location { \"${name}_root\":\n      ensure          =\u003e present,\n      ssl             =\u003e true,\n      ssl_only        =\u003e true,\n      server           =\u003e \"${name}.${facts['networking']['domain']} ${name}\",\n      www_root        =\u003e \"${full_web_path}/${name}/\",\n      location        =\u003e '~ \\.php$',\n      index_files     =\u003e ['index.php', 'index.html', 'index.htm'],\n      proxy           =\u003e undef,\n      fastcgi         =\u003e \"127.0.0.1:${backend_port}\",\n      fastcgi_script  =\u003e undef,\n      location_cfg_append =\u003e {\n        fastcgi_connect_timeout =\u003e '3m',\n        fastcgi_read_timeout    =\u003e '3m',\n        fastcgi_send_timeout    =\u003e '3m'\n      }\n    }\n  }\n}\n```\n\n## Add custom fastcgi_params\n\n```puppet\nnginx::resource::location { \"some_root\":\n  ensure         =\u003e present,\n  location       =\u003e '/some/url',\n  fastcgi        =\u003e \"127.0.0.1:9000\",\n  fastcgi_param  =\u003e {\n    'APP_ENV' =\u003e 'local',\n  },\n}\n```\n\n## Call class web::nginx_ssl_with_redirect\n\n```puppet\nweb::nginx_ssl_with_redirect { 'sub-domain-name':\n    backend_port =\u003e 9001,\n  }\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Fpuppet-nginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoxpupuli%2Fpuppet-nginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Fpuppet-nginx/lists"}