greenlock-koa.js/README.md

2.8 KiB

Join the chat at https://gitter.im/Daplie/letsencrypt-express

letsencrypt-koa

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 letsencrypt-express

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

Part 1: Setup

'use strict';

/* Note: using staging server url, remove .testing() for production
Using .testing() will overwrite the debug flag with true */ 
var LEX = require('letsencrypt-express').testing();

var lex = LEX.create({
  configDir: require('os').homedir() + '/letsencrypt/etc'
, approveRegistration: function (hostname, cb) { // leave `null` to disable automatic registration
    // Note: this is the place to check your database to get the user associated with this domain
    cb(null, {
      domains: [hostname]
    , email: 'CHANGE_ME' // user@example.com
    , agreeTos: 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:

npm install -g letsencrypt-cli

letsencrypt certonly --standalone \
  --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

var http = require('http');
var https = require('spdy');
var koa = require('koa');
var app = koa();
var redirectHttps = koa().use(require('koa-force-ssl').callback();

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

var server = https.createServer(lex.httpsOptions, LEX.createAcmeResponder(lex, app.callback()));
var redirectServer = http.createServer(LEX.createAcmeResponder(lex, redirectHttps)));

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

redirectServer.listen(80, function () {
  console.log('Redirecting insecure traffic from http://localhost:' + this.address().port + ' to https');
});