From e6a008d498b009d2bf45443c05a67b1e644bf10b Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Fri, 10 Jan 2020 17:51:25 -0700 Subject: [PATCH] update docs --- README.md | 426 +++++++++---------------------- WALKTHROUGH.md | 252 ++++++++++++++++++ examples/cluster/package.json | 12 + examples/cluster/server.js | 25 +- examples/express/package.json | 12 + examples/express/server.js | 37 ++- examples/http-proxy/package.json | 12 + examples/http-proxy/server.js | 30 ++- examples/http/package.json | 12 + examples/http/server.js | 26 +- examples/http2/package.json | 12 + examples/http2/server.js | 27 +- examples/https/package.json | 12 + examples/https/server.js | 27 +- examples/quickstart/package.json | 12 + examples/quickstart/server.js | 49 ++-- examples/socket.io/package.json | 12 + examples/socket.io/server.js | 25 +- examples/websockets/package.json | 12 + examples/websockets/server.js | 25 +- 20 files changed, 596 insertions(+), 461 deletions(-) create mode 100644 WALKTHROUGH.md create mode 100644 examples/cluster/package.json create mode 100644 examples/express/package.json create mode 100644 examples/http-proxy/package.json create mode 100644 examples/http/package.json create mode 100644 examples/http2/package.json create mode 100644 examples/https/package.json create mode 100644 examples/quickstart/package.json create mode 100644 examples/socket.io/package.json create mode 100644 examples/websockets/package.json diff --git a/README.md b/README.md index 65c2d1d..89aa093 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,111 @@ # [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js) is Let's Encrypt for Node +| Built by [Root](https://therootcompany.com) for [Hub](https://rootprojects.org/hub/) | + ![Greenlock Logo](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo") -| Built by [Root](https://therootcompany.com) for [Hub](https://rootprojects.org/hub/) - -Free SSL, Automated HTTPS / HTTP2, served with Node via Express, Koa, hapi, etc. - -### Let's Encrypt for Node and Express (and Koa, hapi, rill, etc) +### Free SSL for Node Web Servers 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! +You define your app and let Greenlock handle issuing and renewing Free SSL Certificates. ```bash npm init -``` - -```bash npm install --save greenlock-express@v4 ``` +`server.js`: + +```js +"use strict"; + +var app = require("./app.js"); + +require("greenlock-express") + .init({ + packageRoot: __dirname, + configDir: "./greenlock.d", + + // contact for security and critical bug notices + maintainerEmail: "jon@example.com", + + // whether or not to run at cloudscale + cluster: false + }) + // Serves on 80 and 443 + // Get's SSL certificates magically! + .serve(app); +``` + +`./greenlock.d/config.json`: + +```json +{ "sites": [{ "subject": "example.com", "altnames": ["example.com"] }] } +``` + +# Let's Encrypt for... + +- IoT +- Enterprise On-Prem +- Local Development +- Home Servers +- Quitting Heroku + +# Features + +- [x] Let's Encrypt v2 (November 2019) + - [x] ACME Protocol (RFC 8555) + - [x] HTTP Validation (HTTP-01) + - [x] DNS Validation (DNS-01) + - [ ] ALPN Validation (TLS-ALPN-01) + - Need ALPN validation? [contact us](mailto:greenlock-support@therootcompany.com) +- [x] Automated HTTPS + - [x] Fully Automatic Renewals every 45 days + - [x] Free SSL + - [x] **Wildcard** SSL + - [x] **Localhost** certificates + - [x] HTTPS-enabled Secure **WebSockets** (`wss://`) + - [x] **Cloud-ready** with Node `cluster`. +- [x] Fully customizable + - [x] **Reasonable defaults** + - [x] Domain Management + - [x] Key and Certificate Management + - [x] ACME Challenge Plugins + +# Compatibility + +Works with _any_ node http app, including + +- [x] Express +- [x] Koa +- [x] hapi +- [x] rill +- [x] http2 +- [x] cluster +- [x] etc... + +# QuickStart: Serve Sites with Free SSL + +Easy as 1, 2, 3... 4 + +1. Create a Project with Greenlock Express + - `server.js` + - `app.js` +2. Setup the config file (or database) + - `greenlock.d/config.json` +3. Add Domains + - `npx greenlock add --subject example.com --altnames example.com` +4. Hello, World! + - `npm start -- --staging` + +```bash +npm init +npm install --save greenlock-express@v4 +``` + +You can use **local file storage** or a **database**. The default is to use file storage. + ```bash npx greenlock init --config-dir ./greenlock.d --maintainer-email 'jon@example.com' ``` @@ -101,303 +179,11 @@ Listening on 0.0.0.0:80 for ACME challenges and HTTPS redirects Listening on 0.0.0.0:443 for secure traffic ``` -# Let's Encrypt for... +## Walkthrough -- IoT -- Enterprise On-Prem -- Local Development -- Home Servers -- Quitting Heroku +Read the [WALKTHROUGH](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/WALKTHROUGH.md) -# Features - -- [x] Let's Encrypt v2 (November 2019) - - [x] ACME Protocol (RFC 8555) - - [x] HTTP Validation (HTTP-01) - - [x] DNS Validation (DNS-01) - - [ ] ALPN Validation (TLS-ALPN-01) - - Need ALPN validation? [contact us](mailto:greenlock-support@therootcompany.com) -- [x] Automated HTTPS - - [x] Fully Automatic Renewals every 45 days - - [x] Free SSL - - [x] **Wildcard** SSL - - [x] **Localhost** certificates - - [x] HTTPS-enabled Secure **WebSockets** (`wss://`) -- [x] Fully customizable - - [x] **Reasonable defaults** - - [x] Domain Management - - [x] Key and Certificate Management - - [x] ACME Challenge Plugins - -# QuickStart Guide - -Easy as 1, 2, 3... 4 - -
-1. Create a node project - -## 1. Create a node project - -Create an empty node project. - -Be sure to fill out the package name, version, and an author email. - -```bash -mkdir ~/my-project -pushd ~/my-project -npm init -``` - -
- -
-2. Create an http app (i.e. express) - -## 2. Create an http app (i.e. express) - -This example is shown with Express, but any node app will do. Greenlock -works with everything. -(or any node-style http app) - -`my-express-app.js`: - -```js -"use strict"; - -// A plain, node-style app - -function myPlainNodeHttpApp(req, res) { - res.end("Hello, Encrypted World!"); -} - -// Wrap that plain app in express, -// because that's what you're used to - -var express = require("express"); -var app = express(); -app.get("/", myPlainNodeHttpApp); - -// export the app normally -// do not .listen() - -module.exports = app; -``` - -
- -
-3. Serve with Greenlock Express - -## 3. Serve with Greenlock Express - -Greenlock Express is designed with these goals in mind: - -- Simplicity and ease-of-use -- Performance and scalability -- Configurability and control - -You can start with **near-zero configuration** and -slowly add options for greater performance and customization -later, if you need them. - -`server.js`: - -```js -"use strict"; - -//var pkg = require("./package.json"); -var app = require("./app.js"); - -require("greenlock-express") - .init({ - // name & version for ACME client user agent - //packageAgent: pkg.name + "/" + pkg.version, - - // contact for security and critical bug notices - maintainerEmail: pkg.author, - - // where to find .greenlockrc and set default paths - packageRoot: __dirname, - - // where config and certificate stuff go - configDir: "./greenlock.d", - - // whether or not to run at cloudscale - cluster: false - }) - .serve(app); -``` - -And start your server: - -```bash -# Allow non-root node to use ports 80 (HTTP) and 443 (HTTPS) -sudo setcap 'cap_net_bind_service=+ep' $(which node) -``` - -```bash -# `npm start` will call `node ./server.js` by default -npm start -``` - -```bash -# use --staging to use the development API until you're ready to get real certificates -npm start -- --staging -``` - -```txt -Greenlock v4.0.0 -Greenlock Config Dir/File: ./greenlock.d/config.json - -Listening on 0.0.0.0:80 for ACME challenges and HTTPS redirects -Listening on 0.0.0.0:443 for secure traffic -``` - -
- -
-4. Manage SSL Certificates and Domains - -## 4. Manage domains - -The management API is built to work with Databases, S3, etc. - -By default, it's just a simple config file and directory. - -```bash -# see which manager and what options are in use -cat .greenlockrc -``` - -
-Example Output - -```json -{ - "manager": { - "module": "@greenlock/manager" - }, - "configDir": "./greenlock.d" -} -``` - -
- -```bash -# show the global defaults -npx greenlock defaults -``` - -```js -var defaults = await greenlock.defaults(); -``` - -
-Example Output - -```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 -} -``` - -
- -```bash -# show per-site configs -npx greenlock config --subject example.com -``` - -```js -greenlock.sites.get({ subject: "example.com" }); -``` - -
-Example Output - -```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" - } - } - } -} -``` - -
- -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 -# Set a global subscriber account -npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true -``` - -```js -greenlock.manager.defaults({ - subscriberEmail: "mycompany@example.com", - agreeToTerms: true -}); -``` - - - -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 -``` - -```js -greenlock.sites.add({ - subject: "example.com", - altnames: ["example.com"] -}); -``` - - - -Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require -[**DNS validation**](https://git.rootprojects.org/root/greenlock-exp). - -- DNS Validation - - [**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) - - [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/) (coming soon) - -
- -# Plenty of Examples +# 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/) @@ -411,6 +197,22 @@ Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require - [**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/) +# Using a Database, S3, etc + +If you have a small site, the default file storage will work well for you. + +If you have many sites with many users, you'll probably want to store config in a database of some sort. + +See the section on **Custom** callbacks and plugins below. + +# Advanced Configuration + +All of the advanced configuration is done by replacing the default behavior with callbacks. + +You can whip up your own, or you can use something that's published to npm. + +See the section on **Custom** callbacks and plugins below. + # Easy to Customize diff --git a/WALKTHROUGH.md b/WALKTHROUGH.md new file mode 100644 index 0000000..8ec1640 --- /dev/null +++ b/WALKTHROUGH.md @@ -0,0 +1,252 @@ +# Greenlock Express Walkthrough + +This will show you the basics of how to + +1. Create a node project +2. Create an http app (i.e. express) +3. Serve with Greenlock Express +4. Manage SSL Certificates and Domains + +## 1. Create a node project + +Create an empty node project. + +Be sure to fill out the package name, version, and an author email. + +```bash +mkdir ~/my-project +pushd ~/my-project +npm init +``` + +## 2. Create an http app (i.e. express) + +This example is shown with Express, but any node app will do. Greenlock +works with everything. +(or any node-style http app) + +`my-express-app.js`: + +```js +"use strict"; + +// A plain, node-style app + +function myPlainNodeHttpApp(req, res) { + res.end("Hello, Encrypted World!"); +} + +// Wrap that plain app in express, +// because that's what you're used to + +var express = require("express"); +var app = express(); +app.get("/", myPlainNodeHttpApp); + +// export the app normally +// do not .listen() + +module.exports = app; +``` + +## 3. Serve with Greenlock Express + +Greenlock Express is designed with these goals in mind: + +- Simplicity and ease-of-use +- Performance and scalability +- Configurability and control + +You can start with **near-zero configuration** and +slowly add options for greater performance and customization +later, if you need them. + +`server.js`: + +```js +"use strict"; + +//var pkg = require("./package.json"); +var app = require("./app.js"); + +require("greenlock-express") + .init({ + // where to find .greenlockrc and set default paths + packageRoot: __dirname, + + // where config and certificate stuff go + configDir: "./greenlock.d", + + // contact for security and critical bug notices + maintainerEmail: pkg.author, + + // name & version for ACME client user agent + //packageAgent: pkg.name + "/" + pkg.version, + + // whether or not to run at cloudscale + cluster: false + }) + .serve(app); +``` + +And start your server: + +```bash +# Allow non-root node to use ports 80 (HTTP) and 443 (HTTPS) +sudo setcap 'cap_net_bind_service=+ep' $(which node) +``` + +```bash +# `npm start` will call `node ./server.js` by default +npm start +``` + +```bash +# use --staging to use the development API until you're ready to get real certificates +npm start -- --staging +``` + +```txt +Greenlock v4.0.0 +Greenlock Config Dir/File: ./greenlock.d/config.json + +Listening on 0.0.0.0:80 for ACME challenges and HTTPS redirects +Listening on 0.0.0.0:443 for secure traffic +``` + +## 4. Manage SSL Certificates and Domains + +The management API is built to work with Databases, S3, etc. + +By default, it's just a simple config file and directory. + +```bash +# see which manager and what options are in use +cat .greenlockrc +``` + +
+Example Output + +```json +{ + "manager": { + "module": "@greenlock/manager" + }, + "configDir": "./greenlock.d" +} +``` + +
+ +```bash +# show the global defaults +npx greenlock defaults +``` + +```js +var defaults = await greenlock.defaults(); +``` + +
+Example Output + +```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 +} +``` + +
+ +```bash +# show per-site configs +npx greenlock config --subject example.com +``` + +```js +greenlock.sites.get({ subject: "example.com" }); +``` + +
+Example Output + +```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" + } + } + } +} +``` + +
+ +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 +# Set a global subscriber account +npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true +``` + +```js +greenlock.manager.defaults({ + subscriberEmail: "mycompany@example.com", + agreeToTerms: true +}); +``` + + + +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 +``` + +```js +greenlock.sites.add({ + subject: "example.com", + altnames: ["example.com"] +}); +``` + + + +Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require +[**DNS validation**](https://git.rootprojects.org/root/greenlock-exp). + +- DNS Validation + - [**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) + - [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/) (coming soon) diff --git a/examples/cluster/package.json b/examples/cluster/package.json new file mode 100644 index 0000000..9f59e5f --- /dev/null +++ b/examples/cluster/package.json @@ -0,0 +1,12 @@ +{ + "name": "cluster-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/cluster/server.js b/examples/cluster/server.js index ba66dc2..f15adca 100644 --- a/examples/cluster/server.js +++ b/examples/cluster/server.js @@ -1,25 +1,22 @@ "use strict"; -var pkg = require("../../package.json"); //require("greenlock-express") require("../../") - .init(function getConfig() { - // Greenlock Config + .init({ + packageRoot: __dirname, + configDir: "./greenlock.d", - return { - package: { name: "websocket-example", version: pkg.version }, - maintainerEmail: "jon@example.com", + 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, + // 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 - }; + // This will default to the number of workers being equal to + // n-1 cpus, with a minimum of 2 + workers: 4 }) - .serve(httpsWorker); + .ready(httpsWorker); function httpsWorker(glx) { // WRONG diff --git a/examples/express/package.json b/examples/express/package.json new file mode 100644 index 0000000..18dcd2c --- /dev/null +++ b/examples/express/package.json @@ -0,0 +1,12 @@ +{ + "name": "express-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/express/server.js b/examples/express/server.js index 3242553..4753fd3 100644 --- a/examples/express/server.js +++ b/examples/express/server.js @@ -1,27 +1,22 @@ "use strict"; -function httpsWorker(glx) { - var app = require("./my-express-app.js"); +var app = require("./my-express-app.js"); - app.get("/hello", function(req, res) { - res.end("Hello, Encrypted World!"); - }); +app.get("/hello", function(req, res) { + res.end("Hello, Encrypted World!"); +}); + +//require("greenlock-express") +require("../../") + .init({ + packageRoot: __dirname, + configDir: "./greenlock.d", + + maintainerEmail: "jon@example.com", + + cluster: false + }) // 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); + .serve(app); diff --git a/examples/http-proxy/package.json b/examples/http-proxy/package.json new file mode 100644 index 0000000..c67dbfc --- /dev/null +++ b/examples/http-proxy/package.json @@ -0,0 +1,12 @@ +{ + "name": "http-proxy-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/http-proxy/server.js b/examples/http-proxy/server.js index c8bf342..337a6fa 100644 --- a/examples/http-proxy/server.js +++ b/examples/http-proxy/server.js @@ -1,5 +1,21 @@ "use strict"; +//require("greenlock-express") +require("../../") + .init(function getConfig() { + // Greenlock Config + + return { + packageRoot: __dirname, + configDir: "./greenlock.d", + + maintainerEmail: "jon@example.com", + + cluster: false + }; + }) + .ready(httpsWorker); + function httpsWorker(glx) { // we need the raw https server var server = glx.httpsServer(); @@ -28,17 +44,3 @@ 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); diff --git a/examples/http/package.json b/examples/http/package.json new file mode 100644 index 0000000..7a17e40 --- /dev/null +++ b/examples/http/package.json @@ -0,0 +1,12 @@ +{ + "name": "http-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/http/server.js b/examples/http/server.js index 8aa11bb..c9bc450 100644 --- a/examples/http/server.js +++ b/examples/http/server.js @@ -1,7 +1,5 @@ "use strict"; -var pkg = require("../../package.json"); - // The WRONG way: //var http = require('http'); //var httpServer = https.createSecureServer(redirectToHttps); @@ -10,6 +8,17 @@ var pkg = require("../../package.json"); // Greenlock needs to change some low-level http and https options. // Use glx.httpServer(redirectToHttps) instead. +//require("greenlock-express") +require("../../") + .init({ + packageRoot: __dirname, + configDir: "./greenlock.d", + + maintainerEmail: "jon@example.com", + cluster: false + }) + .ready(httpsWorker); + function httpsWorker(glx) { // // HTTP can only be used for ACME HTTP-01 Challenges @@ -27,16 +36,3 @@ function httpsWorker(glx) { 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); diff --git a/examples/http2/package.json b/examples/http2/package.json new file mode 100644 index 0000000..72ec1a9 --- /dev/null +++ b/examples/http2/package.json @@ -0,0 +1,12 @@ +{ + "name": "http2-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/http2/server.js b/examples/http2/server.js index 1d663f5..3da9882 100644 --- a/examples/http2/server.js +++ b/examples/http2/server.js @@ -1,7 +1,5 @@ "use strict"; -var pkg = require("../../package.json"); - // The WRONG way: //var http2 = require('http2'); //var http2Server = https.createSecureServer(tlsOptions, app); @@ -10,6 +8,17 @@ var pkg = require("../../package.json"); // Greenlock needs to change some low-level http and https options. // Use glx.httpsServer(tlsOptions, app) instead. +//require("greenlock-express") +require("../../") + .init({ + packageRoot: __dirname, + configDir: "./greenlock.d", + + maintainerEmail: "jon@example.com", + cluster: false + }) + .ready(httpsWorker); + function httpsWorker(glx) { // // HTTP2 would have been the default httpsServer for node v12+ @@ -29,20 +38,8 @@ function httpsWorker(glx) { // 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); diff --git a/examples/https/package.json b/examples/https/package.json new file mode 100644 index 0000000..25b5e8d --- /dev/null +++ b/examples/https/package.json @@ -0,0 +1,12 @@ +{ + "name": "https1-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/https/server.js b/examples/https/server.js index 9ca89c5..1921ef6 100644 --- a/examples/https/server.js +++ b/examples/https/server.js @@ -1,7 +1,5 @@ "use strict"; -var pkg = require("../../package.json"); - // The WRONG way: //var https = require('https'); //var httpsServer = https.createServer(tlsOptions, app); @@ -10,6 +8,17 @@ var pkg = require("../../package.json"); // Greenlock needs to change some low-level http and https options. // Use glx.httpsServer(tlsOptions, app) instead. +//require("greenlock-express") +require("../../") + .init({ + packageRoot: __dirname, + configDir: "./greenlock.d", + + maintainerEmail: "jon@example.com", + cluster: false + }) + .ready(httpsWorker); + function httpsWorker(glx) { // // HTTPS 1.1 is the default @@ -29,20 +38,8 @@ function httpsWorker(glx) { // 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); diff --git a/examples/quickstart/package.json b/examples/quickstart/package.json new file mode 100644 index 0000000..e8576ef --- /dev/null +++ b/examples/quickstart/package.json @@ -0,0 +1,12 @@ +{ + "name": "quickstart-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/quickstart/server.js b/examples/quickstart/server.js index a45d6ae..e15918a 100644 --- a/examples/quickstart/server.js +++ b/examples/quickstart/server.js @@ -1,32 +1,27 @@ "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!"); - }; +// 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!"); +}; + +//require("greenlock-express") +require("../../") + .init({ + // Package name+version are taken from /package.json and used for ACME client user agent + packageRoot: __dirname, + // configDir is relative to packageRoot, not _this_ file + configDir: "./greenlock.d", + + // Maintainer email is the contact for critical bug and security notices + // by default package.json.author.email will be used + //maintainerEmail: "jon@example.com", + + // Change to true when you're ready to make your app cloud-scale + cluster: false + }) // 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); + .serve(app); diff --git a/examples/socket.io/package.json b/examples/socket.io/package.json new file mode 100644 index 0000000..a7d6973 --- /dev/null +++ b/examples/socket.io/package.json @@ -0,0 +1,12 @@ +{ + "name": "socket-io-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/socket.io/server.js b/examples/socket.io/server.js index a729dcb..735ff43 100644 --- a/examples/socket.io/server.js +++ b/examples/socket.io/server.js @@ -8,6 +8,17 @@ // You can just use WebSockets // (see the websocket example) +//require("greenlock-express") +require("../../") + .init({ + packageRoot: __dirname, + configDir: "./greenlock.d", + + maintainerEmail: "jon@example.com", + cluster: false + }) + .ready(httpsWorker); + function httpsWorker(glx) { var socketio = require("socket.io"); var io; @@ -33,17 +44,3 @@ function httpsWorker(glx) { 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); diff --git a/examples/websockets/package.json b/examples/websockets/package.json new file mode 100644 index 0000000..a7a4086 --- /dev/null +++ b/examples/websockets/package.json @@ -0,0 +1,12 @@ +{ + "name": "websockets-example", + "version": "1.0.0", + "description": "", + "main": "server.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "node server.js" + }, + "author": "John Doe (https://example.com/)", + "license": "ISC" +} diff --git a/examples/websockets/server.js b/examples/websockets/server.js index 952108f..ac39b61 100644 --- a/examples/websockets/server.js +++ b/examples/websockets/server.js @@ -1,5 +1,16 @@ "use strict"; +//require("greenlock-express") +require("../../") + .init({ + packageRoot: __dirname, + configDir: "./greenlock.d", + + maintainerEmail: "jon@example.com", + cluster: false + }) + .ready(httpsWorker); + function httpsWorker(glx) { // we need the raw https server var server = glx.httpsServer(); @@ -26,17 +37,3 @@ function httpsWorker(glx) { 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);