|
|
@ -1,6 +1,6 @@ |
|
|
|
# Greenlock™ for Koa |
|
|
|
# Greenlock™ for rill |
|
|
|
|
|
|
|
An Automated HTTPS ACME client (Let's Encrypt v2) for Koa |
|
|
|
An Automated HTTPS ACME client (Let's Encrypt v2) for rill |
|
|
|
|
|
|
|
Greenlock™ for |
|
|
|
[Browsers](https://git.coolaj86.com/coolaj86/greenlock.html), |
|
|
@ -9,8 +9,8 @@ Greenlock™ for |
|
|
|
[Express.js](https://git.coolaj86.com/coolaj86/greenlock-express.js), |
|
|
|
[Node.js Cluster](https://git.coolaj86.com/coolaj86/greenlock-cluster.js), |
|
|
|
[hapi](https://git.coolaj86.com/coolaj86/greenlock-hapi.js), |
|
|
|
**Koa**, |
|
|
|
and [rill](https://git.coolaj86.com/coolaj86/greenlock-rill.js) |
|
|
|
[Koa](https://git.coolaj86.com/coolaj86/greenlock-koa.js), |
|
|
|
and **rill** |
|
|
|
| Sponsered by [ppl](https://ppl.family) |
|
|
|
|
|
|
|
Features |
|
|
@ -29,7 +29,7 @@ which works with any middleware system. |
|
|
|
## Install |
|
|
|
|
|
|
|
``` |
|
|
|
npm install --save greenlock-koa@2.x |
|
|
|
npm install --save greenlock-rill@2.x |
|
|
|
``` |
|
|
|
|
|
|
|
QuickStart |
|
|
@ -42,7 +42,7 @@ QuickStart |
|
|
|
// Greenlock Setup // |
|
|
|
////////////////////// |
|
|
|
|
|
|
|
var greenlock = require('greenlock-koa').create({ |
|
|
|
var greenlock = require('greenlock-rill').create({ |
|
|
|
version: 'draft-11' // Let's Encrypt v2 |
|
|
|
// You MUST change this to 'https://acme-v02.api.letsencrypt.org/directory' in production |
|
|
|
, server: 'https://acme-staging-v02.api.letsencrypt.org/directory' |
|
|
@ -61,21 +61,21 @@ var greenlock = require('greenlock-koa').create({ |
|
|
|
}); |
|
|
|
|
|
|
|
|
|
|
|
////////////////// |
|
|
|
// Just add Koa // |
|
|
|
////////////////// |
|
|
|
/////////////////// |
|
|
|
// Just add rill // |
|
|
|
/////////////////// |
|
|
|
|
|
|
|
var http = require('http'); |
|
|
|
var https = require('https'); |
|
|
|
var koa = require('koa'); |
|
|
|
var app = koa(); |
|
|
|
var Rill = require('rill'); |
|
|
|
var app = new Rill(); |
|
|
|
|
|
|
|
app.use(function *() { |
|
|
|
this.body = 'Hello World'; |
|
|
|
app.use(({ req, res }, next)=> { |
|
|
|
res.body = 'Hello, World!'; |
|
|
|
}); |
|
|
|
|
|
|
|
// https server |
|
|
|
var server = https.createServer(greenlock.tlsOptions, greenlock.middleware(app.callback())); |
|
|
|
var server = https.createServer(greenlock.tlsOptions, greenlock.middleware(app.handler())); |
|
|
|
|
|
|
|
server.listen(443, function () { |
|
|
|
console.log('Listening at https://localhost:' + this.address().port); |
|
|
@ -84,56 +84,31 @@ server.listen(443, function () { |
|
|
|
|
|
|
|
// http redirect to https |
|
|
|
var http = require('http'); |
|
|
|
var redirectHttps = koa().use(require('koa-sslify')()).callback(); |
|
|
|
var redirectHttps = require('redirect-https')(); |
|
|
|
http.createServer(greenlock.middleware(redirectHttps)).listen(80, function () { |
|
|
|
console.log('Listening on port 80 to handle ACME http-01 challenge and redirect to https'); |
|
|
|
}); |
|
|
|
``` |
|
|
|
|
|
|
|
Usage & Troubleshooting |
|
|
|
============================ |
|
|
|
|
|
|
|
See <https://git.coolaj86.com/coolaj86/greenlock-express.js> |
|
|
|
|
|
|
|
Handling a dynamic list of domains |
|
|
|
======================== |
|
|
|
|
|
|
|
If you handle multiple domains and you dynamically add new ones, |
|
|
|
you'll want to replace the static list of domains in `approveDomains` |
|
|
|
with a function like this: |
|
|
|
|
|
|
|
```js |
|
|
|
function approveDomains(opts, certs, cb) { |
|
|
|
// This is where you check your database and associated |
|
|
|
// email addresses with domains and agreements and such |
|
|
|
|
|
|
|
// 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 { |
|
|
|
// Do something to |
|
|
|
opts.email = 'john.doe@example.com'; |
|
|
|
opts.agreeTos = true; |
|
|
|
} |
|
|
|
|
|
|
|
opts.communityMember = true; |
|
|
|
|
|
|
|
// NOTE: you can also change other options such as `challengeType` and `challenge` |
|
|
|
// opts.challengeType = 'http-01'; |
|
|
|
// opts.challenge = require('le-challenge-fs').create({}); |
|
|
|
|
|
|
|
cb(null, { options: opts, certs: certs }); |
|
|
|
} |
|
|
|
``` |
|
|
|
In the oversimplified exapmple above we handle a static list of domains. |
|
|
|
If you add domains programmatically you'll want to use the `approveDomains` |
|
|
|
callback. |
|
|
|
|
|
|
|
**SECURITY**: Be careful with this. |
|
|
|
If you don't check that the domains being requested are the domains you |
|
|
|
allow an attacker can make you hit your rate limit for failed verification |
|
|
|
attempts. |
|
|
|
|
|
|
|
See the |
|
|
|
We have a |
|
|
|
[vhost example](https://git.coolaj86.com/coolaj86/greenlock-express.js/src/branch/master/examples/vhost.js) |
|
|
|
for an idea of how this is done. |
|
|
|
that allows any domain for which there is a folder on the filesystem in a specific location. |
|
|
|
|
|
|
|
|
|
|
|
More Usage & Troubleshooting |
|
|
|
============================ |
|
|
|
|
|
|
|
See <https://git.coolaj86.com/coolaj86/greenlock-express.js> |
|
|
|
See that example for an idea of how this is done. |
|
|
|