diff --git a/README.md b/README.md index 244afa7..ab9487b 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,104 @@ 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`. + +# 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 + +```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 -- --staging ``` # Let's Encrypt for... @@ -163,23 +208,34 @@ later, if you need them. `server.js`: ```js +"use strict"; + require("greenlock-express") - .init(getConfig) - .serve(worker); + .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, -function getConfig() { - return { - // uses name and version as part of the ACME client user-agent - // uses author as the contact for support notices - package: require("./package.json") - }; -} + // contact for security and critical bug notices + maintainerEmail: pkg.author, -function worker(server) { - // Works with any Node app (Express, etc) - var app = require("my-express-app.js"); - server.serveApp(app); -} + // where to find .greenlockrc and set default paths + packageRoot: __dirname + }), + + // 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); + }); ``` And start your server: @@ -194,6 +250,11 @@ sudo setcap 'cap_net_bind_service=+ep' $(which node) npm start ``` +```bash +# use --staging to use the development API until you're ready to get real certificates +npm start -- --staging +``` + ```txt Greenlock v3.0.0 Greenlock Manager Config File: ~/.config/greenlock/manager.json @@ -212,42 +273,108 @@ Listening on 0.0.0.0:443 for secure traffic The management API is built to work with Databases, S3, etc. -HOWEVER, by default it starts with a simple config file. +By default, it's just a simple config file and directory. - +```bash +# see which manager and what options are in use +cat .greenlockrc +``` -`~/.config/greenlock/manager.json`: +
+Example Output ```json { - "subscriberEmail": "letsencrypt-test@therootcompany.com", - "agreeToTerms": true, - "sites": { - "example.com": { - "subject": "example.com", - "altnames": ["example.com", "www.example.com"] + "manager": "greenlock-manager-fs", + "configFile": "./greenlock.json" +} +``` + +
+ +```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" + } } } } ``` -COMING SOON +
-Management can be done via the **CLI** or the JavaScript [**API**](https://git.rootprojects.org/root/greenlock.js/). +Management can be done via the **CLI** or the JavaScript [**API**](https://git.rootprojects.org/root/greenlock.js). Since this is the QuickStart, we'll demo the **CLI**: You need to create a Let's Encrypt _subscriber account_, which can be done globally, or per-site. All individuals, and most businesses, should set this globally: ```bash -# COMING SOON -# (this command should be here by Nov 5th) -# (edit the config by hand for now) -# # Set a global subscriber account -npx greenlock config --subscriber-email 'mycompany@example.com' --agree-to-terms true +npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true +``` + +```js +greenlock.manager.defaults({ + subscriberEmail: "mycompany@example.com", + agreeToTerms: true +}); ``` @@ -256,14 +383,17 @@ A Let's Encrypt SSL certificate has a "Subject" (Primary Domain) and up to 100 " (of which the first _must_ be the subject). ```bash -# COMING SOON -# (this command should be here by Nov 5th) -# (edit the config by hand for now) -# # Add a certificate with specific domains npx greenlock add --subject example.com --altnames example.com,www.example.com ``` +```js +greenlock.sites.add({ + subject: "example.com", + altnames: ["example.com"] +}); +``` + Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require @@ -278,14 +408,12 @@ Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require # Plenty of Examples -**These are in-progress** Check back tomorrow (Nov 2nd, 2019). - - [greenlock-express.js/examples/](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples) - [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/) + - [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) @@ -301,9 +429,15 @@ 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'` - [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` - [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` - [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 # Ready-made Integrations @@ -327,6 +461,13 @@ Greenlock Express integrates between Let's Encrypt's ACME Challenges and many po | http-01 | [Build your own](https://git.rootprojects.org/root/acme-http-01-test.js) | acme-http-01-test | | tls-alpn-01 | [Contact us](mailto:support@therootcompany.com) | - | +Example Usage: + +```bash +npx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx +npx greenlock defaults --challenge-http-01 acme-http-01-s3 --challenge-http-01-bucket my-bucket +``` + Search `acme-http-01-` or `acme-dns-01-` on npm to find more. # Full Documentation @@ -374,3 +515,4 @@ 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/package-lock.json b/package-lock.json index 3873285..83d918a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,9 +1,17 @@ { "name": "greenlock-express", - "version": "3.0.15", + "version": "3.1.0", "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==", + "requires": { + "greenlock-manager-fs": "^3.0.5" + } + }, "@root/acme": { "version": "3.0.8", "resolved": "https://registry.npmjs.org/@root/acme/-/acme-3.0.8.tgz", @@ -40,19 +48,20 @@ "integrity": "sha512-OaEub02ufoU038gy6bsNHQOjIn8nUjGiLcaRmJ40IUykneJkIW5fxDqKxQx48cszuNflYldsJLPPXCrGfHs8yQ==" }, "@root/greenlock-express": { - "version": "3.0.15", - "resolved": "https://registry.npmjs.org/@root/greenlock-express/-/greenlock-express-3.0.15.tgz", - "integrity": "sha512-TrdU0BdV7heDr4o5mrIbaPLtaskPYvyDlDWmTYVInyYmgc12tEk2vHJx5KZlVQSkZPi6jnc/v606R18zTezchA==", + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/@root/greenlock-express/-/greenlock-express-3.1.0.tgz", + "integrity": "sha512-KxsBKobvQ3YKlfjSsAFSN2jvkRdkn8CrVKP2swVoiXtrduBgqDMfAaE85S+Wiz17wmk42na0369TqLPp8wzEjQ==", "requires": { - "@root/greenlock": "^3.0.27", + "@root/greenlock": "^3.1.3", "redirect-https": "^1.1.5" }, "dependencies": { "@root/greenlock": { - "version": "3.0.27", - "resolved": "https://registry.npmjs.org/@root/greenlock/-/greenlock-3.0.27.tgz", - "integrity": "sha512-M8qVeGa6WkL+6MK5zm1XRhP9n1fwuUlea/LS8PH3DWxf99s+77nIiK3AFPjFYNrRzKyPsWHICRLKLdK7o+F7gA==", + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/@root/greenlock/-/greenlock-3.1.3.tgz", + "integrity": "sha512-9Rj9JIKYItOvZKbPa5JrljS74dw+KjltOyQnb14y4nX89C+s1mZjv3Qiv1cNuYkYCmBGR77z0/cKnfUUaWxkag==", "requires": { + "@greenlock/manager": "^3.0.0", "@root/acme": "^3.0.8", "@root/csr": "^0.8.1", "@root/keypairs": "^0.9.0", @@ -60,7 +69,7 @@ "@root/request": "^1.3.10", "acme-http-01-standalone": "^3.0.5", "cert-info": "^1.5.1", - "greenlock-manager-fs": "^3.0.3", + "greenlock-manager-fs": "^3.0.5", "greenlock-store-fs": "^3.2.0", "safe-replace": "^1.1.0" } @@ -117,18 +126,18 @@ "integrity": "sha1-Aljq5NPQwJdN4cFpGI7wBR0dGYg=" }, "greenlock-manager-fs": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/greenlock-manager-fs/-/greenlock-manager-fs-3.0.3.tgz", - "integrity": "sha512-Jwo60nHd10PNUA9M6cylD9YB4x4hzlfO2LRIGI0X+V+zA0x3KVbNW14yj8frdfHrtsWC1JQe7oFnHVdoRbAU2A==", + "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==", "requires": { "@root/mkdirp": "^1.0.0", "safe-replace": "^1.1.0" } }, "greenlock-store-fs": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/greenlock-store-fs/-/greenlock-store-fs-3.2.0.tgz", - "integrity": "sha512-zqcPnF+173oYq5qU7FoGtuqeG8dmmvAiSnz98kEHAHyvgRF9pE1T0MM0AuqDdj45I3kXlCj2gZBwutnRi37J3g==", + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/greenlock-store-fs/-/greenlock-store-fs-3.2.2.tgz", + "integrity": "sha512-92ejLB4DyV4qv/2b6VLGF2nKfYQeIfg3o+e/1cIoYLjlIaUFdbBXkzLTRozFlHsQPZt2ALi5qYrpC9IwH7GK8A==", "requires": { "@root/mkdirp": "^1.0.0", "safe-replace": "^1.1.0" diff --git a/package.json b/package.json index 027ed6f..be7facd 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "greenlock-express", - "version": "3.0.15", + "version": "3.1.0", "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.0.27", - "@root/greenlock-express": "^3.0.15", + "@root/greenlock": "^3.1.3", + "@root/greenlock-express": "^3.1.0", "redirect-https": "^1.1.5" }, "trulyOptionalDependencies": {