greenlock-rill.js/README.md

115 lines
3.3 KiB
Markdown
Raw Permalink Normal View History

2018-05-10 19:15:49 +00:00
# Greenlock™ for rill
2018-05-10 18:51:54 +00:00
2018-05-10 19:15:49 +00:00
An Automated HTTPS ACME client (Let's Encrypt v2) for rill
2018-05-10 18:51:54 +00:00
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),
2018-05-10 19:15:49 +00:00
[Koa](https://git.coolaj86.com/coolaj86/greenlock-koa.js),
and **rill**
2018-04-20 06:33:56 +00:00
| Sponsered by [ppl](https://ppl.family)
2016-04-22 18:20:15 +00:00
2018-05-10 18:51:54 +00:00
Features
========
2016-04-18 17:07:30 +00:00
2018-05-10 18:51:54 +00:00
* [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
2016-04-18 17:07:30 +00:00
2018-05-10 18:51:54 +00:00
This module is just an alias for greenlock-express.js,
which works with any middleware system.
2016-04-18 17:07:30 +00:00
## Install
```
2018-05-10 19:15:49 +00:00
npm install --save greenlock-rill@2.x
2016-04-18 17:07:30 +00:00
```
2018-05-10 18:51:54 +00:00
QuickStart
==========
2016-04-18 17:07:30 +00:00
```javascript
'use strict';
2018-05-10 18:51:54 +00:00
//////////////////////
// Greenlock Setup //
//////////////////////
2018-05-10 19:15:49 +00:00
var greenlock = require('greenlock-rill').create({
2018-05-10 18:51:54 +00:00
version: 'draft-11' // Let's Encrypt v2
2018-04-20 06:27:36 +00:00
// You MUST change this to 'https://acme-v02.api.letsencrypt.org/directory' in production
2018-05-10 18:51:54 +00:00
, server: 'https://acme-staging-v02.api.letsencrypt.org/directory'
2016-08-16 20:58:02 +00:00
2018-05-10 18:51:54 +00:00
, email: 'jon@example.com'
, agreeTos: true
, approveDomains: [ 'example.com' ]
2016-08-16 20:58:02 +00:00
2018-05-10 18:51:54 +00:00
// Join the community to get notified of important updates
// and help make greenlock better
, communityMember: true
2016-08-16 20:58:02 +00:00
2018-05-10 18:51:54 +00:00
, configDir: require('os').homedir() + '/acme/etc'
2016-04-18 17:07:30 +00:00
2018-05-10 18:51:54 +00:00
//, debug: true
});
2016-04-18 17:07:30 +00:00
2018-05-10 19:15:49 +00:00
///////////////////
// Just add rill //
///////////////////
2016-04-18 17:07:30 +00:00
var http = require('http');
2018-05-10 18:51:54 +00:00
var https = require('https');
2018-05-10 19:15:49 +00:00
var Rill = require('rill');
var app = new Rill();
2016-04-18 17:07:30 +00:00
2018-05-10 19:15:49 +00:00
app.use(({ req, res }, next)=> {
res.body = 'Hello, World!';
2016-04-18 17:07:30 +00:00
});
2018-05-10 18:51:54 +00:00
// https server
2018-05-10 19:15:49 +00:00
var server = https.createServer(greenlock.tlsOptions, greenlock.middleware(app.handler()));
2016-04-18 17:07:30 +00:00
server.listen(443, function () {
console.log('Listening at https://localhost:' + this.address().port);
});
2016-08-16 20:58:02 +00:00
2018-05-10 18:51:54 +00:00
// http redirect to https
2016-08-16 20:58:02 +00:00
var http = require('http');
2018-05-10 19:15:49 +00:00
var redirectHttps = require('redirect-https')();
2018-05-10 18:51:54 +00:00
http.createServer(greenlock.middleware(redirectHttps)).listen(80, function () {
console.log('Listening on port 80 to handle ACME http-01 challenge and redirect to https');
2016-04-18 17:07:30 +00:00
});
```
2018-05-10 18:51:54 +00:00
2018-05-10 19:15:49 +00:00
Usage & Troubleshooting
============================
See <https://git.coolaj86.com/coolaj86/greenlock-express.js>
2018-05-10 18:51:54 +00:00
Handling a dynamic list of domains
========================
2018-05-10 19:15:49 +00:00
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.
2018-05-10 18:51:54 +00:00
**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.
2018-05-10 19:15:49 +00:00
We have a
2018-05-10 18:51:54 +00:00
[vhost example](https://git.coolaj86.com/coolaj86/greenlock-express.js/src/branch/master/examples/vhost.js)
2018-05-10 19:15:49 +00:00
that allows any domain for which there is a folder on the filesystem in a specific location.
2018-05-10 18:51:54 +00:00
2018-05-10 19:15:49 +00:00
See that example for an idea of how this is done.