{"id":15887820,"url":"https://github.com/pgassmann/puppet-letsencrypt_nginx","last_synced_at":"2025-03-20T08:32:59.333Z","repository":{"id":57666047,"uuid":"55190026","full_name":"pgassmann/puppet-letsencrypt_nginx","owner":"pgassmann","description":"Let's Encrypt nginx helper Puppet Module","archived":false,"fork":false,"pushed_at":"2019-08-16T09:22:27.000Z","size":63,"stargazers_count":3,"open_issues_count":0,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-28T23:51:04.218Z","etag":null,"topics":["certbot","letsencrypt","nginx","puppet","puppet-module"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","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/pgassmann.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-31T23:37:17.000Z","updated_at":"2022-07-30T15:31:53.000Z","dependencies_parsed_at":"2022-09-26T20:31:37.056Z","dependency_job_id":null,"html_url":"https://github.com/pgassmann/puppet-letsencrypt_nginx","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgassmann%2Fpuppet-letsencrypt_nginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgassmann%2Fpuppet-letsencrypt_nginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgassmann%2Fpuppet-letsencrypt_nginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgassmann%2Fpuppet-letsencrypt_nginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pgassmann","download_url":"https://codeload.github.com/pgassmann/puppet-letsencrypt_nginx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244066232,"owners_count":20392406,"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":["certbot","letsencrypt","nginx","puppet","puppet-module"],"created_at":"2024-10-06T06:05:01.908Z","updated_at":"2025-03-20T08:32:58.839Z","avatar_url":"https://github.com/pgassmann.png","language":"Ruby","readme":"[![Build Status](https://travis-ci.org/pgassmann/puppet-letsencrypt_nginx.svg?branch=master)](https://travis-ci.org/pgassmann/puppet-letsencrypt_nginx)\n\n# letsencrypt_nginx\n\n#### Table of Contents\n\n1. [Overview](#overview)\n2. [Module Description - What the module does and why it is useful](#module-description)\n3. [Setup - The basics of getting started with letsencrypt_nginx](#setup)\n4. [Usage - Configuration options and additional functionality](#usage)\n5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [Development - Guide for contributing to the module](#development)\n\n## Overview\n\nThe goal of [Let's Encrypt](https://letsencrypt.org) is to automate ssl certificates.\n\nThis module is a helper to manage letsencrypt for puppet managed nginx servers.\n\nWorks with [puppet/letsencrypt](https://github.com/voxpupuli/puppet-letsencrypt) and [puppet/nginx](https://github.com/voxpupuli/puppet-nginx)\n\n## Module Description\n\nThe goal of this module is to enable ssl on puppet managed nginx servers as\nsimple as possible. The module reuses the domains configured in the server server_name\n\nFor the authorization, the webroot challenge is used and a custom location is\nautomatically added to the ngninx server so that the challenge path is using\nthe letsencrypt webroot.\nThis allows to solve the challenge even if the server is just a proxy to another server.\n\n## Setup\n\n### What letsencrypt_nginx does\n\n* configure locations for the letsencrypt challenge path for defined servers and default server\n* Define default server for nginx that catches all requests that do not match a server_name\n* Uses letsencrypt::certonly to get certificate (requires puppet-letsencrypt)\n* Tell letsencrypt::certonly to manage cron for renewals\n\n### What letsencrypt_nginx does not\n\n* Manage nginx server ssl configuration. Configure the server ssl and certificate as seen  in the examples below.\n\n### Setup Requirements\n\nRequests to Port 80 (and 433) of the IPv4 address of the domains to encrypt need to reach your server.\n\nThis module uses the puppet/letsencrypt module, see it's documentation for the letsencrypt options\n\n### Usage\n\nSee the following example for encrypting a nginx server.\nThis will successfully configure nginx, the server and the ssl certificat in one run, if added to a blank Server.\n\nImportant: You should declare letsencrypt_nginx resources after the nginx resources.\nThe fetching of the configured domains is parse order dependent.\n\n\n#### Let's encrypt nginx server\n\n\n    nginx::resource::server { 'letsencrypt-test1.example.com':\n      server_name      =\u003e [\n        'letsencrypt-test1.example.com',\n        'letsencrypt-test2.example.com',\n      ],\n      proxy            =\u003e 'http://10.1.2.3',\n      ssl              =\u003e true,\n      ssl_redirect =\u003e true,\n      ssl_key          =\u003e '/etc/letsencrypt/live/letsencrypt-test1.example.com/privkey.pem',\n      ssl_cert         =\u003e '/etc/letsencrypt/live/letsencrypt-test1.example.com/fullchain.pem',\n    }\n    class { ::letsencrypt:\n      email =\u003e 'foo@example.com',\n    }\n    class { 'letsencrypt_nginx':\n      firstrun_webroot =\u003e '/var/www/html',\n      servers           =\u003e {\n        'letsencrypt-test1.example.com' =\u003e {},\n      },\n    }\n\nTo add ssl configuration to an existing installation, you need first to configure the locations\nfor your default server and your existing server.\n\n    class { 'letsencrypt_nginx':\n      locations =\u003e {\n        'default' =\u003e {}\n        'letsencrypt-test1.example.com' =\u003e {}\n      }\n    }\n\nIf this is applied successfully, you can then add the ssl configuration to your nginx server as above and declare your letsencrypt_nginx::server\n\n#### Hiera example\n\n    classes:\n      - nginx\n      - letsencrypt\n      - letsencrypt_nginx\n\n    nginx::servers:\n      'letsencrypt-test1.example.com':\n          server_name:\n                                - 'letsencrypt-test1.example.com'\n                                - 'letsencrypt-test2.example.com'\n          proxy:                'http://10.1.2.3'\n          ssl:                  true\n          ssl_redirect:     true\n          ssl_key:              '/etc/letsencrypt/live/letsencrypt-test1.example.com/privkey.pem'\n          ssl_cert:             '/etc/letsencrypt/live/letsencrypt-test1.example.com/fullchain.pem'\n\n    letsencrypt::email: 'foo@example.com'\n    # use staging server for testing\n    letsencrypt::config:\n      server: 'https://acme-staging.api.letsencrypt.org/directory'\n\n    letsencrypt_nginx::firstrun_webroot: '/var/www/html'\n    letsencrypt_nginx::servers:\n      'letsencrypt-test1.example.com': {}\n\n\n## Reference\n\n\n### Class: letsencrypt_nginx\n\nLet's Encrypt base configuration and hiera interface.\n\n#### Parameters\n\n* `default_server_name`:\n  name of nginx server that catches all requests that do not match any other server_name\n\n* `webroot`:\n  This directory is configured as webroot for the webroot authentication\n  locations added to the server to allow renewals\n\n* `firstrun_webroot`:\n  Use different webroot on first run.\n  Set this to the default webroot of the webserver if the service\n  starts automatically when installed.\n  E.g. For Nginx on Ubuntu: /var/www/html\n\n* `firstrun_standalone`:\n  Use standalone mode on first run.\n  Set this to true if the webserver does not start automatically when installed.\n  letsencrypt will use standalone mode to get the certificate\n  before the webserver is started the first time.\n\n* `locations`, `servers`:\n  These Parameters can be used to create instances of these defined types through hiera\n\n\n### Define: letsencrypt_nginx::server\n\nAutomatically get ssl certificate for nginx server\n\n#### Parameters\n\n* `domains`:\n  Array of domains to get ssl certificate for.\n  If not defined, it uses the server_name array defined in the server.\n  Use these domains instead of reading server_name array of server.\n\n* `exclude_domains`:\n  Array of servernames that should not be added as alt names for the ssl cert.\n  E.g. Elements of server_name that are defined in the server,\n  but are not public resolvable or not valid fqdns.\n\n* `webroot_paths`:\n  Passed to letsencrypt::certonly, not recommended to change\n  An array of webroot paths for the domains in `domains`.\n  Required if using `plugin =\u003e 'webroot'`. If `domains` and\n  `webroot_paths` are not the same length, `webroot_paths`\n  will cycle to make up the difference.\n\n* `additional_args`:\n  Passed to letsencrypt::certonly\n  An array of additional command line arguments to pass to the\n  `letsencrypt-auto` command.\n\n* `manage_cron`:\n  Passed to letsencrypt::certonly, default: true\n  Boolean indicating whether or not to schedule cron job for renewal.\n  Runs daily but only renews if near expiration, e.g. within 10 days.\n\n\n### Define: letsencrypt_nginx::location\n\nConfigure acme-challenge location webroot for a nginx server\n\n#### Parameters\n\n* `server`: server to configure location for, defaults to $name\n\n\n## Development\n\nRun `bundle exec rake` to execute the spec tests. There are already some basic tests for each class and define, but not all options are covered.\n\n## Release Notes\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n## Contributors\n\n* Philipp Gassmann \u003cphiphi@phiphi.ch\u003e\n\n## License\n\nApache 2.0\n\n## TODO \u0026 Ideas\n\n* Automatically configure SSL certificate and key on the server\n* Add Domains to existing Certificates\n* Support for RedHat, CentOS etc.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgassmann%2Fpuppet-letsencrypt_nginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgassmann%2Fpuppet-letsencrypt_nginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgassmann%2Fpuppet-letsencrypt_nginx/lists"}