greenlock-express.js/README.md

454 lines
21 KiB
Markdown
Raw Normal View History

2019-05-16 04:19:58 +00:00
![Greenlock Logo](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo")
2018-05-12 07:46:56 +00:00
2019-05-16 04:19:58 +00:00
!["Greenlock Function"](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/from-not-secure-to-secure-url-bar.png "from url bar showing not secure to url bar showing secure")
2018-05-16 20:56:52 +00:00
2018-06-23 20:40:03 +00:00
<table>
2018-06-23 20:31:04 +00:00
<tr>
2019-05-16 04:19:58 +00:00
<td><a href="https://medium.com/@bohou/secure-your-nodejs-server-with-letsencrypt-for-free-f8925742faa9" target="_blank"><img src="https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/ibm-301x112.png"></a></td>
<td><a href="https://github.com/mozilla-iot/le-store-certbot/issues/4" target="_blank"><img src="https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/mozilla-iot-301x112.png"></a></td>
<td><a href="https://github.com/digitalbazaar/bedrock-letsencrypt" target="_blank"><img src="https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/digital-bazaar-301x112.png"></a></td>
2018-06-23 20:31:04 +00:00
</tr>
2018-06-23 20:40:03 +00:00
</table>
<table>
2018-06-23 20:31:04 +00:00
<tr>
2019-05-16 04:19:58 +00:00
<td><a href="https://github.com/beakerbrowser/homebase" target="_blank"><img src="https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/beaker-browser-301x112.png"></a></td>
<td><a href="https://telebit.cloud" target="_blank"><img src="https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/telebit-301x112.png"></a></td>
<td><a href="https://rootprojects.org" target="_blank"><img src="https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/ppl-301x112.png"></a></td>
2018-06-23 20:31:04 +00:00
</tr>
2018-06-23 20:40:03 +00:00
</table>
2018-06-23 20:38:38 +00:00
2019-05-16 04:19:58 +00:00
# [Greenlock](https://git.rootprojects.org/root/greenlock-express.js)&trade; for Express.js
2018-05-31 21:14:23 +00:00
<small>formerly letsencrypt-express</small>
2018-05-14 23:42:54 +00:00
Free SSL, Free Wildcard SSL, and Fully Automated HTTPS made dead simple<br>
2019-05-16 04:19:58 +00:00
<small>certificates issued by Let's Encrypt v2 via [ACME](https://git.rootprojects.org/root/acme-v2.js)</small>
2018-05-10 06:53:45 +00:00
2018-05-14 23:36:12 +00:00
!["Lifetime Downloads"](https://img.shields.io/npm/dt/greenlock.svg "Lifetime Download Count can't be shown")
!["Monthly Downloads"](https://img.shields.io/npm/dm/greenlock.svg "Monthly Download Count can't be shown")
!["Weekly Downloads"](https://img.shields.io/npm/dw/greenlock.svg "Weekly Download Count can't be shown")
2018-05-16 01:13:58 +00:00
!["Stackoverflow Questions"](https://img.shields.io/stackexchange/stackoverflow/t/greenlock.svg "S.O. Question count can't be shown")
2018-05-26 01:25:27 +00:00
<a href="https://twitter.com/intent/follow?screen_name=GreenlockHTTPS"><img src="https://img.shields.io/twitter/url/http/shields.io.svg?style=social&label=Follow%20@GreenlockHTTPS" title="Follow @GreenlockHTTPS on Twitter" alt="Twitter Badge"></a>
2018-05-10 06:53:45 +00:00
| A [Root](https://rootprojects.org) Project |
2019-05-16 04:19:58 +00:00
[Greenlock&trade;](https://git.rootprojects.org/root/greenlock.js) is for
[Web Servers](https://git.rootprojects.org/root/greenlock-cli.js),
[Web Browsers](https://greenlock.domains),
2018-05-14 23:39:59 +00:00
and **node.js middleware systems**.
2018-04-20 06:43:02 +00:00
# Features
2018-05-10 06:53:45 +00:00
- [x] Automatic HTTPS
- [x] Free SSL
- [x] Free Wildcard SSL
- [x] Multiple domain support (up to 100 altnames per SAN)
- [x] Dynamic Virtual Hosting (vhost)
- [x] Automatical renewal (10 to 14 days before expiration)
- [x] Great ACME support
- [x] ACME draft 11
- [x] Let's Encrypt v2
- [x] Let's Encrypt v1
- [x] Full node.js support
- [x] core https module
- [x] Express.js
2019-05-16 04:19:58 +00:00
- [x] [Koa](https://git.rootprojects.org/root/greenlock-koa.js)
- [x] [hapi](https://git.rootprojects.org/root/greenlock-hapi.js)
2018-05-11 20:03:02 +00:00
- [x] Extensible Plugin Support
- [x] AWS (S3, Route53)
- [x] Azure
- [x] CloudFlare
2018-05-11 20:27:53 +00:00
- [x] Consul
2018-05-11 20:03:02 +00:00
- [x] Digital Ocean
- [x] etcd
- [x] Redis
2016-08-15 23:12:39 +00:00
# Install
2016-08-12 07:02:33 +00:00
```bash
2017-01-25 22:02:16 +00:00
npm install --save greenlock-express@2.x
2016-08-12 07:02:33 +00:00
```
# QuickStart
<!-- TODO better quickstart (fewer options) -->
2018-04-23 19:55:03 +00:00
2018-04-23 20:02:50 +00:00
### Screencast
2018-08-18 09:46:48 +00:00
Watch the QuickStart demonstration: [https://youtu.be/e8vaR4CEZ5s](https://youtu.be/e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk)
2018-04-23 20:02:50 +00:00
2018-08-18 09:45:11 +00:00
<a href="https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk"><img src="https://i.imgur.com/Y8ix6Ts.png" title="QuickStart Video" alt="YouTube Video Preview" /></a>
2018-05-24 04:39:24 +00:00
2018-08-18 09:45:11 +00:00
* [0:00](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk#t=0) - Intro
* [2:22](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk#t=142) - Demonstrating QuickStart Example
* [6:37](https://www.youtube.com/watch?v=e8vaR4CEZ5s&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk?t=397) - Troubleshooting / Gotchas
#### Beyond the QuickStart (Part 2)
* [1:00](https://www.youtube.com/watch?v=bTEn93gxY50&index=2&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk&t=60) - Bringing Greenlock into an Existing Express Project
* [2:26](https://www.youtube.com/watch?v=bTEn93gxY50&index=2&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk&t=146) - The `approveDomains` callback
#### Security Concerns (Part 3)
* [0:00](https://www.youtube.com/watch?v=aZgVqPzoZTY&index=3&list=PLZaEVINf2Bq_lrS-OOzTUJB4q3HxarlXk) - Potential Attacks, and Mitigation
2018-04-23 20:02:50 +00:00
### Working Example Code
2018-04-20 07:14:39 +00:00
Here's a completely working example that will get you started.
2018-04-20 08:59:33 +00:00
```
2019-05-16 04:19:58 +00:00
git clone https://git.rootprojects.org/root/greenlock-express.js.git
2018-04-20 08:59:33 +00:00
pushd greenlock-express.js
npm install
popd
# edit 'email' and 'approveDomains' in
# greenlock-express.js/examples/simple.js
node greenlock-express.js/examples/simple.js
```
2018-04-20 07:14:39 +00:00
All you have to do is start the webserver and then visit it at its domain name.
2016-08-12 07:02:33 +00:00
`server.js`:
2016-08-12 07:02:33 +00:00
```javascript
'use strict';
2017-01-25 22:02:16 +00:00
require('greenlock-express').create({
email: 'john.doe@example.com' // The email address of the ACME user / hosting provider
, agreeTos: true // You must accept the ToS as the host which handles the certs
, configDir: '~/.config/acme/' // Writable directory where certs will be saved
, communityMember: true // Join the community to get notified of important updates
, telemetry: true // Contribute telemetry data to the project
2016-08-12 07:02:33 +00:00
// Using your express app:
// simply export it as-is, then include it here
, app: require('./app.js')
//, debug: true
}).listen(80, 443);
```
2016-08-16 01:15:16 +00:00
`app.js`:
```js
'use strict';
2016-08-12 07:02:33 +00:00
var express = require('express');
var app = express();
2018-05-10 06:53:45 +00:00
app.use('/', function (req, res) {
res.setHeader('Content-Type', 'text/html; charset=utf-8')
res.end('Hello, World!\n\n💚 🔒.js');
})
2018-05-26 01:28:11 +00:00
// Don't do this:
// app.listen(3000)
// Do this instead:
module.exports = app;
2016-08-12 07:02:33 +00:00
```
### `communityMember`
If you're the kind of person that likes the kinds of stuff that I do,
well, I want to do more of it and I'd like to get you involved.
As expected, by default we keep your email private and only use it for
transactional messaging, urgent security or API updates
(such as the mandatory upgrade to Let's Encrypt v2), and ACME account registration.
However, when you set the `communityMember` option to `true` we'll also
inform you when there are meaningful and relavant feature updates (no bugfix noise),
and give you early access to similar projects.
You can see our full privacy policy at <https://greenlock.domains/legal/#privacy>.
### What if the example didn't work?
2018-04-20 07:23:22 +00:00
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?
* **correct ACME version**
* Let's Encrypt **v2** (ACME v2) must use `version: 'draft-11'`
* Let's Encrypt v1 must use `version: 'v01'`
* **valid email**
* You MUST set `email` 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 ~/acme/etc/tmp.tmp`)
* **port binding privileges**
2018-04-21 02:24:50 +00:00
* You MUST be able to bind to ports 80 and 443
2018-04-20 07:23:22 +00:00
* 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**
2018-05-19 23:54:08 +00:00
* You MUST use the **production** server url, not staging
* The API URL should not have 'acme-staging-v02', but should have 'acme-v02'
* Delete the `configDir` used for getting certificates in staging
2016-08-12 07:02:33 +00:00
2018-05-19 23:54:08 +00:00
### Production vs Staging
If at first you don't succeed, stop and switch to staging.
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
There are a number of common problems related to system configuration -
firewalls, ports, permissions, etc - that you are likely to run up against
2017-01-25 22:02:16 +00:00
when using greenlock for your first time.
2016-08-12 07:02:33 +00:00
2018-05-19 23:54:08 +00:00
I've put a "dry run" in place with built-in diagnostics, so hopefully
you get everything right on your first or second try.
However, in order to avoid being blocked by hitting the bad request rate limits
you should switch to using the `staging` server for any testing or debugging.
```
https://acme-staging-v02.api.letsencrypt.org/directory
```
2016-08-12 07:02:33 +00:00
## Working Examples
2018-08-18 10:00:25 +00:00
| Example | Location + Description |
|:---------------:|:---------:|
2019-05-16 04:19:58 +00:00
| **QuickStart** | [examples/quickstart.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/quickstart.js) uses the fewest options and accepts all default settings. It's guaranteed to work for you. |
| Production | [examples/production.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/production.js) shows how to require an express app (or other middleware system), expand the `approveDomains` callback, provides an example database shim, and exposes the server instance. |
| Virtual&nbsp;Hosting | [examples/vhost.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/vhost.js) shows how to dynamically secure and serve domains based on their existance on the file system. |
| Wildcard&nbsp;Domains | [examples/wildcard.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcard.js) shows how to use the `greenlock-challenge-dns` and wildcard cetificates. |
| HTTPS&nbsp;(raw) | [examples/spdy.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/spdy.js) demonstrates how to manually configure a node web server using the node's built-in `http` and `https` modules. |
| HTTP2&nbsp;(spdy) | Presently spdy is incompatible with node v11, but [examples/spdy.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/spdy.js) demonstrates how to manually configure a node web server with spdy-compatible versions of node and Greenlock. |
| HTTP2&nbsp;(node) | [examples/http2.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http2.js) uses node's new HTTP2 module, which is NOT compatible with the existing middleware systems (and is not "stable" as of v10.0). |
| WebSockets&nbsp;(ws) | [examples/websockets.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/websockets.js) demonstrates how to use Greenlock express with a websocket server. |
| socket.io | [examples/socket.io.js](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/socket.io.js) demonstrates how to use Greenlock express with socket.io (even though `ws` is far simpler, faster, and better and every way). |
2019-04-27 06:54:10 +00:00
| - | Build Your Own <br> Be sure to tell me ([@coolaj86](https://twitter.com/@coolaj86)) / us ([@GreenlockHTTPS](https://twitter.com/@GreenlockHTTPS)) about it. :) |
2019-05-16 04:19:58 +00:00
| Full&nbsp;List | Check out the [examples/](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples) directory |
2018-08-18 10:00:25 +00:00
# Plugins
2018-04-30 15:46:34 +00:00
**IMPORTANT**: Community plugins may or may not be maintained and working. Please try with the defaults before switching to community plugins.
2018-04-30 15:42:33 +00:00
## HTTP-01 Challenges
2018-05-11 19:58:37 +00:00
| | Plugin |
|:--------------:|:---------:|
2019-04-27 05:54:20 +00:00
| **Default (fs)** | [acme-http-01-cli](https://git.rootprojects.org/root/acme-http-01-cli.js) |
2019-05-10 04:23:09 +00:00
| AWS S3 | [acme-http-01-s3](https://git.rootprojects.org/root/acme-http-01-s3.js) |
2018-05-11 20:13:16 +00:00
| Azure | [kolarcz/node-le-challenge-azure-storage](https://github.com/kolarcz/node-le-challenge-azure-storage) |
2019-04-26 20:53:37 +00:00
| - | Build Your Own <br> [greenlock-challenge-test](https://git.rootprojects.org/root/greenlock-challenge-test.js) |
2019-04-27 05:54:20 +00:00
| Full List | Search [acme-http-01-](https://www.npmjs.com/search?q=acme-http-01-) or [le-challenge-](https://www.npmjs.com/search?q=le-challenge-) on npm |
2018-05-11 19:58:37 +00:00
## DNS-01 Challenges
2018-05-11 19:58:37 +00:00
| | Plugin |
|:--------------:|:---------:|
2019-04-27 05:54:20 +00:00
| **Manual (cli)** | [acme-dns-01-cli](https://git.rootprojects.org/root/acme-dns-01-cli.js) |
2018-05-11 19:58:37 +00:00
| AWS Route 53 | [thadeetrompetter/le-challenge-route53](https://github.com/thadeetrompetter/le-challenge-route53) |
| CloudFlare | [buschtoens/le-challenge-cloudflare](https://github.com/buschtoens/le-challenge-cloudflare) |
| CloudFlare | [llun/le-challenge-cloudflare](https://github.com/llun/le-challenge-cloudflare) |
| Digital Ocean | [bmv437/le-challenge-digitalocean](https://github.com/bmv437/le-challenge-digitalocean) |
2018-05-11 20:03:02 +00:00
| etcd | [ceecko/le-challenge-etcd](https://github.com/ceecko/le-challenge-etcd) |
2019-04-26 20:53:37 +00:00
| - | Build Your Own <br> [greenlock-challenge-test](https://git.rootprojects.org/root/greenlock-challenge-test.js) |
2019-04-27 05:54:20 +00:00
| Full List | Search [acme-dns-01-](https://www.npmjs.com/search?q=acme-dns-01-) or [le-challenge-](https://www.npmjs.com/search?q=le-challenge-) on npm |
2018-05-11 19:58:37 +00:00
## Account & Certificate Storage
2018-05-11 19:58:37 +00:00
2018-05-12 02:51:22 +00:00
| | Plugin |
2018-05-11 19:58:37 +00:00
|:--------------:|:---------:|
2019-04-27 05:54:20 +00:00
| **Simplest** | [greenlock-store-fs](https://git.rootprojects.org/root/greenlock-store-fs.js) |
2019-04-03 05:37:23 +00:00
| certbot (v2 default) | [le-store-certbot](https://git.coolaj86.com/coolaj86/le-store-certbot.js) |
2019-05-10 04:23:09 +00:00
| AWS S3 | [gl-store-s3](https://git.rootprojects.org/root/gl-store-s3.js) |
2018-05-11 20:27:53 +00:00
| Consul | [sebastian-software/le-store-consul](https://github.com/sebastian-software/le-store-consul) |
2018-05-11 19:58:37 +00:00
| json (fs) | [paulgrove/le-store-simple-fs](https://github.com/paulgrove/le-store-simple-fs)
| Redis | [digitalbazaar/le-store-redis](https://github.com/digitalbazaar/le-store-redis) |
2019-04-26 20:53:37 +00:00
| - | Build Your Own <br> [greenlock-store-test](https://git.rootprojects.org/root/greenlock-store-test.js) |
2018-05-11 20:11:11 +00:00
| Full List | Search [le-store-](https://www.npmjs.com/search?q=le-store-) on npm |
2018-04-30 15:42:33 +00:00
## Auto-SNI
2018-05-12 02:51:22 +00:00
| | Plugin |
|:-----------:|:---------:|
2018-07-03 20:45:34 +00:00
| **Default** | [le-sni-auto](https://git.coolaj86.com/coolaj86/le-sni-auto.js) |
2018-05-12 02:51:22 +00:00
(you probably wouldn't need or want to replace this)
**Bugs**: Please report bugs with the community plugins to the appropriate owner first, then here if you don't get a response.
2018-04-30 15:46:34 +00:00
# Usage
2016-08-15 23:12:39 +00:00
The oversimplified example was the bait
(because everyone seems to want an example that fits in 3 lines, even if it's terribly bad practices),
2018-04-20 08:59:33 +00:00
now here's the switch.
We have another completely working example that will provides a little more to build off of.
```
2019-05-16 04:19:58 +00:00
git clone https://git.rootprojects.org/root/greenlock-express.js.git
2018-04-20 08:59:33 +00:00
pushd greenlock-express.js
npm install
popd
# replace 'fooCheckDb' in
# greenlock-express.js/examples/normal.js
node greenlock-express.js/examples/normal.js
```
It looks a little more like this:
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
`serve.js`:
```javascript
'use strict';
2016-08-12 07:02:33 +00:00
2018-04-20 05:32:15 +00:00
// returns an instance of greenlock.js with additional helper methods
var glx = require('greenlock-express').create({
2018-05-19 23:54:08 +00:00
server: 'https://acme-v02.api.letsencrypt.org/directory'
// Note: If at first you don't succeed, stop and switch to staging:
// https://acme-staging-v02.api.letsencrypt.org/directory
2018-04-20 03:37:56 +00:00
, version: 'draft-11' // Let's Encrypt v2 (ACME v2)
2016-08-12 07:02:33 +00:00
2018-05-12 02:33:22 +00:00
// If you wish to replace the default account and domain key storage plugin
2018-05-12 02:51:22 +00:00
, store: require('le-store-certbot').create({
configDir: require('path').join(require('os').homedir(), 'acme', 'etc')
, webrootPath: '/tmp/acme-challenges'
})
2016-08-12 07:48:21 +00:00
2018-05-26 01:28:11 +00:00
// Contribute telemetry data to the project
, telemetry: true
// the default servername to use when the client doesn't specify
// (because some IoT devices don't support servername indication)
, servername: 'example.com'
2016-08-17 15:11:10 +00:00
, approveDomains: approveDomains
2016-08-15 23:12:39 +00:00
});
var server = glx.listen(80, 443, function () {
console.log("Listening on port 80 for ACME challenges and 443 for express app.");
});
2016-08-17 15:09:43 +00:00
```
2016-08-12 07:02:33 +00:00
Note: You shouldn't be using the plain HTTP server for anything except, potentially, for error handling
on the listen event (if the default print-and-quit behavior doesn't work for your use case).
If you need to do that, here's how:
```
var plainServer = server.unencrypted;
plainServer.on('error', function (err) { ... });
```
2018-04-20 07:09:34 +00:00
The Automatic Certificate Issuance is initiated via SNI (`httpsOptions.SNICallback`).
For security, domain validation MUST have an approval callback in *production*.
2016-08-17 15:11:10 +00:00
```javascript
2018-05-12 02:29:21 +00:00
var http01 = require('le-challenge-fs').create({ webrootPath: '/tmp/acme-challenges' });
2016-08-17 15:11:10 +00:00
function approveDomains(opts, certs, cb) {
// This is where you check your database and associated
// email addresses with domains and agreements and such
// if (!isAllowed(opts.domains)) { return cb(new Error("not allowed")); }
// The domains being approved for the first time are listed in opts.domains
// Certs being renewed are listed in certs.altnames (if that's useful)
2016-08-17 15:11:10 +00:00
2018-05-12 02:29:21 +00:00
// Opt-in to submit stats and get important updates
2018-05-10 06:53:45 +00:00
opts.communityMember = true;
2016-08-17 15:11:10 +00:00
2018-05-12 02:33:22 +00:00
// If you wish to replace the default challenge plugin, you may do so here
2018-05-12 02:29:21 +00:00
opts.challenges = { 'http-01': http01 };
2018-11-05 07:14:22 +00:00
opts.email = 'john.doe@example.com';
opts.agreeTos = true;
2016-08-17 15:11:10 +00:00
// NOTE: you can also change other options such as `challengeType` and `challenge`
// opts.challengeType = 'http-01';
// opts.challenge = require('le-challenge-fs').create({});
2016-08-17 15:11:10 +00:00
cb(null, { options: opts, certs: certs });
}
```
2016-08-12 07:02:33 +00:00
2016-08-17 15:09:43 +00:00
```javascript
2016-08-15 23:12:39 +00:00
// handles acme-challenge and redirects to https
require('http').createServer(glx.middleware(require('redirect-https')())).listen(80, function () {
2016-08-15 23:12:39 +00:00
console.log("Listening for ACME http-01 challenges on", this.address());
});
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
var app = require('express')();
app.use('/', function (req, res) {
res.end('Hello, World!');
});
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
// handles your app
require('https').createServer(glx.httpsOptions, app).listen(443, function () {
2016-08-15 23:12:39 +00:00
console.log("Listening for ACME tls-sni-01 challenges and serve app on", this.address());
});
2016-08-12 07:02:33 +00:00
```
**Security**:
2016-08-17 15:25:07 +00:00
Greenlock will do a self-check on all domain registrations
to prevent you from hitting rate limits.
2016-08-17 15:25:07 +00:00
# API
2016-08-12 07:56:19 +00:00
2016-08-16 01:15:16 +00:00
This module is an elaborate ruse (to provide an oversimplified example and to nab some SEO).
2019-05-16 04:19:58 +00:00
The API is actually located at [greenlock.js options](https://git.rootprojects.org/root/greenlock.js)
2018-04-20 05:32:15 +00:00
(because all options are simply passed through to `greenlock.js` proper without modification).
2016-08-15 23:12:39 +00:00
2018-04-20 05:32:15 +00:00
The only "API" consists of two options, the rest is just a wrapper around `greenlock.js` to take LOC from 15 to 5:
2016-08-15 23:12:39 +00:00
2016-08-16 01:15:16 +00:00
* `opts.app` An express app in the format `function (req, res) { ... }` (no `next`).
* `server = glx.listen(plainAddr, tlsAddr, onListen)` Accepts port numbers (or arrays of port numbers) to listen on, returns secure server.
* `listen(80, 443)`
* `listen(80, 443, onListenSecure)`
* `listen(80, 443, onListenPlain, onListenSecure)`
* `listen('localhost:80', '0.0.0.0:443')`
* `listen('[::1]:80', '[::]:443')`
* `listen('/tmp/glx.plain.sock', '/tmp/glx.secure.sock')`
2016-08-12 07:56:19 +00:00
2018-04-20 05:32:15 +00:00
Brief overview of some simple options for `greenlock.js`:
2016-08-12 07:56:19 +00:00
2018-04-20 05:32:15 +00:00
* `opts.server` set to https://acme-v02.api.letsencrypt.org/directory in production
2018-04-20 03:37:56 +00:00
* `opts.version` set to `v01` for Let's Encrypt v1 or `draft-11` for Let's Encrypt v2 (mistakenly called ACME v2)
2016-08-16 01:15:16 +00:00
* `opts.email` The default email to use to accept agreements.
* `opts.agreeTos` When set to `true`, this always accepts the LetsEncrypt TOS. When a string it checks the agreement url first.
2018-05-10 07:00:44 +00:00
* `opts.communityMember` Join the community to get notified of important updates and help make greenlock better
2016-08-17 15:25:07 +00:00
* `opts.approveDomains` can be either of:
* An explicit array of allowed domains such as `[ 'example.com', 'www.example.com' ]`
* A callback `function (opts, certs, cb) { cb(null, { options: opts, certs: certs }); }` for setting `email`, `agreeTos`, `domains`, etc (as shown in usage example above)
2016-08-16 01:15:16 +00:00
* `opts.renewWithin` is the **maximum** number of days (in ms) before expiration to renew a certificate.
* `opts.renewBy` is the **minimum** number of days (in ms) before expiration to renew a certificate.
2018-05-03 00:55:35 +00:00
## Supported ACME versions
* Let's Encrypt v1 (aka v01)
* Let's Encrypt v2 (aka v02 or ACME draft 11)
* ACME draft 11 (ACME v2 is a misnomer)
2018-05-10 07:00:44 +00:00
* Wildcard domains (via dns-01 challenges)
2018-05-10 06:53:45 +00:00
* `*.example.com`
2018-05-31 21:14:23 +00:00
<small>tags: letsencrypt acme free ssl automated https node express.js</small>
2019-05-16 04:19:58 +00:00
# Legal &amp; Rules of the Road
2019-05-16 04:19:58 +00:00
Greenlock&trade; is a [trademark](https://rootprojects.org/legal/#trademark) of AJ ONeal
2019-05-16 04:19:58 +00:00
The rule of thumb is "attribute, but don't confuse". For example:
> Built with [Greenlock CLI](https://git.rootprojects.org/root/greenlock-cli.js) (a [Root](https://rootprojects.org) project).
Please [contact us](mailto:aj@therootcompany.com) if you have any questions in regards to our trademark,
attribution, and/or visible source policies. We want to build great software and a great community.
[Greenlock&trade;](https://git.rootprojects.org/root/greenlock.js) |
MPL-2.0 |
[Terms of Use](https://therootcompany.com/legal/#terms) |
[Privacy Policy](https://therootcompany.com/legal/#privacy)