4.0.4

README.md

@@ -1,109 +1,47 @@
-# [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js) is Let's Encrypt for Node
+# [Greenlock Express v4](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!
-
-### Create your project
+You define your app and let Greenlock handle issuing and renewing Free SSL Certificates.
 
 ```bash
 npm init
+npm install --save greenlock-express@v4
 ```
 
-```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>
+`server.js`:
 
 ```js
 "use strict";
 
+var app = require("./app.js");
+
 require("greenlock-express")
-    .init(function() {
-        return {
-            greenlock: require("./greenlock.js"),
+    .init({
+        packageRoot: __dirname,
+        configDir: "./greenlock.d",
 
-            // whether or not to run at cloudscale
-            cluster: false
-        };
+        // contact for security and critical bug notices
+        maintainerEmail: "jon@example.com",
+
+        // 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);
-    });
+    // Serves on 80 and 443
+    // Get's SSL certificates magically!
+    .serve(app);
 ```
 
-</details>
+`./greenlock.d/config.json`:
 
-<details>
-<summary>greenlock.js</summary>
-
-```js
-"use strict";
-
-var pkg = require("./package.json");
-module.exports = require("@root/greenlock").create({
-    // 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
-});
-```
-
-</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
+```json
+{ "sites": [{ "subject": "example.com", "altnames": ["example.com"] }] }
 ```
 
 # Let's Encrypt for...
@@ -128,297 +66,353 @@ npm start -- --staging
     -   [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
 
-# QuickStart Guide
+# Compatibility
 
-Easy as 1, 2, 3... 4
+Works with _any_ node http app, including
 
-<details>
-<summary>1. Create a node project</summary>
+-   [x] Express
+-   [x] Koa
+-   [x] hapi
+-   [x] rill
+-   [x] http2
+-   [x] cluster
+-   [x] etc...
 
-## 1. Create a node project
+# v4 QuickStart
 
-Create an empty node project.
+Serving sites with Free SSL is as easy as 1, 2, 3... 4
 
-Be sure to fill out the package name, version, and an author email.
+## Overview
+
+1. Create a Project with Greenlock Express
+    - `server.js`
+    - `app.js`
+2. Setup the config file (or database)
+    - `.greenlockrc`
+    - `greenlock.d/config.json`
+3. Add Domains
+    - `npx greenlock add --subject example.com --altnames example.com`
+4. Hello, World!
+    - `npm start -- --staging`
+
+### TL;DR
+
+If you're familiar with node, npm, and npx: this is all you need to do:
 
 ```bash
-mkdir ~/my-project
-pushd ~/my-project
 npm init
+npm install --save greenlock-express@v4
+
+npx greenlock init --config-dir greenlock.d --maintainer-email jon@example.com
+npx greenlock add --subject example.com --altnames example.com
+
+npm start -- --staging
 ```
 
-</details>
+Once you've tested that that works, you can change `app.js` to suit your needs replace the built-in callbacks for things like certificate storage as you like.
 
-<details>
-<summary>2. Create an http app (i.e. express)</summary>
+## 1. Create your Project
 
-## 2. Create an http app (i.e. express)
+If you need to install Node.js, do so:
 
-This example is shown with Express, but any node app will do. Greenlock
-works with everything.
-(or any node-style http app)
+Mac, Linux:
 
-`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;
+```bash
+curl -fsS https://webinstall.dev/node | bash
 ```
 
-</details>
+Windows 10:
 
-<details>
-<summary>3. Serve with Greenlock Express</summary>
+```pwsh
+curl -fsSA "MS" https://webinstall.dev/node | powershell
+```
 
-## 3. Serve with Greenlock Express
+Then create a directory for your project, and initialize it:
 
-Greenlock Express is designed with these goals in mind:
+```bash
+mkdir -p my-sites
+pushd my-sites
+npm init
+npm install --save greenlock-express@v4
+```
 
--   Simplicity and ease-of-use
--   Performance and scalability
--   Configurability and control
+## 2. Initialize and Config (Dir or DB)
 
-You can start with **near-zero configuration** and
-slowly add options for greater performance and customization
-later, if you need them.
+You can use **local file storage** or a **database**. The default is to use file storage.
+
+You'll need to create `server.js` and `greenlock.d/config.json`. You can do so using the CLI, API, or by hand.
+
+### Using the CLI (simplest, recommended)
+
+Anytime you install an npm module that contains an executable,
+you can run it using `npx`.
+
+To initialize the Greenlock config, run `npx greenlock init`:
+
+```bash
+npx greenlock init --config-dir ./greenlock.d --maintainer-email 'jon@example.com'
+```
+
+### By Hand (for advanced users)
+
+Create `server.js` like so:
 
 `server.js`:
 
 ```js
-"use strict";
+'use strict';
 
-require("greenlock-express")
-    .init(function() {
-        var pkg = require("./package.json");
-        return {
-            greenlock: require("@root/greenlock").create({
-                // name & version for ACME client user agent
-                packageAgent: pkg.name + "/" + pkg.version,
+var app = require('./app.js');
 
-                // contact for security and critical bug notices
-                maintainerEmail: pkg.author,
+require('greenlock-express')
+    .init({
+        packageRoot: __dirname,
 
-                // where to find .greenlockrc and set default paths
-                packageRoot: __dirname
-            }),
+        // where to look for configuration
+        configDir: './greenlock.d',
 
-            // whether or not to run at cloudscale
-            cluster: false
-        };
+        // 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);
-    });
+    // Serves on 80 and 443
+    // Get's SSL certificates magically!
+    .serve(app);
 ```
 
-And start your server:
+Create `app.js` like so:
 
-```bash
-# Allow non-root node to use ports 80 (HTTP) and 443 (HTTPS)
-sudo setcap 'cap_net_bind_service=+ep' $(which node)
+`app.js`:
+
+```js
+'use strict';
+
+// Here's a vanilla HTTP app to start,
+// but feel free to replace it with Express, Koa, etc
+var app = function(req, res) {
+    res.end('Hello, Encrypted World!');
+};
+
+module.exports = app;
 ```
 
-```bash
-# `npm start` will call `node ./server.js` by default
-npm start
+Greenlock uses `.greenlockrc` to figure out whether to use the file system or a database for config,
+as well as where its root directory is.
+
+`.greenlockrc`
+
+```json
+{"manager":{"module":"@greenlock/manager"},"configDir":"greenlock.d"}
 ```
 
+The `greenlock.d/config.json` is NOT intended to be edited by hand, as it is a substitute for a database, but it looks like this:
+
+```json
+{ "defaults": { "subscriberEmail": "john.doe@example.com" }, "sites": [] }
+```
+
+## 3. Add Sites
+
+For security, you must specify which sites you allow to request certificates. If you need this to be dynamic (i.e. checking a database or API, see the section below on custom site managers).
+
+Every site has a "subject" (its primary domain name) and one or more "altnames" (secondary or related domain names on the same certificate).
+
+### Using CLI (simple, recommended)
+
+Simply supply the names of sites that you manage and they will be added to the file system config, or database.
+
 ```bash
-# use --staging to use the development API until you're ready to get real certificates
+npx greenlock add --subject example.com --altnames example.com,www.example.com
+```
+
+### By Hand (debugging only)
+
+You should NOT edit `greenlock.d/config.json` with your own tools. Use `greenlock.manager.add({})` instead.
+
+`greenlock.d/config.json`:
+
+<!-- TODO update manager to write array rather than object -->
+
+```json
+{ "sites": [{ "subject": "example.com", "altnames": [ "example.com", "www.example.com" ] }] }
+```
+
+## 4. Hello, Encrypted World!
+
+That was it! Now you can run your server!
+
+When you run `npm start`, it will automatically run `node server.js` (or `package.json.scripts.start`).
+
+For arguments that `npm start` should ignore, place them after `--`.
+
+Here we use `--staging` in order to tell greenlock to issue test certificates rather than real certificates.
+
+```bash
+# Note: you can use npm start to run server.js with the --staging flag set
 npm start -- --staging
 ```
 
 ```txt
-Greenlock v3.0.0
-Greenlock Manager Config File: ~/.config/greenlock/manager.json
-Greenlock Storage Directory: ~/.config/greenlock/
+> my-project@1.0.0 start /srv/www/my-project
+> node server.js
 
 Listening on 0.0.0.0:80 for ACME challenges and HTTPS redirects
 Listening on 0.0.0.0:443 for secure traffic
 ```
 
-</details>
+If everything worked you can visit your site in your browser, and after a few seconds you'll get a certificate warning and, after that, see a "Hello World" message. The debug (staging) certificates will be saved in `greenlock.d/staging`. Run again without `--staging` and you will get real certificates.
 
-<details>
-<summary>4. Manage SSL Certificates and Domains</summary>
+### Season to taste
 
-## 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.
+Now you're ready to update `app.js` with your code. For example, try this next:
 
 ```bash
-# see which manager and what options are in use
-cat .greenlockrc
+npm install --save express
+mkdir -p public
+echo '<h1>Hello!</h1>' >> public/index.html
 ```
 
-<details>
-<summary>Example Output</summary>
+`app.js`:
 
-```json
-{
-    "manager": "greenlock-manager-fs",
-    "configFile": "./greenlock.json"
+```js
+'use strict';
+
+var path = require('path');
+var express = require('express');
+var app = express();
+
+app.get('/', express.static(path.join(__dirname, "public")));
+
+module.exports = app;
+
+// for development and debugging
+if (require.main === module) {
+    require('http').createServer(app).listen(3000, function () {
+        console.info("Listening for HTTP on", this.address());
+    });
 }
 ```
 
-</details>
+# Walkthrough
 
-```bash
-# show the global defaults
-npx greenlock defaults
-```
+For a more detail read the full
+[WALKTHROUGH](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/WALKTHROUGH.md).
 
-```js
-var defaults = await greenlock.defaults();
-```
+# Examples
 
-<details>
-<summary>Example Output</summary>
+To see all of the examples, just browse [greenlock-express.js/examples/](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples)
 
-```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
-}
-```
+|        Example         | Location + Description                                                                                                                     |
+| :--------------------: | :----------------------------------------------------------------------------------------------------------------------------------------- |
+|        Express         | [./examples/express/][ex-express] how to export an express app                                                                             |
+|    Node's **http2**    | [./examples/http2/][ex-http2] how to use Node's built-in http2 server                                                                      |
+|      Node's https      | [./examples/https][ex-https] how to customize the https server                                                                             |
+|     **WebSockets**     | [./examples/websockets/][ex-websockets] how to use `on('upgrade')`                                                                         |
+| <span>Socket.IO</span> | [./examples/socket.io][ex-socketio] how to overcomplicate a persistent connection                                                          |
+|        Cluster         | [./examples/cluster/][ex-cluster] how to use Node's built-in clustering with master and worker processes                                   |
+|     **Wildcards**      | [coming someday][ex-wildcards] (ask to help create this) how to use DNS-01 for wildcard certs                                              |
+|     **Localhost**      | [coming someday][ex-localhost] (ask to help create this) how to use DNS-01 for domains that resolve to private networks, such as 127.0.0.1 |
+|       **CI/CD**        | [coming someday][ex-cicd] (ask to help create this) how to use the `--staging` environment for test deployments                            |
+|       HTTP Proxy       | [examples/http-proxy][ex-http-proxy] how to (reverse) proxy decrypted traffic to another server                                            |
+|           -            | Build your own<br>Be sure to tell me about it (open an issue)                                                                              |
 
-</details>
+[ex-express]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/express/
+[ex-http2]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http2/
+[ex-https]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/https/
+[ex-websockets]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/websockets/
+[ex-socketio]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/socketo.io/
+[ex-cluster]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/cluster/
+[ex-wildcards]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcards/
+[ex-localhost]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/
+[ex-cicd]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/
+[ex-http-proxy]: https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http-proxy/
 
-```bash
-# show per-site configs
-npx greenlock config --subject example.com
-```
 
-```js
-greenlock.sites.get({ subject: "example.com" });
-```
+# FAQ
+## 1. But did YOU read the QuickStart?
 
-<details>
-<summary>Example Output</summary>
+99% of the questions I get are answered in the QuickStart, or in the Examples.
 
-```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"
-            }
-        }
-    }
-}
-```
+Before you go into your specific use case, just try out the QuickStart from start to finish so that you can see that the default setup works, you get feel for the "lay of the land", and you know what to edit.
 
-</details>
+## 2. How to use JavaScript configuration?
 
-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 don't. It's JSON on purpose.
 
-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:
+The configuration has to be serializable (i.e. could go in a database).
 
-```bash
-# Set a global subscriber account
-npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true
-```
+The config file is meant for **simple** use cases, for the average dev and it is managed with `npx greenlock ...`, as shown in the QuickStart.
 
-```js
-greenlock.manager.defaults({
-    subscriberEmail: "mycompany@example.com",
-    agreeToTerms: true
-});
-```
+If you have a **dynamic** or **advanced** use case (i.e. you need stuff in a database, or to change config on-the-fly), you can use the Greenlock API (not Greenlock Express) and you'll love it.
 
-<!-- todo print where the key was saved -->
+If you're layering a lot of **complexity** with dev ops tools, but you don't really understand the tools that well (i.e. **Docker**), either use ENVIRONMENT variables or put the `npx greenlock ...` commands in your setup script. You MUST use a database for **lambda** "cloud functions" and such.
 
-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).
+You can also just mangle the Greenlock API to do what you want... but I don't recommend it. Keep it simple and your future self with thank you.
 
-```bash
-# Add a certificate with specific domains
-npx greenlock add --subject example.com --altnames example.com,www.example.com
-```
+General rule of thumb: commit code, not data / config.
 
-```js
-greenlock.sites.add({
-    subject: "example.com",
-    altnames: ["example.com"]
-});
-```
+## 3. How to use non-standard ports (not 80, 443)?
 
-<!-- todo print where the cert was saved -->
+You don't. Not usually.
 
-Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require
-[**DNS validation**](https://git.rootprojects.org/root/greenlock-exp).
+Let's Encrypt **REQUIRES port 80** for HTTP-01 challenges.
 
--   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)
+But if you're using DNS-01 or you have a proxy in place, just use the raw node server. See these examples:
 
-</details>
+- [examples/http/server.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http/server.js)
+- [examples/https/server.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/https/server.js)
 
-# Plenty of Examples
+If you want to use Greenlock as a proxy, see this example:
 
--   [greenlock-express.js/examples/](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples)
-    -   [Express](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/express/)
-    -   [Node's **http2**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http2/)
-    -   [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/)
-    -   [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/)
-    -   [**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)
-    -   [HTTP Proxy](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http-proxy/)
+- [examples/http-proxy/server.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http-proxy/server.js)
+
+# Troubleshooting
+
+### What if the example didn't work?
+
+Double check the following:
+
+-   **Public Facing IP** for `http-01` challenges
+    -   Are you running this _as_ a public-facing webserver (good)? or localhost (bad)?
+    -   Does `ifconfig` show a public address (good)? or a private one - 10.x, 192.168.x, etc (bad)?
+    -   If you're on a non-public server, are you using the `dns-01` challenge?
+-   **valid email**
+    -   You MUST set `maintainerEmail` to a **valid address**
+    -   MX records must validate (`dig MX example.com` for `'john@example.com'`)
+-   **valid DNS records**
+    -   Must have public DNS records (test with `dig +trace A example.com; dig +trace www.example.com` for `[ 'example.com', 'www.example.com' ]`)
+-   **write access**
+    -   You MUST set `configDir` to a writeable location (test with `touch ./greenlock.d/config.json`)
+-   **port binding privileges**
+    -   You MUST be able to bind to ports 80 and 443
+    -   You can do this via `sudo` or [`setcap`](https://gist.github.com/firstdoit/6389682)
+-   **API limits**
+    -   You MUST NOT exceed the API [**usage limits**](https://letsencrypt.org/docs/staging-environment/) per domain, certificate, IP address, etc
+-   **Red Lock, Untrusted**
+    -   You MUST switch from `npm start -- --staging` to `npm start` to use the **production** server
+    -   The API URL should not have 'acme-staging-v02', but should have 'acme-v02'
+
+# 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
 
@@ -429,15 +423,40 @@ Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require
 -->
 
 -   [Custom Domain Management](https://git.rootprojects.org/root/greenlock-manager-test.js)
-    -   `npx greenlock init --manager ./path-or-npm-name.js --manager-FOO 'set option FOO'`
+    -   edit `server.js` and/or `.greenlockrc` to switch from the default `configDir` manager to your config system or database
+    -   CLI example: `npx greenlock init --manager ./path-or-npm-name.js --manager-FOO 'set option FOO'`
 -   [Custom Key & Cert Storage](https://git.rootprojects.org/root/greenlock-store-test.js)
-    -   `npx greenlock defaults --store greenlock-store-fs --store-base-path ./greenlock.d`
+    -   edit the `defaults` section of `greenlock.d/config.json` to change the certificate store or database
+    -   CLI example: `npx greenlock defaults --store greenlock-store-fs --store-base-path ./greenlock.d`
 -   [Custom ACME HTTP-01 Challenges](https://git.rootprojects.org/root/acme-http-01-test.js)
-    -   `npx greenlock defaults --challenge-http-01 ./you-http-01.js`
-    -   `npx greenlock update --subject example.com --challenge-http-01 acme-http-01-standalone`
+    -   edit the `defaults` section of `greenlock.d/config.json` to change the challenges by hand
+    -   CLI example: `npx greenlock defaults --challenge-http-01 ./you-http-01.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
+    -   edit the `defaults` section of `greenlock.d/config.json` to change the challenges by hand
+    -   CLI example: `npx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx`
+    -   Per-site example: `npx greenlock update --subject example.com --challenge-dns-01 ./your-dns-01.js`
+    -   API example:
+        ```js
+        greenlock.sites.set({
+            subject: "example.com",
+            challenges: {
+                "dns-01": {
+                    module: "my-npm-module-name",
+                    foo: "some option",
+                    bar: "some other option"
+                }
+            }
+        });
+        ```
+
+If you're using the default `configDir` management you can edit `greenlock.d/config.json` by hand to change
+which default and per-site modules are used.
+
+You can use the CLI, even if you're using a database, buckets, or your own file storage.
+
+You can also use the API, particularly if you need to set values dynamically per-site or per-user
+rather than using the global defaults. The certificate store and all challenges can be set
+per-site, but most per-site use cases are for DNS-01.
 
 # Ready-made Integrations
 
@@ -515,4 +534,3 @@ attribution, and/or visible source policies. We want to build great software and
 MPL-2.0 |
 [Terms of Use](https://therootcompany.com/legal/#terms) |
 [Privacy Policy](https://therootcompany.com/legal/#privacy)
-[Privacy Policy](https://therootcompany.com/legal/#privacy)

WALKTHROUGH.md

@@ -0,0 +1,256 @@
+# 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
+```
+
+<details>
+<summary>Example Output</summary>
+
+```json
+{
+    "manager": {
+        "module": "@greenlock/manager"
+    },
+    "configDir": "./greenlock.d"
+}
+```
+
+</details>
+
+```bash
+# show the global defaults with the CLI
+npx greenlock defaults
+```
+
+```js
+// show the global defaults with the API
+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 with the CLI
+npx greenlock config --subject example.com
+```
+
+```js
+// show a site config with the API
+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"
+            }
+        }
+    }
+}
+```
+
+</details>
+
+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 with the CLI
+npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true
+```
+
+```js
+// set a global subscriber account with the API
+greenlock.manager.defaults({
+    subscriberEmail: "mycompany@example.com",
+    agreeToTerms: 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 with the CLI
+npx greenlock add --subject example.com --altnames example.com,www.example.com
+```
+
+```js
+// Add a certificate with specific domains with the API
+greenlock.sites.add({
+    subject: "example.com",
+    altnames: ["example.com"]
+});
+```
+
+<!-- todo print where the cert was saved -->
+
+Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require
+[**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)

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

examples/cluster/server.js

@@ -1,25 +1,27 @@
 "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 is only executed by workers (no-op in master)
+    .ready(httpsWorker)
+    // master is only executed by master (no-op in a worker)
+    .master(function() {
+        console.info("I'm the master");
+    });
 
 function httpsWorker(glx) {
     // WRONG

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

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);

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

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);

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

examples/http/server.js

@@ -1,15 +1,24 @@
 "use strict";
 
-var pkg = require("../../package.json");
-
 // The WRONG way:
 //var http = require('http');
-//var httpServer = https.createSecureServer(redirectToHttps);
+//var httpServer = http.createServer(redirectToHttps);
 //
 // Why is that wrong?
 // 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);

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

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+
@@ -17,7 +26,8 @@ function httpsWorker(glx) {
     //
 
     // Get the raw http2 server:
-    var http2Server = glx.http2Server(function(req, res) {
+    var tlsOptions = null;
+    var http2Server = glx.http2Server(tlsOptions, function(req, res) {
         res.end("Hello, Encrypted World!");
     });
 
@@ -29,20 +39,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);

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

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);

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

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 <packageRoot>/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);

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

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);

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 <j.doe@example.com> (https://example.com/)",
+  "license": "ISC"
+}

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);

greenlock-express.js

@@ -17,14 +17,20 @@ var GLE = module.exports;
 // under the hood. That's the hope, anyway.
 
 GLE.init = function(fn) {
-    if (cluster.isWorker) {
+    // See https://git.coolaj86.com/coolaj86/greenlock-express.js/issues/80
+    if (fn && false !== fn.cluster && cluster.isWorker) {
         // ignore the init function and launch the worker
         return require("./worker.js").create();
     }
 
-    var opts = fn();
+    var opts;
+    if ("function" === typeof fn) {
+        opts = fn();
+    } else if ("object" === typeof fn) {
+        opts = fn;
+    }
     if (!opts || "object" !== typeof opts) {
-        throw new Error("the `Greenlock.init(fn)` function should return an object `{ greenlock, cluster }`");
+        throw new Error("the `Greenlock.init(fn)` function should return an object `{ packageRoot, cluster }`");
     }
 
     // just for ironic humor

greenlock-shim.js

@@ -2,20 +2,34 @@
 
 module.exports.create = function(opts) {
     var Greenlock = require("@root/greenlock");
+    //var Init = require("@root/greenlock/lib/init.js");
     var greenlock = opts.greenlock;
 
-    if (!greenlock) {
-        opts = parsePackage(opts);
-        opts.packageAgent = addGreenlockAgent(opts);
-        greenlock = Greenlock.create(opts);
+    /*
+    if (!greenlock && opts.packageRoot) {
         try {
-            if (opts.notify) {
-                greenlock._defaults.notify = opts.notify;
-            }
+            greenlock = require(path.resolve(opts.packageRoot, "greenlock.js"));
         } catch (e) {
-            console.error("Developer Error: notify not attached correctly");
+            if ("MODULE_NOT_FOUND" !== e.code) {
+                throw e;
+            }
         }
     }
+    */
+
+    if (!greenlock) {
+        //opts = Init._init(opts);
+        greenlock = Greenlock.create(opts);
+    }
+    opts.packageAgent = addGreenlockAgent(opts);
+
+    try {
+        if (opts.notify) {
+            greenlock._defaults.notify = opts.notify;
+        }
+    } catch (e) {
+        console.error("Developer Error: notify not attached correctly");
+    }
 
     // re-export as top-level function to simplify rpc with workers
     greenlock.getAcmeHttp01ChallengeResponse = function(opts) {
@@ -24,11 +38,14 @@ module.exports.create = function(opts) {
 
     greenlock._find({}).then(function(sites) {
         if (sites.length <= 0) {
-            console.warn("warning: No sites available. Did you add them?");
+            console.warn("Warning: `find({})` returned 0 sites.");
+            console.warn("         Does `" + greenlock.manager._modulename + "` implement `find({})`?");
+            console.warn("         Did you add sites?");
             console.warn("         npx greenlock add --subject example.com --altnames example.com");
             return;
         }
         console.info("Ready to Serve:");
+
         var max = 3;
         if (sites.length >= 1) {
             sites.slice(0, max).forEach(function(site) {
@@ -53,53 +70,3 @@ function addGreenlockAgent(opts) {
 
     return packageAgent.trim();
 }
-
-// ex: "John Doe <john@example.com> (https://john.doe)"
-// ex: "John Doe <john@example.com>"
-// ex: "<john@example.com>"
-// ex: "john@example.com"
-var looseEmailRe = /(^|[\s<])([^'" <>:;`]+@[^'" <>:;`]+\.[^'" <>:;`]+)/;
-function parsePackage(opts) {
-    // 'package' is sometimes a reserved word
-    var pkg = opts.package || opts.pkg;
-    if (!pkg) {
-        opts.maintainerEmail = parseMaintainer(opts.maintainerEmail);
-        return opts;
-    }
-
-    if (!opts.packageAgent) {
-        var err = "missing `package.THING`, which is used for the ACME client user agent string";
-        if (!pkg.name) {
-            throw new Error(err.replace("THING", "name"));
-        }
-        if (!pkg.version) {
-            throw new Error(err.replace("THING", "version"));
-        }
-        opts.packageAgent = pkg.name + "/" + pkg.version;
-    }
-
-    if (!opts.maintainerEmail) {
-        try {
-            opts.maintainerEmail = pkg.author.email || pkg.author.match(looseEmailRe)[2];
-        } catch (e) {}
-    }
-    if (!opts.maintainerEmail) {
-        throw new Error("missing or malformed `package.author`, which is used as the contact for support notices");
-    }
-    opts.package = undefined;
-    opts.maintainerEmail = parseMaintainer(opts.maintainerEmail);
-
-    return opts;
-}
-
-function parseMaintainer(maintainerEmail) {
-    try {
-        maintainerEmail = maintainerEmail.match(looseEmailRe)[2];
-    } catch (e) {
-        maintainerEmail = null;
-    }
-    if (!maintainerEmail) {
-        throw new Error("missing or malformed `maintainerEmail`, which is used as the contact for support notices");
-    }
-    return maintainerEmail;
-}

master.js

@@ -48,10 +48,12 @@ Master.create = function(opts) {
             kickoff();
             resolveCb(fn);
             return master;
+        },
+        serve: function(fn) {
+            // ignore
+            master.ready(fn);
         }
     };
-    // backwards compat starts early...
-    master.serve = master.ready;
     return master;
 };
 

package-lock.json

@@ -1,26 +1,27 @@
 {
     "name": "@root/greenlock-express",
-    "version": "3.1.0",
+    "version": "4.0.4",
     "lockfileVersion": 1,
     "requires": true,
     "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==",
+            "version": "3.1.0",
+            "resolved": "https://registry.npmjs.org/@greenlock/manager/-/manager-3.1.0.tgz",
+            "integrity": "sha512-PBy5CMK+j4oD7sj7hF5qE+xKEOSiiuL2hHd5X5ttEbtnTSDKjNeqbrR5k2ZddwVNdjOVeBIeuqlm81IFZ+Ftew==",
             "requires": {
-                "greenlock-manager-fs": "^3.0.5"
+                "greenlock-manager-fs": "^3.1.0"
             }
         },
         "@root/acme": {
-            "version": "3.0.8",
-            "resolved": "https://registry.npmjs.org/@root/acme/-/acme-3.0.8.tgz",
-            "integrity": "sha512-VmBvLvWdCDkolkanI9Dzm1ouSWPaAa2eCCwcDZcVQbWoNiUIOqbbd57fcMA/gZxLyuJPStD2WXFuEuSMPDxcww==",
+            "version": "3.1.0",
+            "resolved": "https://registry.npmjs.org/@root/acme/-/acme-3.1.0.tgz",
+            "integrity": "sha512-GAyaW63cpSYd2KvVp5lHLbCWeEhJPKZK9nsJvZJOKsD9Uv88KEttn4FpDZEJ+2q3Jsey0DWpuQ2I4ft0JV9p2w==",
             "requires": {
+                "@root/csr": "^0.8.1",
                 "@root/encoding": "^1.0.1",
-                "@root/keypairs": "^0.9.0",
+                "@root/keypairs": "^0.10.0",
                 "@root/pem": "^1.0.4",
-                "@root/request": "^1.3.11",
+                "@root/request": "^1.6.1",
                 "@root/x509": "^0.7.2"
             }
         },
@@ -48,27 +49,26 @@
             "integrity": "sha512-OaEub02ufoU038gy6bsNHQOjIn8nUjGiLcaRmJ40IUykneJkIW5fxDqKxQx48cszuNflYldsJLPPXCrGfHs8yQ=="
         },
         "@root/greenlock": {
-            "version": "3.1.3",
-            "resolved": "https://registry.npmjs.org/@root/greenlock/-/greenlock-3.1.3.tgz",
-            "integrity": "sha512-9Rj9JIKYItOvZKbPa5JrljS74dw+KjltOyQnb14y4nX89C+s1mZjv3Qiv1cNuYkYCmBGR77z0/cKnfUUaWxkag==",
+            "version": "4.0.5",
+            "resolved": "https://registry.npmjs.org/@root/greenlock/-/greenlock-4.0.5.tgz",
+            "integrity": "sha512-KR9w3mYE9aH33FCibI8oSYBQV+f7lc3MVPdZ9nxY2tqRLmJp05cMOMz340mtG14VnWDuznLj4TbBj3sHIuoQPQ==",
             "requires": {
-                "@greenlock/manager": "^3.0.0",
-                "@root/acme": "^3.0.8",
+                "@greenlock/manager": "^3.1.0",
+                "@root/acme": "^3.1.0",
                 "@root/csr": "^0.8.1",
-                "@root/keypairs": "^0.9.0",
+                "@root/keypairs": "^0.10.0",
                 "@root/mkdirp": "^1.0.0",
-                "@root/request": "^1.3.10",
+                "@root/request": "^1.6.1",
                 "acme-http-01-standalone": "^3.0.5",
                 "cert-info": "^1.5.1",
-                "greenlock-manager-fs": "^3.0.5",
-                "greenlock-store-fs": "^3.2.0",
+                "greenlock-store-fs": "^3.2.2",
                 "safe-replace": "^1.1.0"
             }
         },
         "@root/keypairs": {
-            "version": "0.9.0",
-            "resolved": "https://registry.npmjs.org/@root/keypairs/-/keypairs-0.9.0.tgz",
-            "integrity": "sha512-NXE2L9Gv7r3iC4kB/gTPZE1vO9Ox/p14zDzAJ5cGpTpytbWOlWF7QoHSJbtVX4H7mRG/Hp7HR3jWdWdb2xaaXg==",
+            "version": "0.10.0",
+            "resolved": "https://registry.npmjs.org/@root/keypairs/-/keypairs-0.10.0.tgz",
+            "integrity": "sha512-t8VocY46Mtb0NTsxzyLLf5tsgfw0BXLYVADAyiRdEdqHcvPFGJdjkXNtHVQuSV/FMaC65iTOHVP4E6X8iT3Ikg==",
             "requires": {
                 "@root/encoding": "^1.0.1",
                 "@root/pem": "^1.0.4",
@@ -86,9 +86,9 @@
             "integrity": "sha512-rEUDiUsHtild8GfIjFE9wXtcVxeS+ehCJQBwbQQ3IVfORKHK93CFnRtkr69R75lZFjcmKYVc+AXDB+AeRFOULA=="
         },
         "@root/request": {
-            "version": "1.4.2",
-            "resolved": "https://registry.npmjs.org/@root/request/-/request-1.4.2.tgz",
-            "integrity": "sha512-J8FM4+SJuc7WRC+Jz17m+VT2lgI7HtatHhxN1F2ck5aIKUAxJEaR4u/gLBsgT60mVHevKCjKN0O8115UtJjwLw=="
+            "version": "1.6.1",
+            "resolved": "https://registry.npmjs.org/@root/request/-/request-1.6.1.tgz",
+            "integrity": "sha512-8wrWyeBLRp7T8J36GkT3RODJ6zYmL0/maWlAUD5LOXT28D3TDquUepyYDKYANNA3Gc8R5ZCgf+AXvSTYpJEWwQ=="
         },
         "@root/x509": {
             "version": "0.7.2",
@@ -115,9 +115,9 @@
             "integrity": "sha1-Aljq5NPQwJdN4cFpGI7wBR0dGYg="
         },
         "greenlock-manager-fs": {
-            "version": "3.0.5",
-            "resolved": "https://registry.npmjs.org/greenlock-manager-fs/-/greenlock-manager-fs-3.0.5.tgz",
-            "integrity": "sha512-r/q+tEFuDwklfzPfiGhcIrHuJxMrppC+EseESpu5f0DMokh+1iZVm9nGC/VE7/7GETdOYfEYhhQkmspsi8Gr/A==",
+            "version": "3.1.1",
+            "resolved": "https://registry.npmjs.org/greenlock-manager-fs/-/greenlock-manager-fs-3.1.1.tgz",
+            "integrity": "sha512-np6qdnPIOZx40PAcSQcqK1eMPWjTKxsxcgRd/OVg0ai49WC1Ds74CTrwmB84pq2n53ikbnDBQFmKEQ4AC0DK8w==",
             "requires": {
                 "@root/mkdirp": "^1.0.0",
                 "safe-replace": "^1.1.0"
@@ -133,9 +133,9 @@
             }
         },
         "redirect-https": {
-            "version": "1.3.0",
-            "resolved": "https://registry.npmjs.org/redirect-https/-/redirect-https-1.3.0.tgz",
-            "integrity": "sha512-9GzwI/+Cqw3jlSg0CW6TgBQbhiVhkHSDvW8wjgRQ9IK34wtxS71YJiQeazSCSEqbvowHCJuQZgmQFl1xUHKEgg==",
+            "version": "1.3.1",
+            "resolved": "https://registry.npmjs.org/redirect-https/-/redirect-https-1.3.1.tgz",
+            "integrity": "sha512-Stex2nI+tMpZXKvy++32TiBXEy+GdpAfp3EUnl5BqCiJ5f5i6XvUSFrs7TR7IoRSlthM7ZtD89uYGTtJBXlFYg==",
             "requires": {
                 "escape-html": "^1.0.3"
             }

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@root/greenlock-express",
-    "version": "3.1.0",
+    "version": "4.0.4",
     "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",
     "homepage": "https://greenlock.domains",
@@ -17,8 +17,8 @@
         "example": "examples"
     },
     "dependencies": {
-        "@root/greenlock": "^3.1.3",
-        "redirect-https": "^1.1.5"
+        "@root/greenlock": "^4.0.5",
+        "redirect-https": "^1.3.1"
     },
     "trulyOptionalDependencies": {
         "http-proxy": "^1.17.0",

single.js

@@ -19,9 +19,18 @@ Single.create = function(opts) {
             // ignore
             //fn(master);
             return single;
+        },
+        serve: function(fn) {
+            // keeping backwards compat
+            if (1 === fn.length) {
+                single.ready(fn);
+                return;
+            }
+            // serving the app, right away
+            single.ready(function(glx) {
+                glx.serveApp(fn);
+            });
         }
     };
-    // backwards compat starts now
-    single.serve = single.ready;
     return single;
 };

worker.js

@@ -22,10 +22,19 @@ Worker.create = function() {
         master: function() {
             // ignore
             return worker;
+        },
+        serve: function(fn) {
+            // keeping backwards compat
+            if (1 === fn.length) {
+                worker.ready(fn);
+                return;
+            }
+            // serving the express app, right away
+            worker.ready(function(glx) {
+                glx.serveApp(fn);
+            });
         }
     };
-    // backwards compat starts early...
-    worker.serve = worker.ready;
     return worker;
 };