greenlock-express
Advanced tools
Free SSL and managed or automatic HTTPS for node.js with Express, Koa, Connect, Hapi, and all other middleware systems.
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"] }] }
wss://)cluster.Works with any node http app, including
Serving sites with Free SSL is as easy as 1, 2, 3... 4
server.jsapp.jsgreenlock.d/config.jsonnpx greenlock add --subject example.com --altnames example.comnpm start -- --staging# Install the latest node, if needed
curl -fsL bit.ly/node-installer | bash
# Create your project, add Greenlock Express v4
npm init
npm install --save greenlock-express@v4
You can use local file storage or a database. The default is to use file storage.
# 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;
# 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"] }] }
# 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
For a more detail read the full WALKTHROUGH.
Double check the following:
http-01 challenges
ifconfig show a public address (good)? or a private one - 10.x, 192.168.x, etc (bad)?dns-01 challenge?maintainerEmail to a valid addressdig MX example.com for 'john@example.com')dig +trace A example.com; dig +trace www.example.com for [ 'example.com', 'www.example.com' ])configDir to a writeable location (test with touch ./greenlock.d/config.json)sudo or setcapnpm start -- --staging to npm start to use the production serverIf 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.
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.
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 xxxxnpx greenlock update --subject example.com --challenge-dns-01 ./your-dns-01.jsGreenlock 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
FAQs
Free SSL and managed or automatic HTTPS for node.js with Express, Koa, Connect, Hapi, and all other middleware systems.
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.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.