From b95f718864c4c0382ac1f1263be32c52b03d059e Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Fri, 1 Nov 2019 05:24:01 -0600 Subject: [PATCH] update docs --- README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 52 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 480f749..4532b04 100644 --- a/README.md +++ b/README.md @@ -195,25 +195,32 @@ each domain before authorizing a certificate. -# JavaScript Library +# JavaScript API -### Instantiate +
+Greenlock.create({ packageAgent, maintainerEmail, staging }) + +### Greenlock.create() + +Creates an instance of greenlock with _environment_-level values. ```js -// Creates an instance of greenlock with certain default values +var pkg = require('./package.json'); 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' + maintainerEmail: 'jon@example.com', + // for an RFC 8555 / RFC 7231 ACME client user agent + packageAgent: pkg.name + '/' pkg.version }); ``` @@ -221,13 +228,24 @@ var gl = Greenlock.create({ | --------------- | ------------------------------------------------------------------------------------ | | maintainerEmail | the developer contact for critical bug and security notifications | | packageAgent | if you publish your package for others to use, `require('./package.json').name` here | +| staging | use the Let's Encrypt staging URL instead of the production URL | +| directoryUrl | for use with other (not Let's Encrypt) ACME services, and the Pebble test server | -### Add Approved Domains +
+ +
+Greenlock#manager.defaults() + +# Greenlock#manager.defaults() + +Acts as a getter when given no arguments. + +Otherwise sets default, site-wide values as described below. ```js greenlock.manager.defaults({ @@ -264,6 +282,20 @@ greenlock.manager.defaults({ --> +
+Greenlock#add({ subject, altnames }) + +# Greenlock#add() + +Greenlock is a **Management Environment**. + +Once you add a "site", it will begin to automatically renew, immediately. + +The certificates will provided to the `store` callbacks as soon as they are ready, and whenever they renew. +Failure to renew will be reported to the `notify` callback. + +You can also retrieve them one-off with `get`. + ```js gl.add({ subject: 'example.com', @@ -278,7 +310,12 @@ gl.add({ | subscriberEmail | if different from the default (i.e. multi-tenant, whitelabel) | | challenges | (same as main config) use if this site needs to use non-default http-01 or dns-01 validation | -### Retrieve Certificates (One-Off) +
+ +
+Greenlock#get({ servername }) + +# Greenlock#get() **Disclaimer**: This is only intended for testing, demos, and SNICallback (in [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js)). @@ -305,11 +342,16 @@ return greenlock.get({ servername }).then(function(site) { }); ``` -| Parameter | Description | -| ---------- | ------------------------------------------------------ | -| servername | the first domain on, and identifier of the certificate | +| Parameter | Description | +| ---------- | ------------------------------------------------------------- | +| servername | any altname listed on the certificate (including the subject) | -### Renew Certificates +
+ +
+Greenlock#renew() + +# Greenlock#renew() This will renew only domains that have reached their `renewAt` or are within the befault `renewOffset`.