@root/greenlock - npm Package Compare versions

Comparing version 3.0.19 to 3.0.20

package.json

 {
     "name": "@root/greenlock",
-    "version": "3.0.19",
+    "version": "3.0.20",
     "description": "The easiest Let's Encrypt client for Node.js and Browsers",
@@ -5,0 +5,0 @@ "homepage": "https://rootprojects.org/greenlock/",

README.md

@@ -21,2 +21,4 @@ # New Documentation & [v2/v3 Migration Guide](https://git.rootprojects.org/root/greenlock.js/src/branch/v3/MIGRATION_GUIDE_V2_V3.md)
 
+| **Greenlock** | [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js) | [ACME.js](https://git.rootprojects.org/root/acme.js) |
+
 It uses **Let's Encrypt** to generate Free SSL Certificates, including **Wildcard** SSL.
@@ -64,2 +66,103 @@ It supports **Automated Renewal** of certs for Fully Automated HTTPS.
 
+# Quick Start
+
+Greenlock is fully-automated, **SSL Certificate Manager** for IoT, Web Hosting, and Enterprise On-Prem, Edge, and Hybrid Cloud.
+
+(though we started building it for [Home Servers](https://rootprojects.org/hub/))
+
+You can use it for one-off certificates, like `certbot`,
+but it is _much_ more powerful than that.
+
+By setting just a few callbacks to let it know where it should store private keys and certificates,
+it will automatically renew any certificate that you add to it, as long as the process is running.
+
+Certificates are renewed every 45 days by default, and renewal checks will happen several times a day.
+
+<details>
+<summary>1. Configure</summary>
+
+```js
+'use strict';
+
+var pkg = require('./package.json');
+var Greenlock = require('greenlock');
+var greenlock = Greenlock.create({
+    packageAgent: pkg.name + '/' + pkg.version,
+    maintainerEmail: pkg.author,
+    staging: true,
+    manager: require('greenlock-manager-fs').create({
+        configFile: '~/.config/greenlock/manager.json'
+    }),
+    notify: function(event, details) {
+        if ('error' === event) {
+            // `details` is an error object in this case
+            console.error(details);
+        }
+    }
+});
+
+greenlock.manager
+    .defaults({
+        agreeToTerms: true,
+        subscriberEmail: '[e-mail]'
+    })
+    .then(function(fullConfig) {
+        // ...
+    });
+```
+
+</details>
+
+<details>
+<summary>2. Add Domains</summary>
+
+The `subject` (primary domain on certificate) will be the id,
+so it's very important that the order of the given domains
+be deterministic.
+
+```js
+var altnames = ['example.com', 'www.example.com'];
+
+greenlock
+    .add({
+        subject: altnames[0],
+        altnames: altnames
+    })
+    .then(function() {
+        // saved config to db (or file system)
+    });
+```
+
+Issuance and renewal will start immediately, and run continually.
+
+</details>
+
+<details>
+<summary>3. Test for Success</summary>
+
+The `store` callbacks will be called every any of your certificates
+are renewed.
+
+However, you can do a quick one-off check with `get`.
+
+It will return a certificate immediately (if available),
+or wait for the renewal to complete (or for it to fail again).
+
+```js
+greenlock
+    .get({ servername: subject })
+    .then(function(pems) {
+        if (pems && pems.privkey && pems.cert && pems.chain) {
+            console.info('Success');
+        }
+        //console.log(pems);
+    })
+    .catch(function(e) {
+        console.error('Big bad error:', e.code);
+        console.error(e);
+    });
+```
+
+</details>
+
 # JavaScript API
@@ -132,15 +235,16 @@
 
-| Parameter                 | Description                                                                                                                                                |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| agreeToTerms              | (default: false) either 'true' or a function that presents the Terms of Service and returns it once accepted                                               |
-| challenges['http-01']     | provide an http-01 challenge module                                                                                                                        |
-| challenges['dns-01']      | provide a dns-01 challenge module                                                                                                                          |
-| challenges['tls-alpn-01'] | provide a tls-alpn-01 challenge module                                                                                                                     |
-| challenges[type].module   | the name of your challenge module                                                                                                                          |
-| challenges[type].xxxx     | module-specific options                                                                                                                                    |
-| servername                | the default servername to use for non-sni requests (many IoT clients)                                                                                      |
-| subscriberEmail           | the contact who agrees to the Let's Encrypt Subscriber Agreement and the Greenlock Terms of Service<br>this contact receives renewal failure notifications |
-| store                     | override the default storage module                                                                                                                        |
-| store.module              | the name of your storage module                                                                                                                            |
-| store.xxxx                | options specific to your storage module                                                                                                                    |
+| Parameter                 | Description                                                                                                                                                                        |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| agreeToTerms              | (default: false) either 'true' or a function that presents the Terms of Service and returns it once accepted                                                                       |
+| challenges['http-01']     | provide an http-01 challenge module                                                                                                                                                |
+| challenges['dns-01']      | provide a dns-01 challenge module                                                                                                                                                  |
+| challenges['tls-alpn-01'] | provide a tls-alpn-01 challenge module                                                                                                                                             |
+| challenges[type].module   | the name of your challenge module                                                                                                                                                  |
+| challenges[type].xxxx     | module-specific options                                                                                                                                                            |
+| renewOffset               | **leave the default** Other than for testing, leave this at the default of 45 days before expiration date (`'-45d'`) . Can also be set like `5w`, meaning 5 weeks after issue date |
+| servername                | the default servername to use for non-sni requests (many IoT clients)                                                                                                              |
+| subscriberEmail           | the contact who agrees to the Let's Encrypt Subscriber Agreement and the Greenlock Terms of Service<br>this contact receives renewal failure notifications                         |
+| store                     | override the default storage module                                                                                                                                                |
+| store.module              | the name of your storage module                                                                                                                                                    |
+| store.xxxx                | options specific to your storage module                                                                                                                                            |
 
@@ -160,3 +264,3 @@ <!--
 
-Greenlock is a **Management Environment**.
+Greenlock is a **Automated Certificate Management Environment**.
 
@@ -282,2 +386,13 @@ Once you add a "site", it will begin to automatically renew, immediately.
 
+<details>
+<summary>Events</summary>
+
+Most of the events bubble from ACME.js.
+
+See https://git.rootprojects.org/root/acme.js#api-overview
+
+_TODO_: document the greenlock-specific events.
+
+</details>
+
 <!--
@@ -284,0 +399,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

123272

increased by2.87%

Number of lines in readme file

667

increased by20.83%

No dependency changes