greenlock-express
Advanced tools
Free SSL and managed or automatic HTTPS for node.js with Express, Koa, Connect, Hapi, and all other middleware systems.
Free SSL, Automated HTTPS / HTTP2, served with Node via Express, Koa, hapi, etc.
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.
Cloud-ready with Node cluster.
npm init
npm install --save greenlock-express@v3
npx greenlock init --maintainer-email 'jon@example.com' --manager-config-file ./greenlock.json
"use strict";
require("greenlock-express")
.init(function() {
return {
greenlock: require("./greenlock.js"),
// whether or not to run at cloudscale
cluster: false
};
})
.ready(function(glx) {
var app = require("./app.js");
// Serves on 80 and 443
// Get's SSL certificates magically!
glx.serveApp(app);
});
"use strict";
var pkg = require("./package.json");
module.exports = require("@root/greenlock").create({
// name & version for ACME client user agent
packageAgent: pkg.name + "/" + pkg.version,
// contact for security and critical bug notices
maintainerEmail: pkg.author,
// where to find .greenlockrc and set default paths
packageRoot: __dirname
});
var app = function(req, res) {
res.end("Hello, Encrypted World!");
};
module.exports = app;
npx greenlock defaults --subscriber-email 'jon@example.com' --agree-to-terms
npx greenlock add --subject example.com --altnames example.com
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
wss://)Easy as 1, 2, 3... 4
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
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;
Greenlock Express is designed with these goals in mind:
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";
require("greenlock-express")
.init(function() {
var pkg = require("./package.json");
return {
greenlock: require("@root/greenlock").create({
// name & version for ACME client user agent
packageAgent: pkg.name + "/" + pkg.version,
// contact for security and critical bug notices
maintainerEmail: pkg.author,
// where to find .greenlockrc and set default paths
packageRoot: __dirname
}),
// whether or not to run at cloudscale
cluster: false
};
})
.ready(function(glx) {
var app = require("./app.js");
// Serves on 80 and 443
// Get's SSL certificates magically!
glx.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
# use --staging to use the development API until you're ready to get real certificates
npm start -- --staging
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
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
{
"manager": "greenlock-manager-fs",
"configFile": "./greenlock.json"
}
# show the global defaults
npx greenlock defaults
var defaults = await greenlock.defaults();
{
"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
npx greenlock config --subject example.com
greenlock.sites.get({ subject: "example.com" });
{
"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
npx greenlock defaults --subscriber-email 'mycompany@example.com' --agree-to-terms true
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
npx greenlock add --subject example.com --altnames example.com,www.example.com
greenlock.sites.add({
subject: "example.com",
altnames: ["example.com"]
});
Note: Localhost, Wildcard, and Certificates for Private Networks require DNS validation.
npx greenlock init --manager ./path-or-npm-name.js --manager-FOO 'set option FOO'npx greenlock defaults --store greenlock-store-fs --store-base-path ./greenlock.dnpx greenlock defaults --challenge-http-01 ./you-http-01.jsnpx greenlock update --subject example.com --challenge-http-01 acme-http-01-standalonenpx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxxGreenlock 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.
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.
Do you need...
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.
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 Privacy Policy
FAQs
Free SSL and managed or automatic HTTPS for node.js with Express, Koa, Connect, Hapi, and all other middleware systems.
The npm package greenlock-express receives a total of 4,473 weekly downloads. As such, greenlock-express popularity was classified as popular.
We found that greenlock-express demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.
Research
Security News
The Socket Research Team investigates a malicious Python typosquat of a popular password library that forces Windows shutdowns when input is incorrect.
Product
We’ve redesigned the Socket dashboard with simpler navigation, less visual clutter, and a cleaner UI that highlights what really matters.