greenlock-express.js/README.md

316 lines
11 KiB
Markdown
Raw Normal View History

2020-01-11 20:15:39 +00:00
# [Greenlock Express v4](https://git.rootprojects.org/root/greenlock-express.js) is Let's Encrypt for Node
2019-09-04 06:15:02 +00:00
2020-01-11 00:51:25 +00:00
| Built by [Root](https://therootcompany.com) for [Hub](https://rootprojects.org/hub/) |
2018-04-20 06:43:02 +00:00
2020-01-11 00:51:25 +00:00
![Greenlock Logo](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo")
2018-05-10 06:53:45 +00:00
2020-01-11 00:51:25 +00:00
### Free SSL for Node Web Servers
2019-10-30 05:04:32 +00:00
2019-11-01 10:12:40 +00:00
Greenlock Express is a **Web Server** with **Fully Automated HTTPS** and renewals.
2020-01-11 00:51:25 +00:00
You define your app and let Greenlock handle issuing and renewing Free SSL Certificates.
2019-11-01 21:14:07 +00:00
2019-11-05 10:09:42 +00:00
```bash
npm init
2020-01-06 00:32:20 +00:00
npm install --save greenlock-express@v4
2019-11-05 10:09:42 +00:00
```
2020-01-11 00:51:25 +00:00
`server.js`:
2019-11-05 10:09:42 +00:00
```js
"use strict";
2020-01-09 11:29:18 +00:00
var app = require("./app.js");
2019-11-05 10:09:42 +00:00
require("greenlock-express")
2019-11-18 07:53:26 +00:00
.init({
packageRoot: __dirname,
2020-01-11 00:51:25 +00:00
configDir: "./greenlock.d",
2019-11-05 10:09:42 +00:00
2020-01-09 11:29:18 +00:00
// contact for security and critical bug notices
2020-01-11 00:51:25 +00:00
maintainerEmail: "jon@example.com",
2020-01-09 11:29:18 +00:00
2019-11-18 07:53:26 +00:00
// whether or not to run at cloudscale
cluster: false
2019-11-01 21:14:07 +00:00
})
2020-01-09 11:29:18 +00:00
// Serves on 80 and 443
// Get's SSL certificates magically!
.serve(app);
2019-11-05 10:09:42 +00:00
```
2020-01-11 00:51:25 +00:00
`./greenlock.d/config.json`:
2019-11-18 07:53:26 +00:00
```json
{ "sites": [{ "subject": "example.com", "altnames": ["example.com"] }] }
2019-11-05 10:09:42 +00:00
```
2019-10-28 09:43:53 +00:00
# Let's Encrypt for...
2019-11-01 21:14:07 +00:00
- IoT
- Enterprise On-Prem
- Local Development
- Home Servers
- Quitting Heroku
2018-04-23 19:55:03 +00:00
2019-10-28 09:43:53 +00:00
# Features
2018-04-23 20:02:50 +00:00
2019-11-01 21:14:07 +00:00
- [x] Let's Encrypt v2 (November 2019)
- [x] ACME Protocol (RFC 8555)
- [x] HTTP Validation (HTTP-01)
- [x] DNS Validation (DNS-01)
- [ ] ALPN Validation (TLS-ALPN-01)
- Need ALPN validation? [contact us](mailto:greenlock-support@therootcompany.com)
- [x] Automated HTTPS
- [x] Fully Automatic Renewals every 45 days
- [x] Free SSL
- [x] **Wildcard** SSL
- [x] **Localhost** certificates
- [x] HTTPS-enabled Secure **WebSockets** (`wss://`)
2020-01-11 00:51:25 +00:00
- [x] **Cloud-ready** with Node `cluster`.
2019-11-01 21:14:07 +00:00
- [x] Fully customizable
- [x] **Reasonable defaults**
- [x] Domain Management
- [x] Key and Certificate Management
- [x] ACME Challenge Plugins
2018-04-23 20:02:50 +00:00
2020-01-11 00:51:25 +00:00
# Compatibility
2018-04-23 20:02:50 +00:00
2020-01-11 00:51:25 +00:00
Works with _any_ node http app, including
2018-04-23 20:02:50 +00:00
2020-01-11 00:51:25 +00:00
- [x] Express
- [x] Koa
- [x] hapi
- [x] rill
- [x] http2
- [x] cluster
- [x] etc...
2020-01-11 20:16:48 +00:00
# v4 QuickStart
2018-04-20 07:14:39 +00:00
2020-01-11 20:16:48 +00:00
Serving sites with Free SSL is as easy as 1, 2, 3... 4
2018-04-20 08:59:33 +00:00
2020-01-11 20:15:39 +00:00
### Overview
2020-01-11 00:51:25 +00:00
1. Create a Project with Greenlock Express
- `server.js`
- `app.js`
2. Setup the config file (or database)
- `greenlock.d/config.json`
3. Add Domains
- `npx greenlock add --subject example.com --altnames example.com`
4. Hello, World!
- `npm start -- --staging`
2018-04-20 08:59:33 +00:00
2020-01-11 20:15:39 +00:00
## 1. Create your Project
2019-10-28 09:43:53 +00:00
```bash
npm init
2020-01-11 00:51:25 +00:00
npm install --save greenlock-express@v4
2018-04-20 08:59:33 +00:00
```
2020-01-11 00:51:25 +00:00
You can use **local file storage** or a **database**. The default is to use file storage.
2016-08-12 07:02:33 +00:00
2020-01-11 20:15:39 +00:00
## 2. Initialize and Config (Dir or DB)
2020-01-11 00:51:25 +00:00
```bash
2020-01-11 01:03:59 +00:00
# Note: you can use the CLI to create `server.js` and `greenlock.d/config.json`
2020-01-11 00:51:25 +00:00
npx greenlock init --config-dir ./greenlock.d --maintainer-email 'jon@example.com'
2016-08-12 07:02:33 +00:00
```
2020-01-11 01:03:59 +00:00
`server.js`:
2018-05-19 23:54:08 +00:00
2019-10-28 09:52:38 +00:00
```js
2019-11-05 11:01:58 +00:00
"use strict";
2020-01-06 00:32:20 +00:00
var app = require("./app.js");
2019-10-28 09:43:53 +00:00
require("greenlock-express")
2020-01-06 00:32:20 +00:00
.init({
packageRoot: __dirname,
2020-01-11 00:51:25 +00:00
// contact for security and critical bug notices
2020-01-06 00:32:20 +00:00
configDir: "./greenlock.d",
// whether or not to run at cloudscale
cluster: false
})
2020-01-11 00:51:25 +00:00
// Serves on 80 and 443
// Get's SSL certificates magically!
2020-01-06 00:32:20 +00:00
.serve(app);
2018-05-19 23:54:08 +00:00
```
2016-08-12 07:02:33 +00:00
2020-01-11 01:03:59 +00:00
`app.js`:
2019-11-05 11:01:58 +00:00
```js
2020-01-11 00:51:25 +00:00
"use strict";
2019-11-05 11:01:58 +00:00
2020-01-11 00:51:25 +00:00
// Here's a vanilla HTTP app to start,
// but feel free to replace it with Express, Koa, etc
var app = function(req, res) {
res.end("Hello, Encrypted World!");
};
2019-11-05 11:01:58 +00:00
2020-01-11 00:51:25 +00:00
module.exports = app;
2019-11-05 11:01:58 +00:00
```
2020-01-11 20:15:39 +00:00
### 3. Add Sites
2019-11-05 11:01:58 +00:00
```bash
2020-01-11 01:03:59 +00:00
# Note: you can use the CLI to edit the config file
2020-01-11 00:51:25 +00:00
npx greenlock add --subject example.com --altnames example.com
2019-11-05 11:01:58 +00:00
```
2019-11-01 10:12:40 +00:00
2020-01-11 01:03:59 +00:00
`greenlock.d/config.json`:
2020-01-11 00:51:25 +00:00
<!-- TODO update manager to write array rather than object -->
2019-11-01 10:12:40 +00:00
```json
2020-01-11 00:51:25 +00:00
{ "sites": [{ "subject": "example.com", "altnames": ["example.com"] }] }
2019-11-01 10:12:40 +00:00
```
2020-01-11 20:15:39 +00:00
### 4. Hello, Encrypted World!
2019-10-28 09:43:53 +00:00
```bash
2020-01-11 01:03:59 +00:00
# Note: you can use npm start to run server.js with the --staging flag set
2020-01-11 00:51:25 +00:00
npm start -- --staging
```
2018-04-20 07:09:34 +00:00
2020-01-11 00:51:25 +00:00
```txt
> my-project@1.0.0 start /srv/www/my-project
> node server.js
2016-08-17 15:11:10 +00:00
2020-01-11 00:51:25 +00:00
Listening on 0.0.0.0:80 for ACME challenges and HTTPS redirects
Listening on 0.0.0.0:443 for secure traffic
2019-11-05 11:01:58 +00:00
```
2020-01-11 00:51:25 +00:00
## Walkthrough
2016-08-17 15:25:07 +00:00
2020-01-11 20:15:39 +00:00
For a more detail read the full
[WALKTHROUGH](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/WALKTHROUGH.md).
2020-01-11 00:51:25 +00:00
# Examples
2019-11-01 21:14:07 +00:00
- [greenlock-express.js/examples/](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples)
- [Express](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/express/)
- [Node's **http2**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http2/)
- [Node's https](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/https/)
- [**WebSockets**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/websockets/)
2019-11-05 10:09:42 +00:00
- [Socket.IO](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/socket.io/)
2019-11-01 21:14:07 +00:00
- [Cluster](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/cluster/)
- [**Wildcards**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcards/) (coming soon)
- [**Localhost**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/) (coming soon)
- [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/) (coming soon)
- [HTTP Proxy](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http-proxy/)
2020-01-11 00:51:25 +00:00
# Using a Database, S3, etc
If you have a small site, the default file storage will work well for you.
If you have many sites with many users, you'll probably want to store config in a database of some sort.
See the section on **Custom** callbacks and plugins below.
# Advanced Configuration
All of the advanced configuration is done by replacing the default behavior with callbacks.
You can whip up your own, or you can use something that's published to npm.
See the section on **Custom** callbacks and plugins below.
# Easy to Customize
<!-- greenlock-manager-test => greenlock-manager-custom -->
<!--
- [greenlock.js/examples/](https://git.rootprojects.org/root/greenlock.js/src/branch/master/examples)
-->
2019-11-01 21:14:07 +00:00
- [Custom Domain Management](https://git.rootprojects.org/root/greenlock-manager-test.js)
2019-11-05 11:01:58 +00:00
- `npx greenlock init --manager ./path-or-npm-name.js --manager-FOO 'set option FOO'`
2019-11-01 21:14:07 +00:00
- [Custom Key & Cert Storage](https://git.rootprojects.org/root/greenlock-store-test.js)
2019-11-05 11:01:58 +00:00
- `npx greenlock defaults --store greenlock-store-fs --store-base-path ./greenlock.d`
2019-11-01 21:14:07 +00:00
- [Custom ACME HTTP-01 Challenges](https://git.rootprojects.org/root/acme-http-01-test.js)
2019-11-05 11:01:58 +00:00
- `npx greenlock defaults --challenge-http-01 ./you-http-01.js`
- `npx greenlock update --subject example.com --challenge-http-01 acme-http-01-standalone`
2019-11-01 21:14:07 +00:00
- [Custom ACME DNS-01 Challenges](https://git.rootprojects.org/root/acme-dns-01-test.js)
2019-11-05 11:01:58 +00:00
- `npx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx`
2019-11-05 11:20:17 +00:00
- `npx greenlock update --subject example.com --challenge-dns-01 ./your-dns-01.js`
# Ready-made Integrations
Greenlock Express integrates between Let's Encrypt's ACME Challenges and many popular services.
| Type | Service | Plugin |
| ----------- | ----------------------------------------------------------------------------------- | ------------------------ |
| dns-01 | CloudFlare | acme-dns-01-cloudflare |
| dns-01 | [Digital Ocean](https://git.rootprojects.org/root/acme-dns-01-digitalocean.js) | acme-dns-01-digitalocean |
| dns-01 | [DNSimple](https://git.rootprojects.org/root/acme-dns-01-dnsimple.js) | acme-dns-01-dnsimple |
| dns-01 | [DuckDNS](https://git.rootprojects.org/root/acme-dns-01-duckdns.js) | acme-dns-01-duckdns |
| http-01 | File System / [Web Root](https://git.rootprojects.org/root/acme-http-01-webroot.js) | acme-http-01-webroot |
| dns-01 | [GoDaddy](https://git.rootprojects.org/root/acme-dns-01-godaddy.js) | acme-dns-01-godaddy |
| dns-01 | [Gandi](https://git.rootprojects.org/root/acme-dns-01-gandi.js) | acme-dns-01-gandi |
| dns-01 | [NameCheap](https://git.rootprojects.org/root/acme-dns-01-namecheap.js) | acme-dns-01-namecheap |
| dns-01 | [Name&#46;com](https://git.rootprojects.org/root/acme-dns-01-namedotcom.js) | acme-dns-01-namedotcom |
| dns-01 | Route53 (AWS) | acme-dns-01-route53 |
| http-01 | S3 (AWS, Digital Ocean, Scaleway) | acme-http-01-s3 |
| dns-01 | [Vultr](https://git.rootprojects.org/root/acme-dns-01-vultr.js) | acme-dns-01-vultr |
| dns-01 | [Build your own](https://git.rootprojects.org/root/acme-dns-01-test.js) | acme-dns-01-test |
| http-01 | [Build your own](https://git.rootprojects.org/root/acme-http-01-test.js) | acme-http-01-test |
| tls-alpn-01 | [Contact us](mailto:support@therootcompany.com) | - |
2019-11-05 11:01:58 +00:00
Example Usage:
```bash
npx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx
npx greenlock defaults --challenge-http-01 acme-http-01-s3 --challenge-http-01-bucket my-bucket
```
Search `acme-http-01-` or `acme-dns-01-` on npm to find more.
2019-10-28 09:43:53 +00:00
# Full Documentation
2016-08-12 07:56:19 +00:00
2019-10-28 09:43:53 +00:00
<!--
- Greenlock CLI
- Greenlock JavaScript API
-->
2016-08-16 01:15:16 +00:00
2019-10-28 09:43:53 +00:00
Most of the documentation is done by use-case examples, as shown up at the top of the README.
2016-08-15 23:12:39 +00:00
2019-10-28 09:43:53 +00:00
We're working on more comprehensive documentation for this newly released version.
**Please open an issue** with questions in the meantime.
2016-08-15 23:12:39 +00:00
2019-10-28 09:43:53 +00:00
# Commercial Support
2016-08-12 07:56:19 +00:00
2019-10-28 09:43:53 +00:00
Do you need...
2016-08-12 07:56:19 +00:00
2019-11-01 21:14:07 +00:00
- training?
- specific features?
- different integrations?
- bugfixes, on _your_ timeline?
- custom code, built by experts?
- commercial support and licensing?
2018-05-03 00:55:35 +00:00
2019-10-28 09:43:53 +00:00
You're welcome to [contact us](mailto:aj@therootcompany.com) in regards to IoT, On-Prem,
Enterprise, and Internal installations, integrations, and deployments.
2018-05-03 00:55:35 +00:00
2019-10-28 09:43:53 +00:00
We have both commercial support and commercial licensing available.
2018-05-31 21:14:23 +00:00
2019-10-28 09:43:53 +00:00
We also offer consulting for all-things-ACME and Let's Encrypt.
2019-05-16 04:19:58 +00:00
# Legal &amp; Rules of the Road
2019-05-16 04:19:58 +00:00
Greenlock&trade; is a [trademark](https://rootprojects.org/legal/#trademark) of AJ ONeal
2019-05-16 04:19:58 +00:00
The rule of thumb is "attribute, but don't confuse". For example:
2019-05-16 04:39:35 +00:00
> Built with [Greenlock Express](https://git.rootprojects.org/root/greenlock.js) (a [Root](https://rootprojects.org) project).
2019-05-16 04:19:58 +00:00
Please [contact us](mailto:aj@therootcompany.com) if you have any questions in regards to our trademark,
attribution, and/or visible source policies. We want to build great software and a great community.
[Greenlock&trade;](https://git.rootprojects.org/root/greenlock.js) |
MPL-2.0 |
[Terms of Use](https://therootcompany.com/legal/#terms) |
[Privacy Policy](https://therootcompany.com/legal/#privacy)