From e1d5e9a692f2b787c2e7d9750543e02a1f61ecea Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Tue, 5 Nov 2019 03:09:42 -0700 Subject: [PATCH] update docs --- .gitignore | 5 ++ README.md | 127 +++++++++++++++++++++--------- greenlock-express.js | 4 +- greenlock.js => greenlock-shim.js | 18 ++++- master.js | 2 +- single.js | 2 +- 6 files changed, 110 insertions(+), 48 deletions(-) rename greenlock.js => greenlock-shim.js (84%) diff --git a/.gitignore b/.gitignore index 5613033..e15cb28 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,8 @@ +app.js +server.js +greenlock.js +.greenlockrc + # Logs logs *.log diff --git a/README.md b/README.md index 244afa7..d2f7373 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,3 @@ -# New Documentation & [v2/v3 Migration Guide](https://git.rootprojects.org/root/greenlock.js/src/branch/v3/MIGRATION_GUIDE_V2_V3.md) - -Greenlock v3 just came out of private beta **today** (Nov 1st, 2019). - -The code is complete and we're working on great documentation. - -Many **examples** and **full API** documentation are still coming. - # [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js) is Let's Encrypt for Node ![Greenlock Logo](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo") @@ -14,51 +6,103 @@ Many **examples** and **full API** documentation are still coming. Free SSL, Automated HTTPS / HTTP2, served with Node via Express, Koa, hapi, etc. -### Let's Encrypt for Node, Express, etc +### Let's Encrypt for Node and Express (and Koa, hapi, rill, etc) Greenlock Express is a **Web Server** with **Fully Automated HTTPS** and renewals. +You define your app, and let Greenlock handle issuing and renewing Free SSL Certificates. + +**Cloud-ready** with Node `cluster`. + +# Quick Start + +- 1. Create a Project with Greenlock Express +- 2. Initialize and Setup +- 3. Add Domains, and Hello, World! + +### Create your project + +```bash +npm init +``` + +```bash +npm install --save greenlock-express@v3 +``` + +```bash +npx greenlock init \ + --maintainer-email 'jon@example.com' \ + --manager-config-file ./greenlock.json +``` + +
+server.js + ```js "use strict"; -function httpsWorker(glx) { - // Serves on 80 and 443 - // Get's SSL certificates magically! - - glx.serveApp(function(req, res) { - res.end("Hello, Encrypted World!"); - }); -} - -var pkg = require("./package.json"); require("greenlock-express") - .init(function getConfig() { - // Greenlock Config - + .init(function() { return { - package: { name: pkg.name, version: pkg.version }, - maintainerEmail: pkg.author, + greenlock: require("./greenlock.js"), + + // whether or not to run at cloudscale cluster: false }; }) - .serve(httpsWorker); + .ready(function(glx) { + var app = require("./app.js"); + + // Serves on 80 and 443 + // Get's SSL certificates magically! + glx.serveApp(app); + }); ``` -Manage via API or the config file: +
-`~/.config/greenlock/manage.json`: (default filesystem config) +
+greenlock.js -```json -{ - "subscriberEmail": "letsencrypt-test@therootcompany.com", - "agreeToTerms": true, - "sites": { - "example.com": { - "subject": "example.com", - "altnames": ["example.com", "www.example.com"] - } - } -} +```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 +}); +``` + +
+ +`app.js`: + +```js +var app = function(req, res) { + res.end("Hello, Encrypted World!"); +}; + +module.exports = app; +``` + +```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 ``` # Let's Encrypt for... @@ -285,7 +329,7 @@ Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require - [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/) + - [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) @@ -374,3 +418,8 @@ 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) + +``` + +``` diff --git a/greenlock-express.js b/greenlock-express.js index c36d94b..58aa37a 100644 --- a/greenlock-express.js +++ b/greenlock-express.js @@ -24,9 +24,7 @@ GLE.init = function(fn) { var opts = fn(); if (!opts || "object" !== typeof opts) { - throw new Error( - "the `Greenlock.init(fn)` function should return an object `{ maintainerEmail, packageAgent, notify }`" - ); + throw new Error("the `Greenlock.init(fn)` function should return an object `{ greenlock, cluster }`"); } // just for ironic humor diff --git a/greenlock.js b/greenlock-shim.js similarity index 84% rename from greenlock.js rename to greenlock-shim.js index c6fff08..f705740 100644 --- a/greenlock.js +++ b/greenlock-shim.js @@ -1,11 +1,21 @@ "use strict"; module.exports.create = function(opts) { - opts = parsePackage(opts); - opts.packageAgent = addGreenlockAgent(opts); - var Greenlock = require("@root/greenlock"); - var greenlock = Greenlock.create(opts); + var greenlock = opts.greenlock; + + if (!greenlock) { + opts = parsePackage(opts); + opts.packageAgent = addGreenlockAgent(opts); + greenlock = Greenlock.create(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) { diff --git a/master.js b/master.js index 3444be5..d2d4b3d 100644 --- a/master.js +++ b/master.js @@ -13,7 +13,7 @@ Master.create = function(opts) { var _readyCb; var _kicked = false; - var greenlock = require("./greenlock.js").create(opts); + var greenlock = require("./greenlock-shim.js").create(opts); var ready = new Promise(function(resolve) { resolveCb = resolve; diff --git a/single.js b/single.js index 3a1f5e2..e3264bc 100644 --- a/single.js +++ b/single.js @@ -6,7 +6,7 @@ var Single = module.exports; var Servers = require("./servers.js"); Single.create = function(opts) { - var greenlock = require("./greenlock.js").create(opts); + var greenlock = require("./greenlock-shim.js").create(opts); var servers = Servers.create(greenlock);