🔐 Free SSL, Free Wildcard SSL, and Fully Automated HTTPS for node.js, issued by Let's Encrypt v2 via ACME https://git.rootprojects.org/root/greenlock.js
Go to file
AJ ONeal f3cacf6db4 add some docs 2019-10-21 20:18:16 -06:00
bin wip: yeah! 2019-10-20 02:51:19 -06:00
examples wip: yeah! 2019-10-20 02:51:19 -06:00
tests move manager.js to own module 2019-10-21 17:37:51 -06:00
.gitignore wip: yeah! 2019-10-20 02:51:19 -06:00
LICENSE Initial commit 2019-10-16 00:26:05 +00:00
README.md add some docs 2019-10-21 20:18:16 -06:00
accounts.js need to fail when privkey cannot be found 2019-10-20 03:17:19 -06:00
certificates.js working, huzzah! 2019-10-20 03:27:05 -06:00
errors.js wip: yeah! 2019-10-20 02:51:19 -06:00
express.js wip: yeah! 2019-10-20 02:51:19 -06:00
greenlock.js add some docs 2019-10-21 20:18:16 -06:00
order.js wip: yeah! 2019-10-20 02:51:19 -06:00
package-lock.json wip: yeah! 2019-10-20 02:51:19 -06:00
package.json fix deps and urls 2019-10-21 17:16:32 -06:00
plugins.js export PKG_DIR for other libs to override 2019-10-21 17:37:31 -06:00
user-events.js wip: yeah! 2019-10-20 02:51:19 -06:00
utils.js working, huzzah! 2019-10-20 03:27:05 -06:00

README.md

@root/greenlock

🔐 Free SSL, Free Wildcard SSL, and Fully Automated HTTPS for Node.js and Browsers, issued by Let's Encrypt v2 via ACME

Greenlock™ is the easiest way to integrate Let's Encrypt into your projects, products, and infrastructure.

  • Wildcard Certificates
  • IoT Environments
  • Enterprise and On-Prem
  • Private Networks
  • Localhost Development
  • Web Hosting Providers
  • Commercial support

We've built it simple enough for Hobbyists, and robust enough for the Enterprise.

Localhost Development

HTTPS on Localhost TODO

WebServer with Automatic HTTPS

Learn more about the Greenlock Web Server TODO

Commandline

Learn more about the Greenlock CLI TODO

JavaScript Library

Greenlock API (shared among JS implementations)

Instantiate

// Creates an instance of greenlock with certain default values

var gl = Greenlock.create({
	// Staging for testing environments
	staging: true,

	// This should be the contact who receives critical bug and security notifications
	// Optionally, you may receive other (very few) updates, such as important new features
	maintainerEmail: 'jon@example.com',
	maintainerUpdates: true, // default: false

	// The "Let's Encrypt Subscriber" (often the same as the maintainer)
	// NOT the end customer (except where that is also the maintainer)
	subscriberEmail: 'jon@example.com',
	agreeToTerms: true // default: false
});
Parameter Description
maintainerEmail the developer contact for critical bug and security notifications
maintainerUpdates (default: false) receive occasional non-critical notifications
subscriberEmail the contact who agrees to the Let's Encrypt Subscriber Agreement and the Greenlock Terms of Service
this contact receives renewal failure notifications
agreeToTerms (default: false) either 'true' or a function that presents the Terms of Service and returns it once accepted

Add Approved Domains

gl.add({
	subject: 'example.com',
	altnames: ['example.com', 'www.example.com', 'exampleapi.com']
});
Parameter Description
subject the first domain on, and identifier of the certificate
altnames first domain, plus additional domains
note: the order should always be the same
subscriberEmail if different from the default (i.e. multi-tenant, whitelabel)
agreeToTerms if subscriber is different from the default

Issue and Renew Certificates

This will renew only domains that have reached their renewAt or are within the befault renewOffset.

return greenlock
	.renew()
	.then(function(pems) {
		console.info(pems);
	})
	.then(function(results) {
		results.forEach(function(site) {
			if (site.error) {
				console.error(site.subject, site.error);
				return;
			}
		});
	});
Parameter Type Description
(optional) - ALL parameters are optional, but some should be paired
force bool force silly options, such as tiny durations
duplicate bool force the domain to renew, regardless of age or expiration

Note: only previous approved domains (via gl.add()) may be renewed

Note: this will NOT throw an error. It will return an array of certifates or errors.

More

TODO

Node.js ```bash npm install --save @root/greenlock ````

TODO

Express.js ```js 'use strict';

var Greenlock = require(@root/greenlock-express);

var greenlock = Greenlock.create({ // for security and critical bug notices maintainerEmail: 'jon@example.com'

// for maintainerNewsletter: true });

</details>


<details>
<summary>WebPack</summary>
TODO
</details>

<details>
<summary>VanillaJS for Browsers</summary>
TODO
</details>

# HTTP-01 &amp; DNS-01 Integrations

For Public Web Servers running on a VPS, the **default HTTP-01 challenge plugin**
will work just fine for most people.

However, for

-   **Wildcard Certificates**
-   **IoT Environments**
-   **Enterprise On-Prem**
-   **Private Networks**

Greenlock provides an easy way to integrate Let's Encrypt with your existing services
through a variety of **DNS-01** infrastructure

Why
Typically file propagation is faster and more reliably than DNS propagation.
Therefore, http-01 will be preferred to dns-01 except when wildcards or **private domains** are in use.

http-01 will only be supplied as a defaut if no other challenge is provided.

You can use ACME (Let's Encrypt) with

    -   [x] DNS-01 Challenges
        -   CloudFlare
        -   [Digital Ocean](https://git.rootprojects.org/root/acme-dns-01-digitalocean.js)
        -   [DNSimple](https://git.rootprojects.org/root/acme-dns-01-dnsimple.js)
        -   [DuckDNS](https://git.rootprojects.org/root/acme-dns-01-duckdns.js)
        -   [GoDaddy](https://git.rootprojects.org/root/acme-dns-01-godaddy.js)
        -   [Gandi](https://git.rootprojects.org/root/acme-dns-01-gandi.js)
        -   [NameCheap](https://git.rootprojects.org/root/acme-dns-01-namecheap.js)
        -   [Name&#46;com](https://git.rootprojects.org/root/acme-dns-01-namedotcom.js)
        -   Route53 (AWS)
        -   [Vultr](https://git.rootprojects.org/root/acme-dns-01-vultr.js)
        -   Build your own
    -   [x] HTTP-01 Challenges
        -   [In-Memory](https://git.rootprojects.org/root/acme-http-01-standalone.js) (Standalone)
        -   [FileSystem](https://git.rootprojects.org/root/acme-http-01-webroot.js) (WebRoot)
        -   S3 (AWS, Digital Ocean, etc)
    -   [x] TLS-ALPN-01 Challenges
        - Contact us to learn about Greenlock Pro