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": {