New Documentation & v2/v3 Migration Guide

Greenlock v3 just came out of private beta today (Nov 1st, 2019).

The code is complete and we're working on great documentation.

Many examples and full API documentation are still coming.

Greenlock Express is Let's Encrypt for Node

| Built by Root for Hub

Free SSL, Automated HTTPS / HTTP2, served with Node via Express, Koa, hapi, etc.

Let's Encrypt for Node, Express, etc

Greenlock Express is a Web Server with Fully Automated HTTPS and renewals.

"use strict";

function httpsWorker(glx) {
	// Serves on 80 and 443
	// Get's SSL certificates magically!

	glx.serveApp(function(req, res) {
		res.end("Hello, Encrypted World!");
	});
}

var pkg = require("./package.json");
require("greenlock-express")
	.init(function getConfig() {
		// Greenlock Config

		return {
			package: { name: pkg.name, version: pkg.version },
			maintainerEmail: pkg.author,
			cluster: false
		};
	})
	.serve(httpsWorker);

Manage via API or the config file:

~/.config/greenlock/manage.json: (default filesystem config)

{
	"subscriberEmail": "letsencrypt-test@therootcompany.com",
	"agreeToTerms": true,
	"sites": {
		"example.com": {
			"subject": "example.com",
			"altnames": ["example.com", "www.example.com"]
		}
	}
}

Let's Encrypt for...

• IoT
• Enterprise On-Prem
• Local Development
• Home Servers
• Quitting Heroku

Features

• Let's Encrypt v2 (November 2019)
  • ACME Protocol (RFC 8555)
  • HTTP Validation (HTTP-01)
  • DNS Validation (DNS-01)
  • ALPN Validation (TLS-ALPN-01)
    • Need ALPN validation? contact us
• Automated HTTPS
  • Fully Automatic Renewals every 45 days
  • Free SSL
  • Wildcard SSL
  • Localhost certificates
  • HTTPS-enabled Secure WebSockets (wss://)
• Fully customizable
  • Reasonable defaults
  • Domain Management
  • Key and Certificate Management
  • ACME Challenge Plugins

QuickStart Guide

Easy as 1, 2, 3... 4

1. Create a node project

1. Create a node project

Create an empty node project.

Be sure to fill out the package name, version, and an author email.

mkdir ~/my-project
pushd ~/my-project
npm init

2. Create an http app (i.e. express)

2. Create an http app (i.e. express)

This example is shown with Express, but any node app will do. Greenlock works with everything. (or any node-style http app)

my-express-app.js:

"use strict";

// A plain, node-style app

function myPlainNodeHttpApp(req, res) {
	res.end("Hello, Encrypted World!");
}

// Wrap that plain app in express,
// because that's what you're used to

var express = require("express");
var app = express();
app.get("/", myPlainNodeHttpApp);

// export the app normally
// do not .listen()

module.exports = app;

3. Serve with Greenlock Express

3. Serve with Greenlock Express

Greenlock Express is designed with these goals in mind:

• Simplicity and ease-of-use
• Performance and scalability
• Configurability and control

You can start with near-zero configuration and slowly add options for greater performance and customization later, if you need them.

server.js:

require("greenlock-express")
	.init(getConfig)
	.serve(worker);

function getConfig() {
	return {
		// uses name and version as part of the ACME client user-agent
		// uses author as the contact for support notices
		package: require("./package.json")
	};
}

function worker(server) {
	// Works with any Node app (Express, etc)
	var app = require("my-express-app.js");
	server.serveApp(app);
}

And start your server:

# Allow non-root node to use ports 80 (HTTP) and 443 (HTTPS)
sudo setcap 'cap_net_bind_service=+ep' $(which node)

# `npm start` will call `node ./server.js` by default
npm start

Greenlock v3.0.0
Greenlock Manager Config File: ~/.config/greenlock/manager.json
Greenlock Storage Directory: ~/.config/greenlock/

Listening on 0.0.0.0:80 for ACME challenges and HTTPS redirects
Listening on 0.0.0.0:443 for secure traffic

4. Manage SSL Certificates and Domains

4. Manage domains

The management API is built to work with Databases, S3, etc.

HOWEVER, by default it starts with a simple config file.

~/.config/greenlock/manager.json:

{
	"subscriberEmail": "letsencrypt-test@therootcompany.com",
	"agreeToTerms": true,
	"sites": {
		"example.com": {
			"subject": "example.com",
			"altnames": ["example.com", "www.example.com"]
		}
	}
}

COMING SOON

Management can be done via the CLI or the JavaScript API. Since this is the QuickStart, we'll demo the CLI:

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:

# COMING SOON
# (this command should be here by Nov 5th)
# (edit the config by hand for now)
#
# Set a global subscriber account
npx greenlock config --subscriber-email 'mycompany@example.com' --agree-to-terms true

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).

# COMING SOON
# (this command should be here by Nov 5th)
# (edit the config by hand for now)
#
# Add a certificate with specific domains
npx greenlock add --subject example.com --altnames example.com,www.example.com

Note: Localhost, Wildcard, and Certificates for Private Networks require DNS validation.

• DNS Validation
  • Wildcards (coming soon)
  • Localhost (coming soon)
  • CI/CD (coming soon)

Plenty of Examples

These are in-progress Check back tomorrow (Nov 2nd, 2019).

• greenlock-express.js/examples/
  • Express
  • Node's http2
  • Node's https
  • WebSockets
  • Socket.IO
  • Cluster
  • Wildcards (coming soon)
  • Localhost (coming soon)
  • CI/CD (coming soon)
  • HTTP Proxy

Easy to Customize

• Custom Domain Management
• Custom Key & Cert Storage
• Custom ACME HTTP-01 Challenges
• Custom ACME DNS-01 Challenges

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	acme-dns-01-digitalocean
dns-01	DNSimple	acme-dns-01-dnsimple
dns-01	DuckDNS	acme-dns-01-duckdns
http-01	File System / Web Root	acme-http-01-webroot
dns-01	GoDaddy	acme-dns-01-godaddy
dns-01	Gandi	acme-dns-01-gandi
dns-01	NameCheap	acme-dns-01-namecheap
dns-01	Name.com	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	acme-dns-01-vultr
dns-01	Build your own	acme-dns-01-test
http-01	Build your own	acme-http-01-test
tls-alpn-01	Contact us	-

Search acme-http-01- or acme-dns-01- on npm to find more.

Full Documentation

Most of the documentation is done by use-case examples, as shown up at the top of the README.

We're working on more comprehensive documentation for this newly released version. Please open an issue with questions in the meantime.

Commercial Support

Do you need...

• training?
• specific features?
• different integrations?
• bugfixes, on your timeline?
• custom code, built by experts?
• commercial support and licensing?

You're welcome to contact us in regards to IoT, On-Prem, Enterprise, and Internal installations, integrations, and deployments.

We have both commercial support and commercial licensing available.

We also offer consulting for all-things-ACME and Let's Encrypt.

Legal & Rules of the Road

Greenlock™ is a trademark of AJ ONeal

The rule of thumb is "attribute, but don't confuse". For example:

Built with Greenlock Express (a Root project).

Please contact us 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™ | MPL-2.0 | Terms of Use | Privacy Policy