From 5a39d81ec8927e451d059d8dad4cfcef09fe010a Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Fri, 1 Nov 2019 06:17:06 -0600 Subject: [PATCH] v3.0.20: doc updates --- README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++----- package.json | 2 +- 2 files changed, 130 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 6453c54..039b7db 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,8 @@ To start, check out the Greenlock™ is an Automated Certificate Management Environement 🔐. +| **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. It supports **Automated Renewal** of certs for Fully Automated HTTPS. @@ -60,6 +62,107 @@ TODO --> +# 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. + +
+1. Configure + +```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: 'webhosting@example.com' + }) + .then(function(fullConfig) { + // ... + }); +``` + +
+ +
+2. Add Domains + +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. + +
+ +
+3. Test for Success + +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); + }); +``` + +
+ # JavaScript API