greenlock-koa.js/README.md

# greenlock-koa
(previously letsencrypt-koa)

| Sponsered by [ppl](https://ppl.family)
| [greenlock (lib)](https://git.coolaj86.com/coolaj86/greenlock.js)
| [greenlock-cli](https://git.coolaj86.com/coolaj86/greenlock-cli.js) 
| [greenlock-express](https://git.coolaj86.com/coolaj86/greenlock-express.js)
| [greenlock-cluster](https://git.coolaj86.com/coolaj86/greenlock-cluster.js)
| **greenlock-koa**
| [greenlock-hapi](https://git.coolaj86.com/coolaj86/greenlock-hapi.js)
|

Free SSL and Automatic HTTPS for node.js with KOA and other middleware systems via Let's Encrypt

* 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

```
npm install --save greenlock-express@2.x
```

*Pay no attention to the man behind the curtain.* (just ignore that the name of the module is greenlock-express)

### Part 1: Setup

```javascript
'use strict';

var le = require('greenlock-express').create({
  // You MUST change this to 'https://acme-v02.api.letsencrypt.org/directory' in production
  server: 'https://acme-staging-v02.api.letsencrypt.org/directory'
, version: 'draft-11' // Let's Encrypt v2
  
, configDir: require('os').homedir() + '/acme/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 });
  }

 , debug: true
});
```

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 greenlock-cli

greenlock certonly --standalone \
  --server 'https://acme-v02.api.letsencrypt.org/directory' \
  --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');
var https = require('spdy');
var koa = require('koa');
var app = koa();

app.use(function *() {
  this.body = 'Hello World';
});

var server = https.createServer(le.httpsOptions, le.middleware(app.callback()));

server.listen(443, function () {
 console.log('Listening at https://localhost:' + this.address().port);
});


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');
});
```