coolaj86
/
greenlock-rill.js
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

update Koa docs

This commit is contained in:
AJ ONeal 2018-05-10 12:51:54 -06:00
parent 844dc7abd4
commit e689306a77
3 changed files with 113 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
README.md
View File

@ -1,75 +1,72 @@
# greenlock-koa
(previously letsencrypt-koa)
# Greenlock™ for Koa
An Automated HTTPS ACME client (Let's Encrypt v2) for Koa
Greenlock™ for
[Browsers](https://git.coolaj86.com/coolaj86/greenlock.html),
[Node.js](https://git.coolaj86.com/coolaj86/greenlock.js),
[Commandline](https://git.coolaj86.com/coolaj86/greenlock-cli.js),
[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)
| 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
Features
========
* 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
* [x] Automatic Registration via SNI (`httpsOptions.SNICallback`)
* [x] Secure domain approval callback
* [x] Automatic renewal between 10 and 14 days before expiration
* [x] Virtual Hosting (vhost) with Multiple Domains & SAN
* [x] and [more](https://git.coolaj86.com/coolaj86/greenlock-express.js)
* [x] plugins for AWS, redis, and more
All you have to do is start the webserver and then visit it at it's domain name.
This module is just an alias for greenlock-express.js,
which works with any middleware system.
## Install
```
npm install --save greenlock-express@2.x
npm install --save greenlock-koa@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
QuickStart
==========
```javascript
'use strict';
var le = require('greenlock-express').create({
//////////////////////
// Greenlock Setup //
//////////////////////
var greenlock = require('greenlock-koa').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'
, version: 'draft-11' // Let's Encrypt v2
, server: 'https://acme-staging-v02.api.letsencrypt.org/directory'
, email: 'jon@example.com'
, agreeTos: true
, approveDomains: [ 'example.com' ]
// Join the community to get notified of important updates
// and help make greenlock better
, communityMember: true
, 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
//, 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
//////////////////
// Just add Koa //
//////////////////
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 https = require('https');
var koa = require('koa');
var app = koa();
@ -77,16 +74,66 @@ app.use(function *() {
this.body = 'Hello World';
});
var server = https.createServer(le.httpsOptions, le.middleware(app.callback()));
// https server
var server = https.createServer(greenlock.tlsOptions, greenlock.middleware(app.callback()));
server.listen(443, function () {
console.log('Listening at https://localhost:' + this.address().port);
});
// http redirect to https
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');
http.createServer(greenlock.middleware(redirectHttps)).listen(80, function () {
console.log('Listening on port 80 to handle ACME http-01 challenge and redirect to https');
});
```
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 });
}
```
**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
[vhost example](https://git.coolaj86.com/coolaj86/greenlock-express.js/src/branch/master/examples/vhost.js)
for an idea of how this is done.
More Usage & Troubleshooting
============================
See <https://git.coolaj86.com/coolaj86/greenlock-express.js>

8
index.js Normal file
View File

@ -0,0 +1,8 @@
'use strict';
module.exports = require('greenlock-express');
module.exports._greenlockExpressCreate = module.exports.create;
module.create = function (opts) {
opts._communityPackage = opts._communityPackage || 'greenlock-koa';
return module.exports._greenlockExpressCreate(opts);
};

12
package.json
View File

@ -1,14 +1,14 @@
{
"name": "greenlock-koa",
"version": "2.0.4",
"description": "Free SSL and Automatic HTTPS for node.js with KOA and other middleware systems via ACME (Let's Encrypt)",
"version": "2.1.2",
"description": "An Automated HTTPS ACME client (Let's Encrypt v2) for Koa",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"repository": {
"type": "git",
"url": "git+https://git.daplie.com/Daplie/greenlock-koa.git"
"url": "git+https://git.coolaj86.com/coolaj86/greenlock-koa.js.git"
},
"keywords": [
"acme",
@ -16,17 +16,17 @@
"cluster",
"free",
"greenlock",
"freessl",
"free ssl",
"https",
"koa",
"le",
"letsencrypt",
"multi-core",
"node",
"node.js",
"scale",
"ssl",
"tls"
],
"author": "AJ ONeal <aj@daplie.com> (https://daplie.com/)",
"author": "AJ ONeal <coolaj86@gmail.com> (https://coolaj86.com/)",
"license": "(MIT OR Apache-2.0)"
}