update Koa docs
This commit is contained in:
AJ ONeal
parent
844dc7abd4
commit
e689306a77
151
README.md
151
README.md
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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
12
package.json
|
|
@ -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)"
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue