greenlock-express.js/WALKTHROUGH.md

Greenlock Express Walkthrough

This will show you the basics of how to

1. Create a node project
2. Create an http app (i.e. express)
3. Serve with Greenlock Express
4. Manage SSL Certificates and Domains

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)

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

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:

"use strict";

//var pkg = require("./package.json");
var app = require("./app.js");

require("greenlock-express")
    .init({
        // where to find .greenlockrc and set default paths
        packageRoot: __dirname,

        // where config and certificate stuff go
        configDir: "./greenlock.d",

        // contact for security and critical bug notices
        maintainerEmail: pkg.author,

        // name & version for ACME client user agent
        //packageAgent: pkg.name + "/" + pkg.version,

        // whether or not to run at cloudscale
        cluster: false
    })
    .serve(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

# use --staging to use the development API until you're ready to get real certificates
npm start -- --staging

Greenlock v4.0.0
Greenlock Config Dir/File: ./greenlock.d/config.json

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

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

By default, it's just a simple config file and directory.

# see which manager and what options are in use
cat .greenlockrc

Example Output

{
    "manager": {
        "module": "@greenlock/manager"
    },
    "configDir": "./greenlock.d"
}

# show the global defaults with the CLI
npx greenlock defaults

// show the global defaults with the API
var defaults = await greenlock.defaults();

Example Output

{
    "store": {
        "module": "greenlock-store-fs",
        "basePath": "./greenlock.d"
    },
    "challenges": {
        "http-01": {
            "module": "acme-http-01-standalone"
        }
    },
    "renewOffset": "-45d",
    "renewStagger": "3d",
    "accountKeyType": "EC-P256",
    "serverKeyType": "RSA-2048",
    "subscriberEmail": "jon@example.com",
    "agreeToTerms": true
}

# show per-site configs with the CLI
npx greenlock config --subject example.com

// show a site config with the API
greenlock.sites.get({ subject: "example.com" });

Example Output

{
    "subject": "example.com",
    "altnames": ["example.com"],
    "renewAt": 1576638107754,
    "defaults": {
        "store": {
            "module": "greenlock-store-fs",
            "basePath": "./greenlock.d"
        },
        "challenges": {
            "http-01": {
                "module": "acme-http-01-standalone"
            }
        }
    }
}

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:

# Set a global subscriber account with the CLI
npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true

// set a global subscriber account with the API
greenlock.manager.defaults({
    subscriberEmail: "mycompany@example.com",
    agreeToTerms: 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).

# Add a certificate with specific domains with the CLI
npx greenlock add --subject example.com --altnames example.com,www.example.com

// Add a certificate with specific domains with the API
greenlock.sites.add({
    subject: "example.com",
    altnames: ["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)