11 KiB

Raw Blame History

Greenlock Express v4 is Let's Encrypt for Node

| Built by Root for Hub |

Free SSL for Node Web Servers

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

You define your app and let Greenlock handle issuing and renewing Free SSL Certificates.

npm init
npm install --save greenlock-express@v4

server.js:

"use strict";

var app = require("./app.js");

require("greenlock-express")
    .init({
        packageRoot: __dirname,
        configDir: "./greenlock.d",

        // contact for security and critical bug notices
        maintainerEmail: "jon@example.com",

        // whether or not to run at cloudscale
        cluster: false
    })
    // Serves on 80 and 443
    // Get's SSL certificates magically!
    .serve(app);

./greenlock.d/config.json:

{ "sites": [{ "subject": "example.com", "altnames": ["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://)
- Cloud-ready with Node cluster.
Fully customizable
- Reasonable defaults
- Domain Management
- Key and Certificate Management
- ACME Challenge Plugins

Compatibility

Works with any node http app, including

Express
Koa
hapi
rill
http2
cluster
etc...

QuickStart: Serve Sites with Free SSL

Easy as 1, 2, 3... 4

Overview

Create a Project with Greenlock Express
- server.js
- app.js
Setup the config file (or database)
- greenlock.d/config.json
Add Domains
- npx greenlock add --subject example.com --altnames example.com
Hello, World!
- npm start -- --staging

1. Create your Project

npm init
npm install --save greenlock-express@v4

You can use local file storage or a database. The default is to use file storage.

2. Initialize and Config (Dir or DB)

# Note: you can use the CLI to create `server.js` and `greenlock.d/config.json`
npx greenlock init --config-dir ./greenlock.d --maintainer-email 'jon@example.com'

server.js:

"use strict";

var app = require("./app.js");

require("greenlock-express")
    .init({
        packageRoot: __dirname,

        // contact for security and critical bug notices
        configDir: "./greenlock.d",

        // whether or not to run at cloudscale
        cluster: false
    })
    // Serves on 80 and 443
    // Get's SSL certificates magically!
    .serve(app);

app.js:

"use strict";

// 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!");
};

module.exports = app;

3. Add Sites

# Note: you can use the CLI to edit the config file
npx greenlock add --subject example.com --altnames example.com

greenlock.d/config.json:

{ "sites": [{ "subject": "example.com", "altnames": ["example.com"] }] }

4. Hello, Encrypted World!

# Note: you can use npm start to run server.js with the --staging flag set
npm start -- --staging

> my-project@1.0.0 start /srv/www/my-project
> node server.js

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

Walkthrough

For a more detail read the full WALKTHROUGH.

Examples

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

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

Custom Domain Management
- npx greenlock init --manager ./path-or-npm-name.js --manager-FOO 'set option FOO'
Custom Key & Cert Storage
- npx greenlock defaults --store greenlock-store-fs --store-base-path ./greenlock.d
Custom ACME HTTP-01 Challenges
- npx greenlock defaults --challenge-http-01 ./you-http-01.js
- npx greenlock update --subject example.com --challenge-http-01 acme-http-01-standalone
Custom ACME DNS-01 Challenges
- npx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx
- 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	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	-

Example Usage:

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.

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

11 KiB Raw Blame History