root
/
greenlock-express.js
mirror of https://github.com/therootcompany/greenlock-express.js.git
2
1
Fork 0
Code Issues 43 Releases Wiki Activity

v3.0.9: add examples

This commit is contained in:
AJ ONeal 2019-11-01 04:12:40 -06:00
parent a7526ffad8
commit fceeb8c72c
26 changed files with 471 additions and 809 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
README.md
View File

@ -1,3 +1,11 @@
# 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")
@ -8,14 +16,28 @@ 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, Express, etc
Greenlock Express is a **Web Server** with **Fully Automated HTTPS** and renewals.
```js ```js
var pkg = require("./package.json");
require("greenlock-express") require("greenlock-express")
.init(function getConfig() { .init(function getConfig() {
return { package: require("./package.json") }; // Greenlock Config
return {
package: { name: pkg.name, version: pkg.version },
maintainerEmail: pkg.author,
cluster: false
};
}) })
.serve(httpsWorker); .serve(httpsWorker);
```
function httpsWorker(server) { With **Express**:
```js
function httpsWorker(glx) {
// Works with any Node app (Express, etc) // Works with any Node app (Express, etc)
var app = require("./my-express-app.js"); var app = require("./my-express-app.js");
@ -26,12 +48,27 @@ function httpsWorker(server) {
// Serves on 80 and 443 // Serves on 80 and 443
// Get's SSL certificates magically! // Get's SSL certificates magically!
server.serveApp(app); glx.serveApp(app);
}
```
Or with **plain** node HTTP:
```js
function httpsWorker(glx) {
// Serves on 80 and 443
// Get's SSL certificates magically!
glx.serveApp(function(req, res) {
res.end("Hello, Encrypted World!");
});
} }
``` ```
Manage via API or the config file: Manage via API or the config file:
`~/.config/greenlock/manage.json`: (default filesystem config)
```json ```json
{ {
"subscriberEmail": "letsencrypt-test@therootcompany.com", "subscriberEmail": "letsencrypt-test@therootcompany.com",
@ -75,25 +112,32 @@ Manage via API or the config file:
# 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.js) - [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.js) - [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.js) - [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.js) - [**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.js) - [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/socket-io.js) - [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/README.md) - [**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/README.md) - [**Localhost**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/) (coming soon)
- [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/README.md) - [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/) (coming soon)
- [HTTP Proxy](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http-proxy/)
# Easy to Customize # Easy to Customize
<!-- greenlock-manager-test => greenlock-manager-custom --> <!-- greenlock-manager-test => greenlock-manager-custom -->
<!--
- [greenlock.js/examples/](https://git.rootprojects.org/root/greenlock.js/src/branch/master/examples) - [greenlock.js/examples/](https://git.rootprojects.org/root/greenlock.js/src/branch/master/examples)
- [Custom Domain Management](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/custom-manager/README.md) -->
- [Custom Key & Cert Storage](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/custom-store/README.md)
- [Custom ACME Challenges](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/custom-acme-challenges/README.md) - [Custom Domain Management](https://git.rootprojects.org/root/greenlock-manager-test.js)
- [Custom Key & Cert Storage](https://git.rootprojects.org/root/greenlock-store-test.js)
- [Custom ACME HTTP-01 Challenges](https://git.rootprojects.org/root/acme-http-01-test.js)
- [Custom ACME DNS-01 Challenges](https://git.rootprojects.org/root/acme-dns-01-test.js)
# QuickStart Guide # QuickStart Guide
@ -198,30 +242,13 @@ Listening on 0.0.0.0:443 for secure traffic
## 4. Manage domains ## 4. Manage domains
Management can be done via the **CLI** or the JavaScript [**API**](https://git.rootprojects.org/root/greenlock.js/). The management API is built to work with Databases, S3, etc.
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. HOWEVER, by default it starts with a simple config file.
All individuals, and most businesses, should set this globally:
```bash
# Set a global subscriber account
npx greenlock config --subscriber-email 'mycompany@example.com' --agree-to-terms true
```
<!-- todo print where the key was saved -->
A Let's Encrypt SSL certificate has a "Subject" (Primary Domain) and up to 100 "Alternative Names"
(of which the first _must_ be the subject).
```bash
# Add a certificate with specific domains
npx greenlock add --subject example.com --altnames example.com,www.example.com
```
<!-- todo print where the cert was saved -->
<!--
This will update the config file (assuming the default fs-based management plugin): This will update the config file (assuming the default fs-based management plugin):
-->
`~/.config/greenlock/manager.json`: `~/.config/greenlock/manager.json`:
@ -238,13 +265,46 @@ This will update the config file (assuming the default fs-based management plugi
} }
``` ```
COMING SOON
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
```
<!-- todo print where the key was saved -->
A Let's Encrypt SSL certificate has a "Subject" (Primary Domain) and up to 100 "Alternative Names"
(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
```
<!-- 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
[**DNS validation**](https://git.rootprojects.org/root/greenlock-exp). [**DNS validation**](https://git.rootprojects.org/root/greenlock-exp).
- DNS Validation - DNS Validation
- [**Wildcards**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcards/README.md) - [**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/README.md) - [**Localhost**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/) (coming soon)
- [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/README.md) - [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/) (coming soon)
# Full Documentation # Full Documentation

39
examples/cluster/server.js Normal file
View File

@ -0,0 +1,39 @@
"use strict";
var pkg = require("../../package.json");
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
package: { name: "websocket-example", version: pkg.version },
maintainerEmail: "jon@example.com",
// When you're ready to go full cloud scale, you just change this to true:
// Note: in cluster you CANNOT use in-memory state (see below)
cluster: true,
// This will default to the number of workers being equal to
// n-1 cpus, with a minimum of 2
workers: 4
};
})
.serve(httpsWorker);
function httpsWorker(glx) {
// WRONG
// This won't work like you
// think because EACH worker
// has ITS OWN `count`.
var count = 0;
var app = function(req, res) {
res.end("Hello... how many times now? Oh, " + count + " times");
count += 1;
};
// Serves on 80 and 443... for each worker
// Get's SSL certificates magically!
glx.serveApp(app);
}

75
examples/demo.js
View File

@ -1,75 +0,0 @@
"use strict";
// npm install spdy@3.x
//var Greenlock = require('greenlock-express')
var Greenlock = require("../");
var greenlock = Greenlock.create({
// Let's Encrypt v2 is ACME draft 11
version: "draft-11",
server: "https://acme-v02.api.letsencrypt.org/directory",
// Note: If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
// You MUST change this to a valid email address
email: "jon@example.com",
// You MUST NOT build clients that accept the ToS without asking the user
agreeTos: true,
// You MUST change these to valid domains
// NOTE: all domains will validated and listed on the certificate
approvedDomains: ["example.com", "www.example.com"],
// You MUST have access to write to directory where certs are saved
// ex: /home/foouser/acme/etc
configDir: "~/.config/acme/",
// Get notified of important updates and help me make greenlock better
communityMember: true
//, debug: true
});
////////////////////////
// http-01 Challenges //
////////////////////////
// http-01 challenge happens over http/1.1, not http2
var redirectHttps = require("redirect-https")();
var acmeChallengeHandler = greenlock.middleware(function(req, res) {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.end(
"<h1>Hello, ⚠️ Insecure World!</h1><a>Visit Secure Site</a>" +
'<script>document.querySelector("a").href=window.location.href.replace(/^http/i, "https");</script>'
);
});
require("http")
.createServer(acmeChallengeHandler)
.listen(80, function() {
console.log("Listening for ACME http-01 challenges on", this.address());
});
////////////////////////
// http2 via SPDY h2 //
////////////////////////
// spdy is a drop-in replacement for the https API
var spdyOptions = Object.assign({}, greenlock.tlsOptions);
spdyOptions.spdy = { protocols: ["h2", "http/1.1"], plain: false };
var server = require("spdy").createServer(
spdyOptions,
require("express")().use("/", function(req, res) {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.end("<h1>Hello, 🔐 Secure World!</h1>");
})
);
server.on("error", function(err) {
console.error(err);
});
server.on("listening", function() {
console.log("Listening for SPDY/http2/https requests on", this.address());
});
server.listen(443);

0
examples/my-express-app.js → examples/express/my-express-app.js
View File

27
examples/express/server.js Normal file
View File

@ -0,0 +1,27 @@
"use strict";
function httpsWorker(glx) {
var app = require("./my-express-app.js");
app.get("/hello", function(req, res) {
res.end("Hello, Encrypted World!");
});
// Serves on 80 and 443
// Get's SSL certificates magically!
glx.serveApp(app);
}
var pkg = require("../../package.json");
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
package: { name: "http2-example", version: pkg.version },
maintainerEmail: "jon@example.com",
cluster: false
};
})
.serve(httpsWorker);

30
examples/force-renew.js
View File

@ -1,30 +0,0 @@
"use strict";
//require('greenlock-express')
require("../")
.create({
// Let's Encrypt v2 is ACME draft 11
version: "draft-11",
server: "https://acme-v02.api.letsencrypt.org/directory",
// Note: If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
email: "john.doe@example.com",
agreeTos: true,
approvedDomains: ["example.com", "www.example.com"],
app: require("express")().use("/", function(req, res) {
res.end("Hello, World!");
}),
renewWithin: 91 * 24 * 60 * 60 * 1000,
renewBy: 90 * 24 * 60 * 60 * 1000,
// Get notified of important updates and help me make greenlock better
communityMember: true,
debug: true
})
.listen(80, 443);

27
examples/http-proxy.js → examples/http-proxy/server.js
View File

@ -1,16 +1,9 @@
"use strict"; "use strict";
require("@root/greenlock-express")
.init(function getConfig() {
return { package: require("../package.json") };
})
.serve(httpsWorker);
function httpsWorker(glx) { function httpsWorker(glx) {
var proxy = require("http-proxy").createProxyServer({ xfwd: true });
// we need the raw https server // we need the raw https server
var server = glx.httpsServer(); var server = glx.httpsServer();
var proxy = require("http-proxy").createProxyServer({ xfwd: true });
// catches error events during proxying // catches error events during proxying
proxy.on("error", function(err, req, res) { proxy.on("error", function(err, req, res) {
@ -20,11 +13,11 @@ function httpsWorker(glx) {
return; return;
}); });
// We'll proxy websocketts too // We'll proxy websockets too
server.on("upgrade", function(req, socket, head) { server.on("upgrade", function(req, socket, head) {
proxy.ws(req, socket, head, { proxy.ws(req, socket, head, {
ws: true, ws: true,
target: "ws://localhost:1443" target: "ws://localhost:3000"
}); });
}); });
@ -35,3 +28,17 @@ function httpsWorker(glx) {
}); });
}); });
} }
var pkg = require("../../package.json");
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
package: { name: "http-proxy-example", version: pkg.version },
maintainerEmail: "jon@example.com",
cluster: false
};
})
.serve(httpsWorker);

42
examples/http/server.js Normal file
View File

@ -0,0 +1,42 @@
"use strict";
var pkg = require("../../package.json");
// The WRONG way:
//var http = require('http');
//var httpServer = https.createSecureServer(redirectToHttps);
//
// Why is that wrong?
// Greenlock needs to change some low-level http and https options.
// Use glx.httpServer(redirectToHttps) instead.
function httpsWorker(glx) {
//
// HTTP can only be used for ACME HTTP-01 Challenges
// (and it is not required for DNS-01 challenges)
//
// Get the raw http server:
var httpServer = glx.httpServer(function(req, res) {
res.statusCode = 301;
res.setHeader("Location", "https://" + req.headers.host + req.path);
res.end("Insecure connections are not allowed. Redirecting...");
});
httpServer.listen(80, "0.0.0.0", function() {
console.info("Listening on ", httpServer.address());
});
}
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
package: { name: "plain-http-example", version: pkg.version },
maintainerEmail: "jon@example.com",
cluster: false
};
})
.serve(httpsWorker);

70
examples/http2.js
View File

@ -1,70 +0,0 @@
"use strict";
//var Greenlock = require('greenlock-express')
var Greenlock = require("../");
var greenlock = Greenlock.create({
// Let's Encrypt v2 is ACME draft 11
version: "draft-11",
server: "https://acme-v02.api.letsencrypt.org/directory",
// Note: If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
// You MUST change this to a valid email address
email: "jon@example.com",
// You MUST NOT build clients that accept the ToS without asking the user
agreeTos: true,
// You MUST change these to valid domains
// NOTE: all domains will validated and listed on the certificate
approvedDomains: ["example.com", "www.example.com"],
// You MUST have access to write to directory where certs are saved
// ex: /home/foouser/acme/etc
configDir: "~/.config/acme/",
// Get notified of important updates and help me make greenlock better
communityMember: true
//, debug: true
});
////////////////////////
// http-01 Challenges //
////////////////////////
// http-01 challenge happens over http/1.1, not http2
var redirectHttps = require("redirect-https")();
var acmeChallengeHandler = greenlock.middleware(redirectHttps);
require("http")
.createServer(acmeChallengeHandler)
.listen(80, function() {
console.log("Listening for ACME http-01 challenges on", this.address());
});
////////////////////////
// node.js' http2 api //
////////////////////////
// http2 is a new API with which you would use hapi or koa, not express
var server = require("http2").createSecureServer(greenlock.tlsOptions);
server.on("error", function(err) {
console.error(err);
});
// WARNING: Because the middleware don't handle this API style,
// the Host headers are unmodified and potentially dangerous
// (ex: Host: Robert'); DROP TABLE Students;)
server.on("stream", function(stream, headers) {
console.log(headers);
stream.respond({
"content-type": "text/html",
":status": 200
});
stream.end("Hello, HTTP2 World!");
});
server.on("listening", function() {
console.log("Listening for http2 requests on", this.address());
});
server.listen(443);

48
examples/http2/server.js Normal file
View File

@ -0,0 +1,48 @@
"use strict";
var pkg = require("../../package.json");
// The WRONG way:
//var http2 = require('http2');
//var http2Server = https.createSecureServer(tlsOptions, app);
//
// Why is that wrong?
// Greenlock needs to change some low-level http and https options.
// Use glx.httpsServer(tlsOptions, app) instead.
function httpsWorker(glx) {
//
// HTTP2 is the default httpsServer for node v12+
// (HTTPS/1.1 is used for node <= v11)
//
// Get the raw http2 server:
var http2Server = glx.httpsServer(function(req, res) {
res.end("Hello, Encrypted World!");
});
http2Server.listen(443, "0.0.0.0", function() {
console.info("Listening on ", http2Server.address());
});
// Note:
// You must ALSO listen on port 80 for ACME HTTP-01 Challenges
// (the ACME and http->https middleware are loaded by glx.httpServer)
var httpServer = glx.httpServer();
httpServer.listen(80, "0.0.0.0", function() {
console.info("Listening on ", httpServer.address());
});
}
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
package: { name: "http2-example", version: pkg.version },
maintainerEmail: "jon@example.com",
cluster: false
};
})
.serve(httpsWorker);

49
examples/https/server.js Normal file
View File

@ -0,0 +1,49 @@
"use strict";
var pkg = require("../../package.json");
// The WRONG way:
//var https = require('https');
//var httpsServer = https.createServer(tlsOptions, app);
//
// Why is that wrong?
// Greenlock needs to change some low-level http and https options.
// Use glx.httpsServer(tlsOptions, app) instead.
function httpsWorker(glx) {
//
// HTTPS/1.1 is only used for node v11 or lower
// (HTTP2 is used for node v12+)
//
// Why not just require('https')?
// Get the raw https server:
var httpsServer = glx.httpsServer(null, function(req, res) {
res.end("Hello, Encrypted World!");
});
httpsServer.listen(443, "0.0.0.0", function() {
console.info("Listening on ", httpsServer.address());
});
// Note:
// You must ALSO listen on port 80 for ACME HTTP-01 Challenges
// (the ACME and http->https middleware are loaded by glx.httpServer)
var httpServer = glx.httpServer();
httpServer.listen(80, "0.0.0.0", function() {
console.info("Listening on ", httpServer.address());
});
}
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
package: { name: "https1-example", version: pkg.version },
maintainerEmail: "jon@example.com",
cluster: false
};
})
.serve(httpsWorker);

88
examples/production.js
View File

@ -1,88 +0,0 @@
"use strict";
//
// My Secure Server
//
//var greenlock = require('greenlock-express')
var greenlock = require("../").create({
// Let's Encrypt v2 is ACME draft 11
// Note: If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
server: "https://acme-v02.api.letsencrypt.org/directory",
version: "draft-11",
// You MUST have write access to save certs
configDir: "~/.config/acme/",
// The previous 'simple' example set these values statically,
// but this example uses approveDomains() to set them dynamically
//, email: 'none@see.note.above'
//, agreeTos: false
// approveDomains is the right place to check a database for
// email addresses with domains and agreements and such
approveDomains: approveDomains,
app: require("./my-express-app.js"),
// Get notified of important updates and help me make greenlock better
communityMember: true
//, debug: true
});
var server = greenlock.listen(80, 443);
//
// My Secure Database Check
//
function approveDomains(opts, certs, cb) {
// Only one domain is listed with *automatic* registration via SNI
// (it's an array because managed registration allows for multiple domains,
// which was the case in the simple example)
console.log(opts.domains);
// The domains being approved for the first time are listed in opts.domains
// Certs being renewed are listed in certs.altnames
if (certs) {
opts.domains = [certs.subject].concat(certs.altnames);
}
fooCheckDb(opts.domains, function(err, agree, email) {
if (err) {
cb(err);
return;
}
// Services SHOULD automatically accept the ToS and use YOUR email
// Clients MUST NOT accept the ToS without asking the user
opts.agreeTos = agree;
opts.email = email;
// NOTE: you can also change other options such as `challengeType` and `challenge`
// (this would be helpful if you decided you wanted wildcard support as a domain altname)
// opts.challengeType = 'http-01';
// opts.challenge = require('le-challenge-fs').create({});
cb(null, { options: opts, certs: certs });
});
}
//
// My User / Domain Database
//
function fooCheckDb(domains, cb) {
// This is an oversimplified example of how we might implement a check in
// our database if we have different rules for different users and domains
var domains = ["example.com", "www.example.com"];
var userEmail = "john.doe@example.com";
var userAgrees = true;
var passCheck = opts.domains.every(function(domain) {
return -1 !== domains.indexOf(domain);
});
if (!passCheck) {
cb(new Error("domain not allowed"));
} else {
cb(null, userAgrees, userEmail);
}
}

38
examples/quickstart.js
View File

@ -1,38 +0,0 @@
"use strict";
//require('greenlock-express')
require("../")
.create({
// Let's Encrypt v2 is ACME draft 11
version: "draft-11",
server: "https://acme-v02.api.letsencrypt.org/directory",
// Note: If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
// You MUST change this to a valid email address
email: "john.doe@example.com",
// You MUST NOT build clients that accept the ToS without asking the user
agreeTos: true,
// You MUST change these to valid domains
// NOTE: all domains will validated and listed on the certificate
approvedDomains: ["example.com", "www.example.com"],
// You MUST have access to write to directory where certs are saved
// ex: /home/foouser/acme/etc
configDir: "~/.config/acme/",
store: require("greenlock-store-fs"),
app: require("express")().use("/", function(req, res) {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.end("Hello, World!\n\n💚 🔒.js");
}),
// Get notified of important updates and help me make greenlock better
communityMember: true
//, debug: true
})
.listen(80, 443);

22
examples/quickstart/README.md Normal file
View File

@ -0,0 +1,22 @@
# Quick Start for Let's Encrypt with Node.js
```js
npm install --save greenlock-express
```
Manage via API or the config file:
`~/.config/greenlock/manage.json`: (default filesystem config)
```json
{
"subscriberEmail": "letsencrypt-test@therootcompany.com",
"agreeToTerms": true,
"sites": {
"example.com": {
"subject": "example.com",
"altnames": ["example.com", "www.example.com"]
}
}
}
```

32
examples/quickstart/server.js Normal file
View File

@ -0,0 +1,32 @@
"use strict";
function httpsWorker(glx) {
// This can be a node http app (shown),
// an Express app, or Hapi, Koa, Rill, etc
var app = function(req, res) {
res.end("Hello, Encrypted World!");
};
// Serves on 80 and 443
// Get's SSL certificates magically!
glx.serveApp(app);
}
var pkg = require("../../package.json");
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
// Package name+version is used for ACME client user agent
package: { name: "websocket-example", version: pkg.version },
// Maintainer email is the contact for critical bug and security notices
maintainerEmail: "jon@example.com",
// Change to true when you're ready to make your app cloud-scale
cluster: false
};
})
.serve(httpsWorker);

104
examples/remote-access.js
View File

@ -1,104 +0,0 @@
"use strict";
//
// WARNING: Not for noobs
// Try the simple example first
//
//
// This demo is used with tunnel-server.js and tunnel-client.js
//
var email = "john.doe@gmail.com";
var domains = ["example.com"];
var agreeLeTos = true;
//var secret = "My Little Brony";
var secret = require("crypto")
.randomBytes(16)
.toString("hex");
require("../")
.create({
version: "draft-11",
server: "https://acme-v02.api.letsencrypt.org/directory",
// Note: If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
email: email,
agreeTos: agreeLeTos,
approveDomains: domains,
configDir: "~/.config/acme/",
app: remoteAccess(secret),
// Get notified of important updates and help me make greenlock better
communityMember: true
//, debug: true
})
.listen(3000, 8443);
function remoteAccess(secret) {
var express = require("express");
var basicAuth = require("express-basic-auth");
var serveIndex = require("serve-index");
var rootIndex = serveIndex("/", { hidden: true, icons: true, view: "details" });
var rootFs = express.static("/", { dotfiles: "allow", redirect: true, index: false });
var userIndex = serveIndex(require("os").homedir(), { hidden: true, icons: true, view: "details" });
var userFs = express.static(require("os").homedir(), { dotfiles: "allow", redirect: true, index: false });
var app = express();
var realm = "Login Required";
var myAuth = basicAuth({
users: { root: secret, user: secret },
challenge: true,
realm: realm,
unauthorizedResponse: function(/*req*/) {
return 'Unauthorized <a href="/">Home</a>';
}
});
app.get("/", function(req, res) {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.end('<a href="/browse/">View Files</a>' + "&nbsp; | &nbsp;" + '<a href="/logout/">Logout</a>');
});
app.use("/logout", function(req, res) {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.setHeader("WWW-Authenticate", 'Basic realm="' + realm + '"');
res.statusCode = 401;
//res.setHeader('Location', '/');
res.end('Logged out &nbsp; | &nbsp; <a href="/">Home</a>');
});
app.use("/browse", myAuth);
app.use("/browse", function(req, res, next) {
if ("root" === req.auth.user) {
rootFs(req, res, function() {
rootIndex(req, res, next);
});
return;
}
if ("user" === req.auth.user) {
userFs(req, res, function() {
userIndex(req, res, next);
});
return;
}
res.end("Sad Panda");
});
console.log("");
console.log("");
console.log("Usernames are\n");
console.log("\troot");
console.log("\tuser");
console.log("");
console.log("Password (for both) is\n");
console.log("\t" + secret);
console.log("");
console.log("Shhhh... It's a secret to everybody!");
console.log("");
console.log("");
return app;
}

32
examples/socket.io.js
View File

@ -1,32 +0,0 @@
// First and foremost:
// I'm not a fan of `socket.io` because it's huge and complex.
// I much prefer `ws` because it's very simple and easy.
// That said, it's popular.......
"use strict";
//var greenlock = require('greenlock-express');
var greenlock = require("../");
var options = require("./greenlock-options.js");
var socketio = require("socket.io");
var server;
var io;
// Any node http app will do - whether express, raw http or whatever
options.app = require("express")().use("/", function(req, res) {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.end("Hello, World!\n\n💚 🔒.js");
});
// The server that's handed back from `listen` is a raw https server
server = greenlock.create(options).listen(80, 443);
io = socketio(server);
// Then you do your socket.io stuff
io.on("connection", function(socket) {
console.log("a user connected");
socket.emit("Welcome");
socket.on("chat message", function(msg) {
socket.broadcast.emit("chat message", msg);
});
});

49
examples/socket.io/server.js Normal file
View File

@ -0,0 +1,49 @@
// First and foremost:
// I'm not a fan of `socket.io` because it's huge and complex.
// I much prefer `ws` because it's very simple and easy.
// That said, it's popular.......
"use strict";
// Note: You DO NOT NEED socket.io
// You can just use WebSockets
// (see the websocket example)
function httpsWorker(glx) {
var socketio = require("socket.io");
var io;
// we need the raw https server
var server = glx.httpsServer();
io = socketio(server);
// Then you do your socket.io stuff
io.on("connection", function(socket) {
console.log("a user connected");
socket.emit("Welcome");
socket.on("chat message", function(msg) {
socket.broadcast.emit("chat message", msg);
});
});
// servers a node app that proxies requests to a localhost
glx.serveApp(function(req, res) {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.end("Hello, World!\n\n💚 🔒.js");
});
}
var pkg = require("../../package.json");
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
package: { name: "socket-io-example", version: pkg.version },
maintainerEmail: "jon@example.com",
cluster: false
};
})
.serve(httpsWorker);

64
examples/spdy.js
View File

@ -1,64 +0,0 @@
"use strict";
// npm install spdy@3.x
//var Greenlock = require('greenlock-express')
var Greenlock = require("../");
var greenlock = Greenlock.create({
// Let's Encrypt v2 is ACME draft 11
version: "draft-11",
server: "https://acme-v02.api.letsencrypt.org/directory",
// Note: If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
// You MUST change this to a valid email address
email: "jon@example.com",
// You MUST NOT build clients that accept the ToS without asking the user
agreeTos: true,
// You MUST change these to valid domains
// NOTE: all domains will validated and listed on the certificate
approvedDomains: ["example.com", "www.example.com"],
// You MUST have access to write to directory where certs are saved
// ex: /home/foouser/acme/etc
configDir: "~/.config/acme/", // MUST have write access
// Get notified of important updates and help me make greenlock better
communityMember: true
//, debug: true
});
////////////////////////
// http-01 Challenges //
////////////////////////
// http-01 challenge happens over http/1.1, not http2
var redirectHttps = require("redirect-https")();
var acmeChallengeHandler = greenlock.middleware(redirectHttps);
require("http")
.createServer(acmeChallengeHandler)
.listen(80, function() {
console.log("Listening for ACME http-01 challenges on", this.address());
});
////////////////////////
// http2 via SPDY h2 //
////////////////////////
// spdy is a drop-in replacement for the https API
var spdyOptions = Object.assign({}, greenlock.tlsOptions);
spdyOptions.spdy = { protocols: ["h2", "http/1.1"], plain: false };
var myApp = require("./my-express-app.js");
var server = require("spdy").createServer(spdyOptions, myApp);
server.on("error", function(err) {
console.error(err);
});
server.on("listening", function() {
console.log("Listening for SPDY/http2/https requests on", this.address());
});
server.listen(443);

3
examples/spdy/server.js Normal file
View File

@ -0,0 +1,3 @@
// SPDY is dead. It was replaced by HTTP2, which is a native node module
//
// Greenlock uses HTTP2 as the default https server in node v12+

134
examples/vhost.js
View File

@ -1,134 +0,0 @@
#!/usr/bin/env node
"use strict";
///////////////////
// vhost example //
///////////////////
//
// virtual hosting example
//
// The prefix where sites go by name.
// For example: whatever.com may live in /srv/www/whatever.com, thus /srv/www is our path
var srv = process.argv[3] || "/srv/www/";
var path = require("path");
var fs = require("fs").promises;
var finalhandler = require("finalhandler");
var serveStatic = require("serve-static");
//var glx = require('greenlock-express')
var glx = require("./").create({
version: "draft-11", // Let's Encrypt v2 is ACME draft 11
server: "https://acme-v02.api.letsencrypt.org/directory", // If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
configDir: process.argv[4] || "~/.config/acme/", // You MUST have access to write to directory where certs
// are saved. ex: /home/foouser/.config/acme
approveDomains: myApproveDomains, // Greenlock's wraps around tls.SNICallback. Check the
// domain name here and reject invalid ones
app: myVhostApp, // Any node-style http app (i.e. express, koa, hapi, rill)
/* CHANGE TO A VALID EMAIL */
email: process.argv[2] || "jon.doe@example.com", // Email for Let's Encrypt account and Greenlock Security
agreeTos: true // Accept Let's Encrypt ToS
//, communityMember: true // Join Greenlock to get important updates, no spam
//, debug: true
});
var server = glx.listen(80, 443);
server.on("listening", function() {
console.info(server.type + " listening on", server.address());
});
function myApproveDomains(opts, certs, cb) {
console.log("sni:", opts.domain);
// In this example the filesystem is our "database".
// We check in /srv/www for whatever.com and if it exists, it's allowed
// SECURITY Greenlock validates opts.domains ahead-of-time so you don't have to
return checkWwws(opts.domains[0])
.then(function() {
//opts.email = email;
opts.agreeTos = true;
cb(null, { options: opts, certs: certs });
})
.catch(cb);
}
function checkWwws(_hostname) {
if (!_hostname) {
// SECURITY, don't allow access to the 'srv' root
// (greenlock-express uses middleware to check '..', etc)
return "";
}
var hostname = _hostname;
var _hostdir = path.join(srv, hostname);
var hostdir = _hostdir;
// TODO could test for www/no-www both in directory
return fs
.readdir(hostdir)
.then(function() {
// TODO check for some sort of htaccess.json and use email in that
// NOTE: you can also change other options such as `challengeType` and `challenge`
// opts.challengeType = 'http-01';
// opts.challenge = require('le-challenge-fs').create({});
return hostname;
})
.catch(function() {
if ("www." === hostname.slice(0, 4)) {
// Assume we'll redirect to non-www if it's available.
hostname = hostname.slice(4);
hostdir = path.join(srv, hostname);
return fs.readdir(hostdir).then(function() {
// TODO list both domains?
return hostname;
});
} else {
// Or check and see if perhaps we should redirect non-www to www
hostname = "www." + hostname;
hostdir = path.join(srv, hostname);
return fs.readdir(hostdir).then(function() {
// TODO list both domains?
return hostname;
});
}
})
.catch(function() {
throw new Error("rejecting '" + _hostname + "' because '" + _hostdir + "' could not be read");
});
}
function myVhostApp(req, res) {
// SECURITY greenlock pre-sanitizes hostnames to prevent unauthorized fs access so you don't have to
// (also: only domains approved above will get here)
console.log("vhost:", req.headers.host);
if (!req.headers.host) {
// SECURITY, don't allow access to the 'srv' root
// (greenlock-express uses middleware to check '..', etc)
return res.end();
}
// We could cache wether or not a host exists for some amount of time
var fin = finalhandler(req, res);
return checkWwws(req.headers.host)
.then(function(hostname) {
if (hostname !== req.headers.host) {
res.statusCode = 302;
res.setHeader("Location", "https://" + hostname);
// SECURITY this is safe only because greenlock disallows invalid hostnames
res.end("<!-- redirecting to https://" + hostname + "-->");
return;
}
var serve = serveStatic(path.join(srv, hostname), { redirect: true });
serve(req, res, fin);
})
.catch(function() {
fin();
});
}

46
examples/websockets.js
View File

@ -1,46 +0,0 @@
"use strict";
////////////////////////
// Greenlock Setup //
////////////////////////
//var Greenlock = require('greenlock-express');
var Greenlock = require("../");
var greenlock = Greenlock.create({
// Let's Encrypt v2 is ACME draft 11
// Note: If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
server: "https://acme-v02.api.letsencrypt.org/directory",
version: "draft-11",
configDir: "~/.config/acme/",
app: require("./my-express-app.js"),
// You MUST change these to a valid email and domains
email: "john.doe@example.com",
approvedDomains: ["example.com", "www.example.com"],
agreeTos: true,
// Get notified of important updates and help me make greenlock better
communityMember: true,
telemetry: true
//, debug: true
});
var server = greenlock.listen(80, 443);
var WebSocket = require("ws");
var ws = new WebSocket.Server({ server: server });
ws.on("connection", function(ws, req) {
// inspect req.headers.authorization (or cookies) for session info
ws.send(
"[Secure Echo Server] Hello!\nAuth: '" +
(req.headers.authorization || "none") +
"'\n" +
"Cookie: '" +
(req.headers.cookie || "none") +
"'\n"
);
ws.on("message", function(data) {
ws.send(data);
});
});

42
examples/websockets/server.js Normal file
View File

@ -0,0 +1,42 @@
"use strict";
function httpsWorker(glx) {
// we need the raw https server
var server = glx.httpsServer();
var WebSocket = require("ws");
var ws = new WebSocket.Server({ server: server });
ws.on("connection", function(ws, req) {
// inspect req.headers.authorization (or cookies) for session info
ws.send(
"[Secure Echo Server] Hello!\nAuth: '" +
(req.headers.authorization || "none") +
"'\n" +
"Cookie: '" +
(req.headers.cookie || "none") +
"'\n"
);
ws.on("message", function(data) {
ws.send(data);
});
});
// servers a node app that proxies requests to a localhost
glx.serveApp(function(req, res) {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.end("Hello, World!\n\n💚 🔒.js");
});
}
var pkg = require("../../package.json");
//require("greenlock-express")
require("../../")
.init(function getConfig() {
// Greenlock Config
return {
package: { name: "websocket-example", version: pkg.version },
maintainerEmail: "jon@example.com",
cluster: false
};
})
.serve(httpsWorker);

77
examples/wildcard.js
View File

@ -1,77 +0,0 @@
#!/usr/bin/env node
"use strict";
/*global Promise*/
///////////////////////
// wildcard example //
//////////////////////
//
// wildcard example
//
//var glx = require('greenlock-express')
var glx = require("../").create({
version: "draft-11", // Let's Encrypt v2 is ACME draft 11
server: "https://acme-staging-v02.api.letsencrypt.org/directory",
//, server: 'https://acme-v02.api.letsencrypt.org/directory' // If at first you don't succeed, stop and switch to staging
// https://acme-staging-v02.api.letsencrypt.org/directory
configDir: "~/acme/", // You MUST have access to write to directory where certs
// are saved. ex: /home/foouser/.config/acme
approveDomains: myApproveDomains, // Greenlock's wraps around tls.SNICallback. Check the
// domain name here and reject invalid ones
app: require("./my-express-app.js"), // Any node-style http app (i.e. express, koa, hapi, rill)
/* CHANGE TO A VALID EMAIL */
email: "jon.doe@example.com", // Email for Let's Encrypt account and Greenlock Security
agreeTos: true, // Accept Let's Encrypt ToS
communityMember: true, // Join Greenlock to (very rarely) get important updates
//, debug: true
store: require("le-store-fs")
});
var server = glx.listen(80, 443);
server.on("listening", function() {
console.info(server.type + " listening on", server.address());
});
function myApproveDomains(opts) {
console.log("sni:", opts.domain);
// must be 'example.com' or start with 'example.com'
if (
"example.com" !== opts.domain &&
"example.com" !==
opts.domain
.split(".")
.slice(1)
.join(".")
) {
return Promise.reject(new Error("we don't serve your kind here: " + opts.domain));
}
// the primary domain for the cert
opts.subject = "example.com";
// the altnames (including the primary)
opts.domains = [opts.subject, "*.example.com"];
if (!opts.challenges) {
opts.challenges = {};
}
opts.challenges["http-01"] = require("le-challenge-fs").create({});
// Note: When implementing a dns-01 plugin you should make it check in a loop
// until it can positively confirm that the DNS changes have propagated.
// That could take several seconds to a few minutes.
opts.challenges["dns-01"] = require("le-challenge-dns").create({});
// explicitly set account id and certificate.id
opts.account = { id: opts.email };
opts.certificate = { id: opts.subject };
return Promise.resolve(opts);
}

2
master.js
View File

@ -66,7 +66,7 @@ Master._spawnWorkers = function(opts, greenlock) {
// process rpc messages // process rpc messages
// start when dead // start when dead
var numWorkers = parseInt(opts.numWorkers, 10); var numWorkers = parseInt(opts.workers || opts.numWorkers, 10);
if (!numWorkers) { if (!numWorkers) {
if (numCpus <= 2) { if (numCpus <= 2) {
numWorkers = 2; numWorkers = 2;

2
package.json
View File

@ -1,6 +1,6 @@
{ {
"name": "@root/greenlock-express", "name": "@root/greenlock-express",
"version": "3.0.8", "version": "3.0.9",
"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",