This commit is contained in:
AJ ONeal 2019-11-05 04:03:07 -07:00
parent d1abb97e1d
commit 629fd3ae88
3 changed files with 246 additions and 95 deletions

296
README.md
View File

@ -1,11 +1,3 @@
# New Documentation & [v2/v3 Migration Guide](https://git.rootprojects.org/root/greenlock.js/src/branch/v3/MIGRATION_GUIDE_V2_V3.md)
Greenlock v3 just came out of private beta **today** (Nov 1st, 2019).
The code is complete and we're working on great documentation.
Many **examples** and **full API** documentation are still coming.
# [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js) is Let's Encrypt for Node # [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js) is Let's Encrypt for Node
![Greenlock Logo](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo") ![Greenlock Logo](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo")
@ -14,51 +6,104 @@ Many **examples** and **full API** documentation are still coming.
Free SSL, Automated HTTPS / HTTP2, served with Node via Express, Koa, hapi, etc. Free SSL, Automated HTTPS / HTTP2, served with Node via Express, Koa, hapi, etc.
### Let's Encrypt for Node, Express, etc ### Let's Encrypt for Node and Express (and Koa, hapi, rill, etc)
Greenlock Express is a **Web Server** with **Fully Automated HTTPS** and renewals. Greenlock Express is a **Web Server** with **Fully Automated HTTPS** and renewals.
You define your app, and let Greenlock handle issuing and renewing Free SSL Certificates.
**Cloud-ready** with Node `cluster`.
# Serve your Sites with Free SSL
- 1. Create a Project with Greenlock Express
- 2. Initialize and Setup
- 3. Add Domains, and Hello, World!
### Create your project
```bash
npm init
```
```bash
npm install --save greenlock-express@v3
```
```bash
npx greenlock init --maintainer-email 'jon@example.com' --manager-config-file ./greenlock.json
```
<details>
<summary>server.js</summary>
```js ```js
"use strict"; "use strict";
function httpsWorker(glx) {
// Serves on 80 and 443
// Get's SSL certificates magically!
glx.serveApp(function(req, res) {
res.end("Hello, Encrypted World!");
});
}
var pkg = require("./package.json");
require("greenlock-express") require("greenlock-express")
.init(function getConfig() { .init(function() {
// Greenlock Config
return { return {
package: { name: pkg.name, version: pkg.version }, greenlock: require("./greenlock.js"),
maintainerEmail: pkg.author,
// whether or not to run at cloudscale
cluster: false cluster: false
}; };
}) })
.serve(httpsWorker); .ready(function(glx) {
var app = require("./app.js");
// Serves on 80 and 443
// Get's SSL certificates magically!
glx.serveApp(app);
});
``` ```
Manage via API or the config file: </details>
`~/.config/greenlock/manage.json`: (default filesystem config) <details>
<summary>greenlock.js</summary>
```json ```js
{ "use strict";
"subscriberEmail": "letsencrypt-test@therootcompany.com",
"agreeToTerms": true, var pkg = require("./package.json");
"sites": { module.exports = require("@root/greenlock").create({
"example.com": { // name & version for ACME client user agent
"subject": "example.com", packageAgent: pkg.name + "/" + pkg.version,
"altnames": ["example.com", "www.example.com"]
} // contact for security and critical bug notices
} maintainerEmail: pkg.author,
}
// where to find .greenlockrc and set default paths
packageRoot: __dirname
});
```
</details>
<details>
<summary>app.js</summary>
```js
var app = function(req, res) {
res.end("Hello, Encrypted World!");
};
module.exports = app;
```
</details>
```bash
npx greenlock defaults --subscriber-email 'jon@example.com' --agree-to-terms
```
```bash
npx greenlock add --subject example.com --altnames example.com
```
```bash
npm start -- --staging
``` ```
# Let's Encrypt for... # Let's Encrypt for...
@ -163,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");
return {
greenlock: require("@root/greenlock").create({
// name & version for ACME client user agent
packageAgent: pkg.name + "/" + pkg.version,
function getConfig() { // contact for security and critical bug notices
return { maintainerEmail: pkg.author,
// uses name and version as part of the ACME client user-agent
// uses author as the contact for support notices
package: require("./package.json")
};
}
function worker(server) { // where to find .greenlockrc and set default paths
// Works with any Node app (Express, etc) packageRoot: __dirname
var app = require("my-express-app.js"); }),
server.serveApp(app);
} // 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:
@ -194,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
@ -212,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 ```json
{ {
"subscriberEmail": "letsencrypt-test@therootcompany.com", "manager": "greenlock-manager-fs",
"agreeToTerms": true, "configFile": "./greenlock.json"
"sites": { }
"example.com": { ```
"subject": "example.com",
"altnames": ["example.com", "www.example.com"] </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
{
"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**: 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 -->
@ -256,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
@ -278,14 +408,12 @@ 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/)
- [Node's https](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/https/) - [Node's https](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/https/)
- [**WebSockets**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/websockets/) - [**WebSockets**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/websockets/)
- [Socket.IO](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/socket-io/) - [Socket.IO](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/socket.io/)
- [Cluster](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/cluster/) - [Cluster](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/cluster/)
- [**Wildcards**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcards/) (coming soon) - [**Wildcards**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcards/) (coming soon)
- [**Localhost**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/) (coming soon) - [**Localhost**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/) (coming soon)
@ -301,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
@ -327,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
@ -374,3 +515,4 @@ attribution, and/or visible source policies. We want to build great software and
MPL-2.0 | 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)

39
package-lock.json generated
View File

@ -1,9 +1,17 @@
{ {
"name": "greenlock-express", "name": "greenlock-express",
"version": "3.0.15", "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,19 +48,20 @@
"integrity": "sha512-OaEub02ufoU038gy6bsNHQOjIn8nUjGiLcaRmJ40IUykneJkIW5fxDqKxQx48cszuNflYldsJLPPXCrGfHs8yQ==" "integrity": "sha512-OaEub02ufoU038gy6bsNHQOjIn8nUjGiLcaRmJ40IUykneJkIW5fxDqKxQx48cszuNflYldsJLPPXCrGfHs8yQ=="
}, },
"@root/greenlock-express": { "@root/greenlock-express": {
"version": "3.0.15", "version": "3.1.0",
"resolved": "https://registry.npmjs.org/@root/greenlock-express/-/greenlock-express-3.0.15.tgz", "resolved": "https://registry.npmjs.org/@root/greenlock-express/-/greenlock-express-3.1.0.tgz",
"integrity": "sha512-TrdU0BdV7heDr4o5mrIbaPLtaskPYvyDlDWmTYVInyYmgc12tEk2vHJx5KZlVQSkZPi6jnc/v606R18zTezchA==", "integrity": "sha512-KxsBKobvQ3YKlfjSsAFSN2jvkRdkn8CrVKP2swVoiXtrduBgqDMfAaE85S+Wiz17wmk42na0369TqLPp8wzEjQ==",
"requires": { "requires": {
"@root/greenlock": "^3.0.27", "@root/greenlock": "^3.1.3",
"redirect-https": "^1.1.5" "redirect-https": "^1.1.5"
}, },
"dependencies": { "dependencies": {
"@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",
@ -60,7 +69,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"
} }
@ -117,18 +126,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": "greenlock-express", "name": "greenlock-express",
"version": "3.0.15", "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,8 +17,8 @@
"example": "examples" "example": "examples"
}, },
"dependencies": { "dependencies": {
"@root/greenlock": "^3.0.27", "@root/greenlock": "^3.1.3",
"@root/greenlock-express": "^3.0.15", "@root/greenlock-express": "^3.1.0",
"redirect-https": "^1.1.5" "redirect-https": "^1.1.5"
}, },
"trulyOptionalDependencies": { "trulyOptionalDependencies": {