New Documentation & v4 Migration Guide

We're still working on the full documentation for this new version, so please be patient.

To start, check out the Migration Guide.

Greenlock is Let's Encrypt for JavaScript

| Built by Root for Hub

Greenlock™ is an Automated Certificate Management Environement 🔐.

| Greenlock | Greenlock Express | ACME.js |

It uses Let's Encrypt to generate Free SSL Certificates, including Wildcard SSL. It supports Automated Renewal of certs for Fully Automated HTTPS.

It's written in plain JavaScript and works in Node, Browsers, and WebPack.

the easiest way to integrate Let's Encrypt into your projects, products, and infrastructure.

[x] Wildcard Certificates
[x] IoT Environments
[x] Enterprise and On-Prem
[x] Private Networks
[x] Localhost Development
[x] Web Hosting Providers
[x] Commercial support

We've built it simple enough for Hobbyists, and robust enough for the Enterprise.

Quick Start

Greenlock is fully-automated, SSL Certificate Manager for IoT, Web Hosting, and Enterprise On-Prem, Edge, and Hybrid Cloud.

(though we started building it for Home Servers)

You can use it for one-off certificates, like certbot, but it is much more powerful than that.

By setting just a few callbacks to let it know where it should store private keys and certificates, it will automatically renew any certificate that you add to it, as long as the process is running.

Certificates are renewed every 45 days by default, and renewal checks will happen several times a day.

<details> <summary>1. Configure</summary>

'use strict';

var pkg = require('./package.json');
var Greenlock = require('greenlock');
var greenlock = Greenlock.create({
    packageRoot: __dirname,
    configDir: "./greenlock.d/",
    packageAgent: pkg.name + '/' + pkg.version,
    maintainerEmail: pkg.author,
    staging: true,
    notify: function(event, details) {
        if ('error' === event) {
            // `details` is an error object in this case
            console.error(details);
        }
    }
});

greenlock.manager
    .defaults({
        agreeToTerms: true,
        subscriberEmail: 'webhosting@example.com'
    })
    .then(function(fullConfig) {
        // ...
    });

</details> <details> <summary>2. Add Domains</summary>

The subject (primary domain on certificate) will be the id, so it's very important that the order of the given domains be deterministic.

var altnames = ['example.com', 'www.example.com'];

greenlock
    .add({
        subject: altnames[0],
        altnames: altnames
    })
    .then(function() {
        // saved config to db (or file system)
    });

Issuance and renewal will start immediately, and run continually.

</details> <details> <summary>3. Test for Success</summary>

The store callbacks will be called every any of your certificates are renewed.

However, you can do a quick one-off check with get.

It will return a certificate immediately (if available), or wait for the renewal to complete (or for it to fail again).

greenlock
    .get({ servername: subject })
    .then(function(pems) {
        if (pems && pems.privkey && pems.cert && pems.chain) {
            console.info('Success');
        }
        //console.log(pems);
    })
    .catch(function(e) {
        console.error('Big bad error:', e.code);
        console.error(e);
    });

</details>

JavaScript API

<details> <summary>Greenlock.create({ configDir, packageAgent, maintainerEmail, staging })</summary>

Greenlock.create()

Creates an instance of greenlock with environment-level values.


var pkg = require('./package.json');
var gl = Greenlock.create({
    configDir: './greenlock.d/',

    // Staging for testing environments
    staging: true,

    // This should be the contact who receives critical bug and security notifications
    // Optionally, you may receive other (very few) updates, such as important new features
    maintainerEmail: 'jon@example.com',

    // for an RFC 8555 / RFC 7231 ACME client user agent
    packageAgent: pkg.name + '/' pkg.version
});

| Parameter | Description | | --------------- | ------------------------------------------------------------------------------------ | | configDir | the directory to use for file-based plugins | | maintainerEmail | the developer contact for critical bug and security notifications | | packageAgent | if you publish your package for others to use, require('./package.json').name here | | staging | use the Let's Encrypt staging URL instead of the production URL | | directoryUrl | for use with other (not Let's Encrypt) ACME services, and the Pebble test server |

</details> <details> <summary>Greenlock#manager.defaults()</summary>

Greenlock#manager.defaults()

Acts as a getter when given no arguments.

Otherwise sets default, site-wide values as described below.

greenlock.manager.defaults({
    // The "Let's Encrypt Subscriber" (often the same as the maintainer)
    // NOT the end customer (except where that is also the maintainer)
    subscriberEmail: 'jon@example.com',
    agreeToTerms: true
    challenges: {
      "http-01": {
        module: "acme-http-01-webroot",
        webroot: "/path/to/webroot"
      }
    }
});

| Parameter | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | agreeToTerms | (default: false) either 'true' or a function that presents the Terms of Service and returns it once accepted | | challenges['http-01'] | provide an http-01 challenge module | | challenges['dns-01'] | provide a dns-01 challenge module | | challenges['tls-alpn-01'] | provide a tls-alpn-01 challenge module | | challenges[type].module | the name of your challenge module | | challenges[type].xxxx | module-specific options | | renewOffset | leave the default Other than for testing, leave this at the default of 45 days before expiration date ('-45d') . Can also be set like 5w, meaning 5 weeks after issue date | | servername | the default servername to use for non-sni requests (many IoT clients) | | subscriberEmail | the contact who agrees to the Let's Encrypt Subscriber Agreement and the Greenlock Terms of Service<br>this contact receives renewal failure notifications | | store | override the default storage module | | store.module | the name of your storage module | | store.xxxx | options specific to your storage module |

</deta

Greenlock.js

Install / Use

README