greenlock-express.js/README.md

176 lines
5.9 KiB
Markdown
Raw Normal View History

2016-08-15 23:12:39 +00:00
[![Join the chat at https://gitter.im/Daplie/letsencrypt-express](https://badges.gitter.im/Daplie/letsencrypt-express.svg)](https://gitter.im/Daplie/letsencrypt-express?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
| [letsencrypt (library)](https://github.com/Daplie/node-letsencrypt)
| [letsencrypt-cli](https://github.com/Daplie/letsencrypt-cli)
| **letsencrypt-express**
| [letsencrypt-koa](https://github.com/Daplie/letsencrypt-koa)
| [letsencrypt-hapi](https://github.com/Daplie/letsencrypt-hapi)
|
letsencrypt-express
2016-08-12 07:02:33 +00:00
===================
2016-08-10 07:43:11 +00:00
2016-08-15 23:12:39 +00:00
Free SSL and managed or automatic HTTPS for node.js with Express, Koa, Connect, Hapi, and all other middleware systems.
* Automatic Registration via SNI (`httpsOptions.SNICallback`)
* **registrations** require an **approval callback** in *production*
* Automatic Renewal (around 80 days)
* **renewals** are *fully automatic* and happen in the *background*, with **no downtime**
* Automatic vhost / virtual hosting
All you have to do is start the webserver and then visit it at it's domain name.
Help Wanted
-----------
There are a number of easy-to-complete features that are up for grabs.
(mostly requiring either tracing some functions and doing some console.log-ing
or simply updating docs and getting tests to pass so that certain plugins accept
and return the right type of objects to complete the implementation
of certain plugins).
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
If you've got some free cycles to help, I can guide you through the process,
I'm just still too busy to do it all myself right now and nothing is breaking.
Email me <aj@daplie.com> if you want to help.
2016-08-12 07:02:33 +00:00
Install
=======
```bash
2016-08-15 23:12:39 +00:00
npm install --save letsencrypt-express@2.x
2016-08-12 07:02:33 +00:00
```
Usage
=====
2016-08-15 23:12:39 +00:00
QuickStart
----------
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
Here's a completely working (but terribly oversimplified) example that will get you started:
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
`app.js`:
2016-08-12 07:02:33 +00:00
```javascript
'use strict';
2016-08-15 23:12:39 +00:00
require('letsencrypt-express').create({
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
server: 'staging'
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
, email: 'john.doe@example.com'
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
, agreeTos: true
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
, app: require('express')().use('/', function (req, res) {
res.end('Hello, World!');
})
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
}).listen(80, 443);
2016-08-12 07:02:33 +00:00
```
2016-08-15 23:12:39 +00:00
Certificates will be stored in `~/letsencrypt`.
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
**Important**:
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
You must set `server` to `https://acme-v01.api.letsencrypt.org/directory` **after**
you have tested that your setup works.
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
**Security Warning**:
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
If you don't do proper checks in `approveDomains(opts, certs, cb)`
an attacker will spoof SNI packets with bad hostnames and that will
cause you to be rate-limited and or blocked from the ACME server.
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
Why You Must Use 'staging' First
--------------------------------
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
when using letsencrypt for your first time.
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
In order to avoid being blocked by hitting rate limits with bad requests,
you should always test against the `'staging'` server
(`https://acme-staging.api.letsencrypt.org/directory`) first.
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
A more typical example
----------------------
2016-08-12 07:02:33 +00:00
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),
now here's the switch:
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
2016-08-15 23:12:39 +00:00
// returns an instance of node-letsencrypt with additional helper methods
var lex = require('letsencrypt-express').create({
server: 'staging'
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
// If you wish to replace the default plugins, you may do so here
//
//, challenges: { 'http-01:' require('le-challenge-fs').create({}) }
//, store: require('le-store-certbot').create({})
//, sni: require('le-sni-auto').create({})
2016-08-12 07:48:21 +00:00
2016-08-15 23:12:39 +00:00
, approveDomains: function (opts, certs, cb) {
// This is where you check your database and associated
// email addresses with domains and agreements and such
2016-08-12 07:48:21 +00:00
2016-08-15 23:12:39 +00:00
// The domains being approved for the first time are listed in opts.domains
// Certs being renewed are listed in certs.altnames
if (certs) {
opts.domains = certs.altnames;
}
else {
opts.email = 'john.doe@example.com';
opts.agreeTos = true;
}
2016-08-12 07:48:21 +00:00
2016-08-15 23:12:39 +00:00
cb(null, opts);
}
});
2016-08-12 07:02:33 +00:00
2016-08-15 23:12:39 +00:00
// handles acme-challenge and redirects to https
require('http').createServer(lex.middleware()).listen(80, function () {
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(lex.httpsOptions, lex.middleware(app)).listen(443, function () {
console.log("Listening for ACME tls-sni-01 challenges and serve app on", this.address());
});
2016-08-12 07:02:33 +00:00
```
2016-08-12 07:56:19 +00:00
### API
2016-08-15 23:12:39 +00:00
All options are passed directly to `node-letsencrypt`,
so `lex` is an instance of `letsencrypt`, but has a few
extra helper methods and options.
See [node-letsencrypt options](https://github.com/Daplie/node-letsencrypt)
* `lexOptions.approveDomains(options, certs, cb)` is special for `letsencrypt-express`, but will probably be included in `node-letsencrypt` in the future (no API change).
2016-08-12 07:56:19 +00:00
2016-08-15 23:12:39 +00:00
* `lexOptions.app` is just an elaborate ruse used for the Quickstart. It's sole purpose is to trim out 5 lines of code for setting http and https servers so that whiners won't whine. Real programmers don't use this.
* `leOptions.email` useful for simple sites where there is only one owner. Leave this `null` and use `approveDomains` otherwise.
* `leOptions.agreeTos` useful for simple sites where there is only one owner. Leave this `null` and use `approveDomains` otherwise.
2016-08-12 07:56:19 +00:00
* `leOptions.renewWithin` is shared so that the worker knows how earlier to request a new cert
* `leOptions.renewBy` is passed to `le-sni-auto` so that it staggers renewals between `renewWithin` (latest) and `renewBy` (earlier)
2016-08-15 23:12:39 +00:00
* `lex.middleware(nextApp)` uses `letsencrypt/middleware` for GET-ing `http-01`, hence `sharedOptions.webrootPath`
* `lex.httpsOptions` has a default localhost certificate and the `SNICallback`.
2016-08-12 07:56:19 +00:00
There are a few options that aren't shown in these examples, so if you need to change something
that isn't shown here, look at the code (it's not that much) or open an issue.