add some docs
This commit is contained in:
parent
bc9a3d179d
commit
f3cacf6db4
216
README.md
216
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
|
🔐 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
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>HTTPS on Localhost</summary>
|
||||||
|
TODO
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
# WebServer with Automatic HTTPS
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Learn more about the Greenlock Web Server</summary>
|
||||||
|
TODO
|
||||||
|
</details>
|
||||||
|
|
||||||
|
# Commandline
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Learn more about the Greenlock CLI</summary>
|
||||||
|
TODO
|
||||||
|
</details>
|
||||||
|
|
||||||
|
# JavaScript Library
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Greenlock API (shared among JS implementations)</summary>
|
||||||
|
|
||||||
|
### 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<br>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<br>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 |
|
||||||
|
|
||||||
|
<!--
|
||||||
|
| servername | string<br>hostname | renew the certificate that has this domain in its altnames (for ServerName Indication / SNI lookup) |
|
||||||
|
| renewOffset | string<br>+ duration | renew domains that have been **issued** after the given duration. ex: '45d' (45 days _after_) |
|
||||||
|
| renewOffset | string<br>- duration | renew domains, by this duration, before they **expire**. ex: '-3w' (3 weeks _before_) |
|
||||||
|
-->
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Node.js</summary>
|
||||||
|
```bash
|
||||||
|
npm install --save @root/greenlock
|
||||||
|
````
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Express.js</summary>
|
||||||
|
```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
|
||||||
|
});
|
||||||
|
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>WebPack</summary>
|
||||||
|
TODO
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>VanillaJS for Browsers</summary>
|
||||||
|
TODO
|
||||||
|
</details>
|
||||||
|
|
||||||
|
# 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.
|
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.
|
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.
|
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)`
|
|
||||||
|
|
|
||||||
|
|
@ -128,9 +128,9 @@ G.create = function(gconf) {
|
||||||
|
|
||||||
greenlock._notify = function(ev, params) {
|
greenlock._notify = function(ev, params) {
|
||||||
var mng = greenlock.manager;
|
var mng = greenlock.manager;
|
||||||
if (mng.notify) {
|
if (mng.notif || greenlock._defaults.notify) {
|
||||||
try {
|
try {
|
||||||
var p = mng.notify(ev, params);
|
var p = (mng.notify || greenlock._defaults.notify)(ev, params);
|
||||||
if (p && p.catch) {
|
if (p && p.catch) {
|
||||||
p.catch(function(e) {
|
p.catch(function(e) {
|
||||||
console.error("Error on event '" + ev + "':");
|
console.error("Error on event '" + ev + "':");
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue