greenlock-express.js/README.md

294 lines
8.7 KiB
Markdown
Raw Normal View History

2019-10-28 09:43:53 +00:00
# [Greenlock Express](https://git.rootprojects.org/root/greenlock-express.js) is Let's Encrypt for Node
2019-09-04 06:15:02 +00:00
2019-05-16 04:19:58 +00:00
![Greenlock Logo](https://git.rootprojects.org/root/greenlock.js/raw/branch/master/logo/greenlock-1063x250.png "Greenlock Logo")
2018-05-12 07:46:56 +00:00
2019-10-28 09:43:53 +00:00
| Built by [Root](https://therootcompany.com) for [Hub](https://rootprojects.org/hub/)
2018-04-20 06:43:02 +00:00
2019-10-28 09:43:53 +00:00
Free SSL, Automated HTTPS / HTTP2, served with Node via Express, Koa, hapi, etc.
2018-05-10 06:53:45 +00:00
2019-10-30 05:04:32 +00:00
### Let's Encrypt for Node, Express, etc
2019-10-28 09:43:53 +00:00
```js
require("greenlock-express")
2019-10-30 05:04:32 +00:00
.init(function getConfig() {
return { package: require("./package.json") };
})
.serve(httpsWorker);
2016-08-12 07:02:33 +00:00
2019-10-30 05:04:32 +00:00
function httpsWorker(server) {
// Works with any Node app (Express, etc)
var app = require("./my-express-app.js");
2019-10-28 09:43:53 +00:00
2019-10-30 05:04:32 +00:00
// See, all normal stuff here
app.get("/hello", function(req, res) {
2019-10-28 09:43:53 +00:00
res.end("Hello, Encrypted World!");
});
2019-10-30 05:04:32 +00:00
// Serves on 80 and 443
// Get's SSL certificates magically!
server.serveApp(app);
}
```
Manage via API or the config file:
```json
{
"subscriberEmail": "letsencrypt-test@therootcompany.com",
"agreeToTerms": true,
"sites": {
"example.com": {
"subject": "example.com",
"altnames": ["example.com", "www.example.com"]
}
}
2019-10-28 09:43:53 +00:00
}
2016-08-12 07:02:33 +00:00
```
2019-10-28 09:43:53 +00:00
# Let's Encrypt for...
2019-10-28 09:43:53 +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-10-28 09:43:53 +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://`)
- [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
2019-10-28 09:43:53 +00:00
# Plenty of Examples
2018-05-24 04:39:24 +00:00
2019-10-28 09:43:53 +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.js)
- [Node's **http2**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/http2.js)
- [Node's https](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/https.js)
- [**WebSockets**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/websockets.js)
- [Socket.IO](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/socket-io.js)
- [Cluster](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/socket-io.js)
- [**Wildcards**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcards/README.md)
- [**Localhost**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/README.md)
- [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/README.md)
2018-08-18 09:45:11 +00:00
2019-10-28 09:43:53 +00:00
# Easy to Customize
2018-08-18 09:45:11 +00:00
2019-10-28 09:43:53 +00:00
<!-- greenlock-manager-test => greenlock-manager-custom -->
2018-08-18 09:45:11 +00:00
2019-10-28 09:43:53 +00:00
- [greenlock.js/examples/](https://git.rootprojects.org/root/greenlock.js/src/branch/master/examples)
- [Custom Domain Management](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/custom-manager/README.md)
- [Custom Key & Cert Storage](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/custom-store/README.md)
- [Custom ACME Challenges](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/custom-acme-challenges/README.md)
2018-08-18 09:45:11 +00:00
2019-10-28 09:43:53 +00:00
# QuickStart Guide
2018-04-23 20:02:50 +00:00
2019-10-28 09:43:53 +00:00
Easy as 1, 2, 3... 4
2018-04-23 20:02:50 +00:00
2019-10-28 09:43:53 +00:00
## 1. Create a node project
2018-04-20 07:14:39 +00:00
2019-10-28 09:43:53 +00:00
Create an empty node project.
2018-04-20 08:59:33 +00:00
2019-10-28 09:43:53 +00:00
Be sure to fill out the package name, version, and an author email.
2018-04-20 08:59:33 +00:00
2019-10-28 09:43:53 +00:00
```bash
mkdir ~/my-project
pushd ~/my-project
npm init
2018-04-20 08:59:33 +00:00
```
2019-10-28 09:43:53 +00:00
## 2. Create an http app (i.e. express)
2016-08-12 07:02:33 +00:00
2019-10-28 09:43:53 +00:00
This example is shown with Express, but any node app will doGreenlock
works with everything.
(or any node-style http app)
`my-express-app.js`:
2016-08-12 07:02:33 +00:00
2019-10-28 09:43:53 +00:00
```js
2019-06-03 09:47:07 +00:00
"use strict";
2019-10-28 09:43:53 +00:00
// A plain, node-style app
2016-08-16 01:15:16 +00:00
2019-10-28 09:43:53 +00:00
function myPlainNodeHttpApp(req, res) {
res.end("Hello, Encrypted World!");
}
2019-06-03 09:47:07 +00:00
2019-10-28 09:43:53 +00:00
// Wrap that plain app in express,
// because that's what you're used to
2016-08-12 07:02:33 +00:00
2019-06-03 09:47:07 +00:00
var express = require("express");
var app = express();
2019-10-28 09:43:53 +00:00
app.get("/", myPlainNodeHttpApp);
2018-05-10 06:53:45 +00:00
2019-10-28 09:43:53 +00:00
// export the app normally
// do not .listen()
2018-05-26 01:28:11 +00:00
module.exports = app;
2016-08-12 07:02:33 +00:00
```
2019-10-28 09:43:53 +00:00
## 3. Serve with Greenlock Express
2018-04-20 07:23:22 +00:00
2019-10-28 09:43:53 +00:00
Greenlock Express is designed with these goals in mind:
2016-08-12 07:02:33 +00:00
2019-10-28 09:43:53 +00:00
- Simplicity and ease-of-use
- Performance and scalability
- Configurability and control
2018-05-19 23:54:08 +00:00
2019-10-28 09:43:53 +00:00
You can start with **near-zero configuration** and
slowly add options for greater performance and customization
later, if you need them.
2016-08-12 07:02:33 +00:00
2019-10-28 09:43:53 +00:00
`server.js`:
2018-05-19 23:54:08 +00:00
2019-10-28 09:52:38 +00:00
```js
2019-10-28 09:43:53 +00:00
require("greenlock-express")
.init(getConfig)
.serve(worker);
function getConfig() {
return {
// uses name and version as part of the ACME client user-agent
2019-10-28 09:52:38 +00:00
// uses author as the contact for support notices
2019-10-28 09:43:53 +00:00
package: require("./package.json")
};
}
2018-05-19 23:54:08 +00:00
2019-10-28 09:43:53 +00:00
function worker(server) {
// Works with any Node app (Express, etc)
2019-10-28 09:52:38 +00:00
var app = require("my-express-app.js");
2019-10-28 09:43:53 +00:00
server.serveApp(app);
}
2018-05-19 23:54:08 +00:00
```
2016-08-12 07:02:33 +00:00
2019-10-28 09:43:53 +00:00
And start your server:
2018-04-20 08:59:33 +00:00
2019-10-28 09:43:53 +00:00
```bash
# Allow non-root node to use ports 80 (HTTP) and 443 (HTTPS)
sudo setcap 'cap_net_bind_service=+ep' $(which node)
2018-04-20 08:59:33 +00:00
```
2019-10-28 09:43:53 +00:00
```bash
# `npm start` will call `node ./server.js` by default
npm start
2018-04-20 08:59:33 +00:00
```
2019-10-28 09:43:53 +00:00
```txt
Greenlock v3.0.0
Greenlock Manager Config File: ~/.config/greenlock/manager.json
Greenlock Storage Directory: ~/.config/greenlock/
2019-06-03 09:47:07 +00:00
2019-10-28 09:43:53 +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-06-03 09:47:07 +00:00
2019-10-28 09:43:53 +00:00
## 4. Manage domains
2019-10-28 09:43:53 +00:00
Management can be done via the **CLI** or the JavaScript [**API**](https://git.rootprojects.org/root/greenlock.js/).
Since this is the QuickStart, we'll demo the **CLI**:
2016-08-12 07:02:33 +00:00
2019-10-28 09:43:53 +00:00
You need to create a Let's Encrypt _subscriber account_, which can be done globally, or per-site.
All individuals, and most businesses, should set this globally:
2019-10-28 09:43:53 +00:00
```bash
# Set a global subscriber account
npx greenlock config --subscriber-email 'mycompany@example.com' --agree-to-terms true
```
2018-04-20 07:09:34 +00:00
2019-10-28 09:43:53 +00:00
<!-- todo print where the key was saved -->
2019-10-28 09:43:53 +00:00
A Let's Encrypt SSL certificate has a "Subject" (Primary Domain) and up to 100 "Alternative Names"
(of which the first _must_ be the subject).
2016-08-17 15:11:10 +00:00
2019-10-28 09:43:53 +00:00
```bash
# Add a certificate with specific domains
npx greenlock add --subject example.com --altnames example.com,www.example.com
```
2016-08-17 15:11:10 +00:00
2019-10-28 09:43:53 +00:00
<!-- todo print where the cert was saved -->
2018-05-12 02:29:21 +00:00
2019-10-28 09:43:53 +00:00
This will update the config file (assuming the default fs-based management plugin):
2016-08-17 15:11:10 +00:00
2019-10-28 09:43:53 +00:00
`~/.config/greenlock/manager.json`:
2019-10-28 09:43:53 +00:00
```json
{
"subscriberEmail": "letsencrypt-test@therootcompany.com",
"agreeToTerms": true,
"sites": {
"example.com": {
"subject": "example.com",
"altnames": ["example.com", "www.example.com"]
}
}
2016-08-17 15:11:10 +00:00
}
```
2019-10-28 09:43:53 +00:00
Note: **Localhost**, **Wildcard**, and Certificates for Private Networks require
[**DNS validation**](https://git.rootprojects.org/root/greenlock-exp).
2016-08-17 15:25:07 +00:00
2019-10-28 09:43:53 +00:00
- DNS Validation
- [**Wildcards**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/wildcards/README.md)
- [**Localhost**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/localhost/README.md)
- [**CI/CD**](https://git.rootprojects.org/root/greenlock-express.js/src/branch/master/examples/ci-cd/README.md)
2016-08-17 15:25:07 +00:00
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-10-28 09:43:53 +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)