v3.0.20: doc updates
This commit is contained in:
parent
9570e1a91e
commit
5a39d81ec8
143
README.md
143
README.md
|
|
@ -18,6 +18,8 @@ To start, check out the
|
||||||
|
|
||||||
Greenlock™ is an Automated Certificate Management Environement 🔐.
|
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 uses **Let's Encrypt** to generate Free SSL Certificates, including **Wildcard** SSL.
|
||||||
It supports **Automated Renewal** of certs for Fully Automated HTTPS.
|
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.
|
||||||
|
|
||||||
|
<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: 'webhosting@example.com'
|
||||||
|
})
|
||||||
|
.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
|
# JavaScript API
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
|
|
@ -127,19 +230,20 @@ greenlock.manager.defaults({
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
| Parameter | Description |
|
| Parameter | Description |
|
||||||
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
| agreeToTerms | (default: false) either 'true' or a function that presents the Terms of Service and returns it once accepted |
|
| 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['http-01'] | provide an http-01 challenge module |
|
||||||
| challenges['dns-01'] | provide a dns-01 challenge module |
|
| challenges['dns-01'] | provide a dns-01 challenge module |
|
||||||
| challenges['tls-alpn-01'] | provide a tls-alpn-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].module | the name of your challenge module |
|
||||||
| challenges[type].xxxx | module-specific options |
|
| challenges[type].xxxx | module-specific options |
|
||||||
| servername | the default servername to use for non-sni requests (many IoT clients) |
|
| 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 |
|
||||||
| 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 |
|
| servername | the default servername to use for non-sni requests (many IoT clients) |
|
||||||
| store | override the default storage module |
|
| 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.module | the name of your storage module |
|
| store | override the default storage module |
|
||||||
| store.xxxx | options specific to your storage module |
|
| store.module | the name of your storage module |
|
||||||
|
| store.xxxx | options specific to your storage module |
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
|
|
||||||
|
|
@ -154,7 +258,7 @@ greenlock.manager.defaults({
|
||||||
|
|
||||||
## Greenlock#add()
|
## Greenlock#add()
|
||||||
|
|
||||||
Greenlock is a **Management Environment**.
|
Greenlock is a **Automated Certificate Management Environment**.
|
||||||
|
|
||||||
Once you add a "site", it will begin to automatically renew, immediately.
|
Once you add a "site", it will begin to automatically renew, immediately.
|
||||||
|
|
||||||
|
|
@ -275,6 +379,17 @@ gl.remove({
|
||||||
|
|
||||||
</details>
|
</details>
|
||||||
|
|
||||||
|
<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>
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
|
|
||||||
<details>
|
<details>
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
{
|
{
|
||||||
"name": "@root/greenlock",
|
"name": "@root/greenlock",
|
||||||
"version": "3.0.19",
|
"version": "3.0.20",
|
||||||
"description": "The easiest Let's Encrypt client for Node.js and Browsers",
|
"description": "The easiest Let's Encrypt client for Node.js and Browsers",
|
||||||
"homepage": "https://rootprojects.org/greenlock/",
|
"homepage": "https://rootprojects.org/greenlock/",
|
||||||
"main": "greenlock.js",
|
"main": "greenlock.js",
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue