diff --git a/README.md b/README.md index 53799e4..ce48ade 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,210 @@ -# root-greenlock.js +# @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. + +- [x] **Wildcard** Certificates +- [x] **IoT** Environments +- [x] **Enterprise** and **On-Prem** +- [x] **Private** Networks +- [x] **Localhost** Development +- [x] **Web Hosting** Providers +- [x] **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 + +```js +// 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 + +```js +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`. + +```js +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 +}); + +``` +
+ + +
+WebPack +TODO +
+ +
+VanillaJS for Browsers +TODO +
+ +# HTTP-01 & 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.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 ``` -Greenlock.create -Greenlock#add -Greenlock#order... or Greenlock#issue? -Greenlock#renew... or Greenlock#issue? -Greenlock#remove -Greenlock#get -Greenlock#all -``` - -Better scaling - -cluster lazy-load, remote management - -`server identifier (for sharding, for manager)` diff --git a/greenlock.js b/greenlock.js index 2d3ea2f..8b5009f 100644 --- a/greenlock.js +++ b/greenlock.js @@ -128,9 +128,9 @@ G.create = function(gconf) { greenlock._notify = function(ev, params) { var mng = greenlock.manager; - if (mng.notify) { + if (mng.notif || greenlock._defaults.notify) { try { - var p = mng.notify(ev, params); + var p = (mng.notify || greenlock._defaults.notify)(ev, params); if (p && p.catch) { p.catch(function(e) { console.error("Error on event '" + ev + "':");