|
|
@ -81,7 +81,8 @@ module.exports = require("@root/greenlock").create({ |
|
|
|
|
|
|
|
</details> |
|
|
|
|
|
|
|
`app.js`: |
|
|
|
<details> |
|
|
|
<summary>app.js</summary> |
|
|
|
|
|
|
|
```js |
|
|
|
var app = function(req, res) { |
|
|
@ -91,6 +92,8 @@ var app = function(req, res) { |
|
|
|
module.exports = app; |
|
|
|
``` |
|
|
|
|
|
|
|
</details> |
|
|
|
|
|
|
|
```bash |
|
|
|
npx greenlock defaults --subscriber-email 'jon@example.com' --agree-to-terms |
|
|
|
``` |
|
|
@ -205,23 +208,34 @@ later, if you need them. |
|
|
|
`server.js`: |
|
|
|
|
|
|
|
```js |
|
|
|
"use strict"; |
|
|
|
|
|
|
|
require("greenlock-express") |
|
|
|
.init(getConfig) |
|
|
|
.serve(worker); |
|
|
|
|
|
|
|
function getConfig() { |
|
|
|
return { |
|
|
|
// uses name and version as part of the ACME client user-agent |
|
|
|
// uses author as the contact for support notices |
|
|
|
package: require("./package.json") |
|
|
|
}; |
|
|
|
} |
|
|
|
.init(function() { |
|
|
|
var pkg = require("./package.json"); |
|
|
|
return { |
|
|
|
greenlock: require("@root/greenlock").create({ |
|
|
|
// name & version for ACME client user agent |
|
|
|
packageAgent: pkg.name + "/" + pkg.version, |
|
|
|
|
|
|
|
function worker(server) { |
|
|
|
// Works with any Node app (Express, etc) |
|
|
|
var app = require("my-express-app.js"); |
|
|
|
server.serveApp(app); |
|
|
|
} |
|
|
|
// contact for security and critical bug notices |
|
|
|
maintainerEmail: pkg.author, |
|
|
|
|
|
|
|
// where to find .greenlockrc and set default paths |
|
|
|
packageRoot: __dirname |
|
|
|
}), |
|
|
|
|
|
|
|
// whether or not to run at cloudscale |
|
|
|
cluster: false |
|
|
|
}; |
|
|
|
}) |
|
|
|
.ready(function(glx) { |
|
|
|
var app = require("./app.js"); |
|
|
|
|
|
|
|
// Serves on 80 and 443 |
|
|
|
// Get's SSL certificates magically! |
|
|
|
glx.serveApp(app); |
|
|
|
}); |
|
|
|
``` |
|
|
|
|
|
|
|
And start your server: |
|
|
@ -236,6 +250,11 @@ sudo setcap 'cap_net_bind_service=+ep' $(which node) |
|
|
|
npm start |
|
|
|
``` |
|
|
|
|
|
|
|
```bash |
|
|
|
# use --staging to use the development API until you're ready to get real certificates |
|
|
|
npm start -- --staging |
|
|
|
``` |
|
|
|
|
|
|
|
```txt |
|
|
|
Greenlock v3.0.0 |
|
|
|
Greenlock Manager Config File: ~/.config/greenlock/manager.json |
|
|
@ -254,42 +273,108 @@ Listening on 0.0.0.0:443 for secure traffic |
|
|
|
|
|
|
|
The management API is built to work with Databases, S3, etc. |
|
|
|
|
|
|
|
HOWEVER, by default it starts with a simple config file. |
|
|
|
By default, it's just a simple config file and directory. |
|
|
|
|
|
|
|
<!-- |
|
|
|
This will update the config file (assuming the default fs-based management plugin): |
|
|
|
--> |
|
|
|
```bash |
|
|
|
# see which manager and what options are in use |
|
|
|
cat .greenlockrc |
|
|
|
``` |
|
|
|
|
|
|
|
<details> |
|
|
|
<summary>Example Output</summary> |
|
|
|
|
|
|
|
```json |
|
|
|
{ |
|
|
|
"manager": "greenlock-manager-fs", |
|
|
|
"configFile": "./greenlock.json" |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
</details> |
|
|
|
|
|
|
|
```bash |
|
|
|
# show the global defaults |
|
|
|
npx greenlock defaults |
|
|
|
``` |
|
|
|
|
|
|
|
```js |
|
|
|
var defaults = await greenlock.defaults(); |
|
|
|
``` |
|
|
|
|
|
|
|
<details> |
|
|
|
<summary>Example Output</summary> |
|
|
|
|
|
|
|
```json |
|
|
|
{ |
|
|
|
"store": { |
|
|
|
"module": "greenlock-store-fs", |
|
|
|
"basePath": "./greenlock.d" |
|
|
|
}, |
|
|
|
"challenges": { |
|
|
|
"http-01": { |
|
|
|
"module": "acme-http-01-standalone" |
|
|
|
} |
|
|
|
}, |
|
|
|
"renewOffset": "-45d", |
|
|
|
"renewStagger": "3d", |
|
|
|
"accountKeyType": "EC-P256", |
|
|
|
"serverKeyType": "RSA-2048", |
|
|
|
"subscriberEmail": "jon@example.com", |
|
|
|
"agreeToTerms": true |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
</details> |
|
|
|
|
|
|
|
```bash |
|
|
|
# show per-site configs |
|
|
|
npx greenlock config --subject example.com |
|
|
|
``` |
|
|
|
|
|
|
|
```js |
|
|
|
greenlock.sites.get({ subject: "example.com" }); |
|
|
|
``` |
|
|
|
|
|
|
|
`~/.config/greenlock/manager.json`: |
|
|
|
<details> |
|
|
|
<summary>Example Output</summary> |
|
|
|
|
|
|
|
```json |
|
|
|
{ |
|
|
|
"subscriberEmail": "letsencrypt-test@therootcompany.com", |
|
|
|
"agreeToTerms": true, |
|
|
|
"sites": { |
|
|
|
"example.com": { |
|
|
|
"subject": "example.com", |
|
|
|
"altnames": ["example.com", "www.example.com"] |
|
|
|
"subject": "example.com", |
|
|
|
"altnames": ["example.com"], |
|
|
|
"renewAt": 1576638107754, |
|
|
|
"defaults": { |
|
|
|
"store": { |
|
|
|
"module": "greenlock-store-fs", |
|
|
|
"basePath": "./greenlock.d" |
|
|
|
}, |
|
|
|
"challenges": { |
|
|
|
"http-01": { |
|
|
|
"module": "acme-http-01-standalone" |
|
|
|
} |
|
|
|
} |
|
|
|
} |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
COMING SOON |
|
|
|
</details> |
|
|
|
|
|
|
|
Management can be done via the **CLI** or the JavaScript [**API**](https://git.rootprojects.org/root/greenlock.js/). |
|
|
|
Management can be done via the **CLI** or the JavaScript [**API**](https://git.rootprojects.org/root/greenlock.js). |
|
|
|
Since this is the QuickStart, we'll demo the **CLI**: |
|
|
|
|
|
|
|
You need to create a Let's Encrypt _subscriber account_, which can be done globally, or per-site. |
|
|
|
All individuals, and most businesses, should set this globally: |
|
|
|
|
|
|
|
```bash |
|
|
|
# COMING SOON |
|
|
|
# (this command should be here by Nov 5th) |
|
|
|
# (edit the config by hand for now) |
|
|
|
# |
|
|
|
# Set a global subscriber account |
|
|
|
npx greenlock config --subscriber-email 'mycompany@example.com' --agree-to-terms true |
|
|
|
npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true |
|
|
|
``` |
|
|
|
|
|
|
|
```js |
|
|
|
greenlock.manager.defaults({ |
|
|
|
subscriberEmail: "mycompany@example.com", |
|
|
|
agreeToTerms: true |
|
|
|
}); |
|
|
|
``` |
|
|
|
|
|
|
|
<!-- todo print where the key was saved --> |
|
|
@ -298,14 +383,17 @@ A Let's Encrypt SSL certificate has a "Subject" (Primary Domain) and up to 100 " |
|
|
|
(of which the first _must_ be the subject). |
|
|
|
|
|
|
|
```bash |
|
|
|
# COMING SOON |
|
|
|
# (this command should be here by Nov 5th) |
|
|
|
# (edit the config by hand for now) |
|
|
|
# |
|
|
|
# Add a certificate with specific domains |
|
|
|
npx greenlock add --subject example.com --altnames example.com,www.example.com |
|
|
|
``` |
|
|
|
|
|
|
|
```js |
|
|
|
greenlock.sites.add({ |
|
|
|
subject: "example.com", |
|
|
|
altnames: ["example.com"] |
|
|
|
}); |
|
|
|
``` |
|
|
|
|
|
|
|
<!-- todo print where the cert was saved --> |
|
|
|
|
|
|
|
Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require |
|
|
@ -320,8 +408,6 @@ Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require |
|
|
|
|
|
|
|
# Plenty of Examples |
|
|
|
|
|
|
|
**These are in-progress** Check back tomorrow (Nov 2nd, 2019). |
|
|
|
|
|
|
|
- [greenlock-express.js/examples/](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples) |
|
|
|
- [Express](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/express/) |
|
|
|
- [Node's **http2**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http2/) |
|
|
@ -343,9 +429,15 @@ Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require |
|
|
|
--> |
|
|
|
|
|
|
|
- [Custom Domain Management](https://git.rootprojects.org/root/greenlock-manager-test.js) |
|
|
|
- `npx greenlock init --manager ./path-or-npm-name.js --manager-FOO 'set option FOO'` |
|
|
|
- [Custom Key & Cert Storage](https://git.rootprojects.org/root/greenlock-store-test.js) |
|
|
|
- `npx greenlock defaults --store greenlock-store-fs --store-base-path ./greenlock.d` |
|
|
|
- [Custom ACME HTTP-01 Challenges](https://git.rootprojects.org/root/acme-http-01-test.js) |
|
|
|
- `npx greenlock defaults --challenge-http-01 ./you-http-01.js` |
|
|
|
- `npx greenlock update --subject example.com --challenge-http-01 acme-http-01-standalone` |
|
|
|
- [Custom ACME DNS-01 Challenges](https://git.rootprojects.org/root/acme-dns-01-test.js) |
|
|
|
- `npx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx` |
|
|
|
- `npx greenlock update --subject example.com --challenge-dns-01 ./your-dns-01.js |
|
|
|
|
|
|
|
# Ready-made Integrations |
|
|
|
|
|
|
@ -369,6 +461,13 @@ Greenlock Express integrates between Let's Encrypt's ACME Challenges and many po |
|
|
|
| http-01 | [Build your own](https://git.rootprojects.org/root/acme-http-01-test.js) | acme-http-01-test | |
|
|
|
| tls-alpn-01 | [Contact us](mailto:support@therootcompany.com) | - | |
|
|
|
|
|
|
|
Example Usage: |
|
|
|
|
|
|
|
```bash |
|
|
|
npx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx |
|
|
|
npx greenlock defaults --challenge-http-01 acme-http-01-s3 --challenge-http-01-bucket my-bucket |
|
|
|
``` |
|
|
|
|
|
|
|
Search `acme-http-01-` or `acme-dns-01-` on npm to find more. |
|
|
|
|
|
|
|
# Full Documentation |
|
|
@ -417,7 +516,3 @@ MPL-2.0 | |
|
|
|
[Terms of Use](https://therootcompany.com/legal/#terms) | |
|
|
|
[Privacy Policy](https://therootcompany.com/legal/#privacy) |
|
|
|
[Privacy Policy](https://therootcompany.com/legal/#privacy) |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
``` |
|
|
|