v3.1.0: updates and docs for CLI

This commit is contained in:
AJ ONeal 2019-11-05 04:01:58 -07:00
parent 47140f6296
commit ec14a224f9
4 changed files with 178 additions and 56 deletions

179
README.md
View File

@ -81,7 +81,8 @@ module.exports = require("@root/greenlock").create({
</details> </details>
`app.js`: <details>
<summary>app.js</summary>
```js ```js
var app = function(req, res) { var app = function(req, res) {
@ -91,6 +92,8 @@ var app = function(req, res) {
module.exports = app; module.exports = app;
``` ```
</details>
```bash ```bash
npx greenlock defaults --subscriber-email 'jon@example.com' --agree-to-terms npx greenlock defaults --subscriber-email 'jon@example.com' --agree-to-terms
``` ```
@ -205,23 +208,34 @@ later, if you need them.
`server.js`: `server.js`:
```js ```js
"use strict";
require("greenlock-express") require("greenlock-express")
.init(getConfig) .init(function() {
.serve(worker); var pkg = require("./package.json");
function getConfig() {
return { return {
// uses name and version as part of the ACME client user-agent greenlock: require("@root/greenlock").create({
// uses author as the contact for support notices // name & version for ACME client user agent
package: require("./package.json") packageAgent: pkg.name + "/" + pkg.version,
};
}
function worker(server) { // contact for security and critical bug notices
// Works with any Node app (Express, etc) maintainerEmail: pkg.author,
var app = require("my-express-app.js");
server.serveApp(app); // 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: And start your server:
@ -236,6 +250,11 @@ sudo setcap 'cap_net_bind_service=+ep' $(which node)
npm start npm start
``` ```
```bash
# use --staging to use the development API until you're ready to get real certificates
npm start -- --staging
```
```txt ```txt
Greenlock v3.0.0 Greenlock v3.0.0
Greenlock Manager Config File: ~/.config/greenlock/manager.json 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. 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.
<!-- ```bash
This will update the config file (assuming the default fs-based management plugin): # see which manager and what options are in use
--> cat .greenlockrc
```
`~/.config/greenlock/manager.json`: <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" });
```
<details>
<summary>Example Output</summary>
```json ```json
{ {
"subscriberEmail": "letsencrypt-test@therootcompany.com",
"agreeToTerms": true,
"sites": {
"example.com": {
"subject": "example.com", "subject": "example.com",
"altnames": ["example.com", "www.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**: 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. 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: All individuals, and most businesses, should set this globally:
```bash ```bash
# COMING SOON
# (this command should be here by Nov 5th)
# (edit the config by hand for now)
#
# Set a global subscriber account # 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 --> <!-- 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). (of which the first _must_ be the subject).
```bash ```bash
# COMING SOON
# (this command should be here by Nov 5th)
# (edit the config by hand for now)
#
# Add a certificate with specific domains # Add a certificate with specific domains
npx greenlock add --subject example.com --altnames example.com,www.example.com 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 --> <!-- todo print where the cert was saved -->
Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require 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 # 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) - [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/) - [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/) - [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) - [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) - [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) - [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) - [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 # 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 | | 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) | - | | 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. Search `acme-http-01-` or `acme-dns-01-` on npm to find more.
# Full Documentation # Full Documentation
@ -417,7 +516,3 @@ MPL-2.0 |
[Terms of Use](https://therootcompany.com/legal/#terms) | [Terms of Use](https://therootcompany.com/legal/#terms) |
[Privacy Policy](https://therootcompany.com/legal/#privacy) [Privacy Policy](https://therootcompany.com/legal/#privacy)
[Privacy Policy](https://therootcompany.com/legal/#privacy) [Privacy Policy](https://therootcompany.com/legal/#privacy)
```
```

View File

@ -22,6 +22,24 @@ module.exports.create = function(opts) {
return greenlock.challenges.get(opts); return greenlock.challenges.get(opts);
}; };
greenlock._find({}).then(function(sites) {
if (sites.length <= 0) {
console.warn("warning: No sites available. Did you add them?");
console.warn(" npx greenlock add --subject example.com --altnames example.com");
return;
}
console.info("Ready to Serve:");
var max = 3;
if (sites.length >= 1) {
sites.slice(0, max).forEach(function(site) {
console.info("\t", site.altnames.join(" "));
});
}
if (sites.length > max) {
console.info("and %d others", sites.length - max);
}
});
return greenlock; return greenlock;
}; };

31
package-lock.json generated
View File

@ -1,9 +1,17 @@
{ {
"name": "@root/greenlock-express", "name": "@root/greenlock-express",
"version": "3.0.18", "version": "3.1.0",
"lockfileVersion": 1, "lockfileVersion": 1,
"requires": true, "requires": true,
"dependencies": { "dependencies": {
"@greenlock/manager": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/@greenlock/manager/-/manager-3.0.0.tgz",
"integrity": "sha512-ijgJrFdzJPmzrDk8aKXYoYR8LNfG3hXd9/s54ZY7IgxTulyPQ/qOPgl7sWgCxxLhZBzSY1xI6eC/6Y5TQ01agg==",
"requires": {
"greenlock-manager-fs": "^3.0.5"
}
},
"@root/acme": { "@root/acme": {
"version": "3.0.8", "version": "3.0.8",
"resolved": "https://registry.npmjs.org/@root/acme/-/acme-3.0.8.tgz", "resolved": "https://registry.npmjs.org/@root/acme/-/acme-3.0.8.tgz",
@ -40,10 +48,11 @@
"integrity": "sha512-OaEub02ufoU038gy6bsNHQOjIn8nUjGiLcaRmJ40IUykneJkIW5fxDqKxQx48cszuNflYldsJLPPXCrGfHs8yQ==" "integrity": "sha512-OaEub02ufoU038gy6bsNHQOjIn8nUjGiLcaRmJ40IUykneJkIW5fxDqKxQx48cszuNflYldsJLPPXCrGfHs8yQ=="
}, },
"@root/greenlock": { "@root/greenlock": {
"version": "3.0.27", "version": "3.1.3",
"resolved": "https://registry.npmjs.org/@root/greenlock/-/greenlock-3.0.27.tgz", "resolved": "https://registry.npmjs.org/@root/greenlock/-/greenlock-3.1.3.tgz",
"integrity": "sha512-M8qVeGa6WkL+6MK5zm1XRhP9n1fwuUlea/LS8PH3DWxf99s+77nIiK3AFPjFYNrRzKyPsWHICRLKLdK7o+F7gA==", "integrity": "sha512-9Rj9JIKYItOvZKbPa5JrljS74dw+KjltOyQnb14y4nX89C+s1mZjv3Qiv1cNuYkYCmBGR77z0/cKnfUUaWxkag==",
"requires": { "requires": {
"@greenlock/manager": "^3.0.0",
"@root/acme": "^3.0.8", "@root/acme": "^3.0.8",
"@root/csr": "^0.8.1", "@root/csr": "^0.8.1",
"@root/keypairs": "^0.9.0", "@root/keypairs": "^0.9.0",
@ -51,7 +60,7 @@
"@root/request": "^1.3.10", "@root/request": "^1.3.10",
"acme-http-01-standalone": "^3.0.5", "acme-http-01-standalone": "^3.0.5",
"cert-info": "^1.5.1", "cert-info": "^1.5.1",
"greenlock-manager-fs": "^3.0.3", "greenlock-manager-fs": "^3.0.5",
"greenlock-store-fs": "^3.2.0", "greenlock-store-fs": "^3.2.0",
"safe-replace": "^1.1.0" "safe-replace": "^1.1.0"
} }
@ -106,18 +115,18 @@
"integrity": "sha1-Aljq5NPQwJdN4cFpGI7wBR0dGYg=" "integrity": "sha1-Aljq5NPQwJdN4cFpGI7wBR0dGYg="
}, },
"greenlock-manager-fs": { "greenlock-manager-fs": {
"version": "3.0.3", "version": "3.0.5",
"resolved": "https://registry.npmjs.org/greenlock-manager-fs/-/greenlock-manager-fs-3.0.3.tgz", "resolved": "https://registry.npmjs.org/greenlock-manager-fs/-/greenlock-manager-fs-3.0.5.tgz",
"integrity": "sha512-Jwo60nHd10PNUA9M6cylD9YB4x4hzlfO2LRIGI0X+V+zA0x3KVbNW14yj8frdfHrtsWC1JQe7oFnHVdoRbAU2A==", "integrity": "sha512-r/q+tEFuDwklfzPfiGhcIrHuJxMrppC+EseESpu5f0DMokh+1iZVm9nGC/VE7/7GETdOYfEYhhQkmspsi8Gr/A==",
"requires": { "requires": {
"@root/mkdirp": "^1.0.0", "@root/mkdirp": "^1.0.0",
"safe-replace": "^1.1.0" "safe-replace": "^1.1.0"
} }
}, },
"greenlock-store-fs": { "greenlock-store-fs": {
"version": "3.2.0", "version": "3.2.2",
"resolved": "https://registry.npmjs.org/greenlock-store-fs/-/greenlock-store-fs-3.2.0.tgz", "resolved": "https://registry.npmjs.org/greenlock-store-fs/-/greenlock-store-fs-3.2.2.tgz",
"integrity": "sha512-zqcPnF+173oYq5qU7FoGtuqeG8dmmvAiSnz98kEHAHyvgRF9pE1T0MM0AuqDdj45I3kXlCj2gZBwutnRi37J3g==", "integrity": "sha512-92ejLB4DyV4qv/2b6VLGF2nKfYQeIfg3o+e/1cIoYLjlIaUFdbBXkzLTRozFlHsQPZt2ALi5qYrpC9IwH7GK8A==",
"requires": { "requires": {
"@root/mkdirp": "^1.0.0", "@root/mkdirp": "^1.0.0",
"safe-replace": "^1.1.0" "safe-replace": "^1.1.0"

View File

@ -1,6 +1,6 @@
{ {
"name": "@root/greenlock-express", "name": "@root/greenlock-express",
"version": "3.0.18", "version": "3.1.0",
"description": "Free SSL and managed or automatic HTTPS for node.js with Express, Koa, Connect, Hapi, and all other middleware systems.", "description": "Free SSL and managed or automatic HTTPS for node.js with Express, Koa, Connect, Hapi, and all other middleware systems.",
"main": "greenlock-express.js", "main": "greenlock-express.js",
"homepage": "https://greenlock.domains", "homepage": "https://greenlock.domains",
@ -17,7 +17,7 @@
"example": "examples" "example": "examples"
}, },
"dependencies": { "dependencies": {
"@root/greenlock": "^3.0.27", "@root/greenlock": "^3.1.3",
"redirect-https": "^1.1.5" "redirect-https": "^1.1.5"
}, },
"trulyOptionalDependencies": { "trulyOptionalDependencies": {