greenlock-rill.js/README.md

106 lines
3.5 KiB
Markdown
Raw Normal View History

2016-12-30 09:40:33 +00:00
<!-- BANNER_TPL_BEGIN -->
2016-12-30 09:22:43 +00:00
About Daplie: We're taking back the Internet!
2016-11-02 00:31:07 +00:00
--------------
2016-12-30 09:22:43 +00:00
Down with Google, Apple, and Facebook!
We're re-decentralizing the web and making it read-write again - one home cloud system at a time.
Tired of serving the Empire? Come join the Rebel Alliance:
2016-11-02 00:31:07 +00:00
2016-12-30 09:22:43 +00:00
<a href="mailto:jobs@daplie.com">jobs@daplie.com</a> | [Invest in Daplie on Wefunder](https://daplie.com/invest/) | [Pre-order Cloud](https://daplie.com/preorder/), The World's First Home Server for Everyone
2016-11-02 00:31:07 +00:00
2016-12-30 09:40:33 +00:00
<!-- BANNER_TPL_END -->
2016-11-02 00:31:07 +00:00
2017-01-14 20:49:29 +00:00
# greenlock-koa (letsencrypt-koa)
2016-11-02 00:31:07 +00:00
2016-04-22 18:12:45 +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)
2017-01-14 20:49:29 +00:00
| [letsencrypt (lib)](https://git.daplie.com/Daplie/node-letsencrypt)
| [letsencrypt-cli](https://git.daplie.com/Daplie/letsencrypt-cli)
| [letsencrypt-express](https://git.daplie.com/Daplie/letsencrypt-express)
| [letsencrypt-cluster](https://git.daplie.com/Daplie/letsencrypt-cluster)
2016-04-22 18:20:15 +00:00
| **letsencrypt-koa**
2017-01-14 20:49:29 +00:00
| [letsencrypt-hapi](https://git.daplie.com/Daplie/letsencrypt-hapi)
2016-04-22 18:20:15 +00:00
|
2016-04-18 17:05:06 +00:00
Free SSL and Automatic HTTPS for node.js with KOA and other middleware systems via Let's Encrypt
2016-04-18 17:07:30 +00:00
* 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.
## Install
```
2016-08-16 20:58:02 +00:00
npm install --save letsencrypt-express@2.x
2016-04-18 17:07:30 +00:00
```
2016-04-18 17:08:49 +00:00
*Pay no attention to the man behind the curtain.* (just ignore that the name of the module is letsencrypt-express)
2016-04-18 17:07:30 +00:00
### Part 1: Setup
```javascript
'use strict';
2016-08-16 20:58:02 +00:00
var le = require('letsencrypt-express').create({
server: 'staging' // in production use 'https://acme-v01.api.letsencrypt.org/directory'
, configDir: require('os').homedir() + '/letsencrypt/etc'
, approveDomains: function (opts, certs, cb) {
opts.domains = certs && certs.altnames || opts.domains;
opts.email = 'john.doe@example.com' // CHANGE ME
opts.agreeTos = true;
cb(null, { options: opts, certs: certs });
2016-04-18 17:07:30 +00:00
}
2016-08-16 20:58:02 +00:00
, debug: true
2016-04-18 17:07:30 +00:00
});
```
WARNING: If you don't do any checks and simply complete `approveRegistration` callback, 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. Alternatively, You can run registration *manually*:
```bash
npm install -g letsencrypt-cli
letsencrypt certonly --standalone \
2016-08-16 20:58:02 +00:00
--server 'https://acme-v01.api.letsencrypt.org/directory' \
2016-04-18 17:07:30 +00:00
--config-dir ~/letsencrypt/etc \
--agree-tos --domains example.com --email user@example.com
# Note: the '--webrootPath' option is also available if you don't want to shut down your webserver to get the cert.
```
### Part 2: Just add Koa
```javascript
var http = require('http');
2016-04-18 17:09:44 +00:00
var https = require('spdy');
2016-04-18 17:07:30 +00:00
var koa = require('koa');
var app = koa();
app.use(function *() {
this.body = 'Hello World';
});
2016-08-16 20:58:02 +00:00
var server = https.createServer(le.httpsOptions, le.middleware(app.callback()));
2016-04-18 17:07:30 +00:00
server.listen(443, function () {
console.log('Listening at https://localhost:' + this.address().port);
});
2016-08-16 20:58:02 +00:00
var http = require('http');
var redirectHttps = koa().use(require('koa-sslify')()).callback();
http.createServer(le.middleware(redirectHttps)).listen(80, function () {
console.log('handle ACME http-01 challenge and redirect to https');
2016-04-18 17:07:30 +00:00
});
```