4.0.4

README.md

@@ -89,51 +89,94 @@ Works with _any_ node http app, including
 
 Serving sites with Free SSL is as easy as 1, 2, 3... 4
 
-### Overview
+## 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`
 
-## 1. Create your Project
+### TL;DR
+
+If you're familiar with node, npm, and npx: this is all you need to do:
 
 ```bash
-# Install the latest node, if needed
-curl -fsL bit.ly/node-installer | bash
+npm init
+npm install --save greenlock-express@v4
 
-# Create your project, add 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
+```
+
+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.
+
+## 1. Create your Project
+
+If you need to install Node.js, do so:
+
+Mac, Linux:
+
+```bash
+curl -fsS https://webinstall.dev/node | bash
+```
+
+Windows 10:
+
+```pwsh
+curl -fsSA "MS" https://webinstall.dev/node | powershell
+```
+
+Then create a directory for your project, and initialize it:
+
+```bash
+mkdir -p my-sites
+pushd my-sites
 npm init
 npm install --save greenlock-express@v4
 ```
 
-You can use **local file storage** or a **database**. The default is to use file storage.
-
 ## 2. Initialize and Config (Dir or DB)
 
+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
-# Note: you can use the CLI to create `server.js` and `greenlock.d/config.json`
 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';
 
-var app = require("./app.js");
+var app = require('./app.js');
 
-require("greenlock-express")
+require('greenlock-express')
     .init({
         packageRoot: __dirname,
 
-        // contact for security and critical bug notices
-        configDir: "./greenlock.d",
+        // where to look for configuration
+        configDir: './greenlock.d',
 
         // whether or not to run at cloudscale
         cluster: false
@@ -143,36 +186,72 @@ require("greenlock-express")
     .serve(app);
 ```
 
+Create `app.js` like so:
+
 `app.js`:
 
 ```js
-"use strict";
+'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!");
+    res.end('Hello, Encrypted World!');
 };
 
 module.exports = app;
 ```
 
-### 3. Add Sites
+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
-# Note: you can use the CLI to edit the config file
-npx greenlock add --subject example.com --altnames example.com
+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"] }] }
+{ "sites": [{ "subject": "example.com", "altnames": [ "example.com", "www.example.com" ] }] }
 ```
 
-### 4. Hello, Encrypted World!
+## 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
@@ -187,24 +266,111 @@ Listening on 0.0.0.0:80 for ACME challenges and HTTPS redirects
 Listening on 0.0.0.0:443 for secure traffic
 ```
 
-## Walkthrough
+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.
+
+### Season to taste
+
+Now you're ready to update `app.js` with your code. For example, try this next:
+
+```bash
+npm install --save express
+mkdir -p public
+echo '<h1>Hello!</h1>' >> public/index.html
+```
+
+`app.js`:
+
+```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());
+    });
+}
+```
+
+# Walkthrough
 
 For a more detail read the full
 [WALKTHROUGH](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/WALKTHROUGH.md).
 
 # 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/)
-    -   [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/)
+To see all of the examples, just browse [greenlock-express.js/examples/](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples)
+
+|        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)                                                                              |
+
+[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/
+
+
+# FAQ
+## 1. But did YOU read the QuickStart?
+
+99% of the questions I get are answered in the QuickStart, or in the Examples.
+
+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.
+
+## 2. How to use JavaScript configuration?
+
+You don't. It's JSON on purpose.
+
+The configuration has to be serializable (i.e. could go in a database).
+
+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.
+
+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.
+
+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.
+
+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.
+
+General rule of thumb: commit code, not data / config.
+
+## 3. How to use non-standard ports (not 80, 443)?
+
+You don't. Not usually.
+
+Let's Encrypt **REQUIRES port 80** for HTTP-01 challenges.
+
+But if you're using DNS-01 or you have a proxy in place, just use the raw node server. See these examples:
+
+- [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)
+
+If you want to use Greenlock as a proxy, see this example:
+
+- [examples/http-proxy/server.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http-proxy/server.js)
 
 # Troubleshooting
 
@@ -257,15 +423,40 @@ See the section on **Custom** callbacks and plugins below.
 -->
 
 -   [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
 

examples/cluster/server.js

@@ -16,7 +16,12 @@ require("../../")
         // n-1 cpus, with a minimum of 2
         workers: 4
     })
-    .ready(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/http/server.js

@@ -2,7 +2,7 @@
 
 // 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.

examples/http2/server.js

@@ -26,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!");
     });
 

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@root/greenlock-express",
-    "version": "4.0.3",
+    "version": "4.0.4",
     "lockfileVersion": 1,
     "requires": true,
     "dependencies": {
@@ -13,14 +13,15 @@
             }
         },
         "@root/acme": {
-            "version": "3.0.9",
-            "resolved": "https://registry.npmjs.org/@root/acme/-/acme-3.0.9.tgz",
-            "integrity": "sha512-/FgJF6RUrkqNpLmxqjktHaWMsLOwma6D+e4EBoxKtTjTAI+dBqW8Z8cH38feUsiIBR5LimPeYmBo/oqU3oMkKQ==",
+            "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,16 +49,16 @@
             "integrity": "sha512-OaEub02ufoU038gy6bsNHQOjIn8nUjGiLcaRmJ40IUykneJkIW5fxDqKxQx48cszuNflYldsJLPPXCrGfHs8yQ=="
         },
         "@root/greenlock": {
-            "version": "4.0.4",
-            "resolved": "https://registry.npmjs.org/@root/greenlock/-/greenlock-4.0.4.tgz",
-            "integrity": "sha512-eSBuAs9LLn11I3oQECB7C61M8SrFSgXLaUGyWW87ctWybrV8wFAzc5QZTebOf97ymFX0gCebiWEO2iBtmLH59g==",
+            "version": "4.0.5",
+            "resolved": "https://registry.npmjs.org/@root/greenlock/-/greenlock-4.0.5.tgz",
+            "integrity": "sha512-KR9w3mYE9aH33FCibI8oSYBQV+f7lc3MVPdZ9nxY2tqRLmJp05cMOMz340mtG14VnWDuznLj4TbBj3sHIuoQPQ==",
             "requires": {
                 "@greenlock/manager": "^3.1.0",
-                "@root/acme": "^3.0.9",
+                "@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.4.2",
+                "@root/request": "^1.6.1",
                 "acme-http-01-standalone": "^3.0.5",
                 "cert-info": "^1.5.1",
                 "greenlock-store-fs": "^3.2.2",
@@ -65,9 +66,9 @@
             }
         },
         "@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",
@@ -85,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",
@@ -132,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": "4.0.3",
+    "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": "^4.0.4",
-        "redirect-https": "^1.1.5"
+        "@root/greenlock": "^4.0.5",
+        "redirect-https": "^1.3.1"
     },
     "trulyOptionalDependencies": {
         "http-proxy": "^1.17.0",