@root/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.js.greenlockrcgreenlock.d/config.jsonnpx greenlock add --subject example.com --altnames example.comnpm start -- --stagingIf you're familiar with node, npm, and npx: this is all you need to do:
npm init
npm install --save greenlock-express@v4
npx greenlock init --config-dir greenlock.d --maintainer-email jon@example.com
npx greenlock add --subject example.com --altnames example.com
npm start -- --staging
Once you've tested that that works, you can change app.js to suit your needs replace the built-in callbacks for things like certificate storage as you like.
If you need to install Node.js, do so:
Mac, Linux:
curl -fsS https://webinstall.dev/node | bash
Windows 10:
curl -fsSA "MS" https://webinstall.dev/node | powershell
Then create a directory for your project, and initialize it:
mkdir -p my-sites
pushd my-sites
npm init
npm install --save greenlock-express@v4
You can use local file storage or a database. The default is to use file storage.
You'll need to create server.js and greenlock.d/config.json. You can do so using the CLI, API, or by hand.
Anytime you install an npm module that contains an executable,
you can run it using npx.
To initialize the Greenlock config, run npx greenlock init:
npx greenlock init --config-dir ./greenlock.d --maintainer-email 'jon@example.com'
Create server.js like so:
server.js:
'use strict';
var app = require('./app.js');
require('greenlock-express')
.init({
packageRoot: __dirname,
// where to look for configuration
configDir: './greenlock.d',
// whether or not to run at cloudscale
cluster: false
})
// Serves on 80 and 443
// Get's SSL certificates magically!
.serve(app);
Create app.js like so:
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;
Greenlock uses .greenlockrc to figure out whether to use the file system or a database for config,
as well as where its root directory is.
.greenlockrc
{"manager":{"module":"@greenlock/manager"},"configDir":"greenlock.d"}
The greenlock.d/config.json is NOT intended to be edited by hand, as it is a substitute for a database, but it looks like this:
{ "defaults": { "subscriberEmail": "john.doe@example.com" }, "sites": [] }
For security, you must specify which sites you allow to request certificates. If you need this to be dynamic (i.e. checking a database or API, see the section below on custom site managers).
Every site has a "subject" (its primary domain name) and one or more "altnames" (secondary or related domain names on the same certificate).
Simply supply the names of sites that you manage and they will be added to the file system config, or database.
npx greenlock add --subject example.com --altnames example.com,www.example.com
You should NOT edit greenlock.d/config.json with your own tools. Use greenlock.manager.add({}) instead.
greenlock.d/config.json:
{ "sites": [{ "subject": "example.com", "altnames": [ "example.com", "www.example.com" ] }] }
That was it! Now you can run your server!
When you run npm start, it will automatically run node server.js (or package.json.scripts.start).
For arguments that npm start should ignore, place them after --.
Here we use --staging in order to tell greenlock to issue test certificates rather than real certificates.
# 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
If everything worked you can visit your site in your browser, and after a few seconds you'll get a certificate warning and, after that, see a "Hello World" message. The debug (staging) certificates will be saved in greenlock.d/staging. Run again without --staging and you will get real certificates.
Now you're ready to update app.js with your code. For example, try this next:
npm install --save express
mkdir -p public
echo '<h1>Hello!</h1>' >> public/index.html
app.js:
'use strict';
var path = require('path');
var express = require('express');
var app = express();
app.get('/', express.static(path.join(__dirname, "public")));
module.exports = app;
// for development and debugging
if (require.main === module) {
require('http').createServer(app).listen(3000, function () {
console.info("Listening for HTTP on", this.address());
});
}
For a more detail read the full WALKTHROUGH.
To see all of the examples, just browse greenlock-express.js/examples/
| Example | Location + Description |
|---|---|
| Express | ./examples/express/ how to export an express app |
| Node's http2 | ./examples/http2/ how to use Node's built-in http2 server |
| Node's https | ./examples/https how to customize the https server |
| WebSockets | ./examples/websockets/ how to use on('upgrade') |
| Socket.IO | ./examples/socket.io how to overcomplicate a persistent connection |
| Cluster | ./examples/cluster/ how to use Node's built-in clustering with master and worker processes |
| Wildcards | coming someday (ask to help create this) how to use DNS-01 for wildcard certs |
| Localhost | coming someday (ask to help create this) how to use DNS-01 for domains that resolve to private networks, such as 127.0.0.1 |
| CI/CD | coming someday (ask to help create this) how to use the --staging environment for test deployments |
| HTTP Proxy | examples/http-proxy how to (reverse) proxy decrypted traffic to another server |
| - | Build your own Be sure to tell me about it (open an issue) |
99% of the questions I get are answered in the QuickStart, or in the Examples.
Before you go into your specific use case, just try out the QuickStart from start to finish so that you can see that the default setup works, you get feel for the "lay of the land", and you know what to edit.
You don't. It's JSON on purpose.
The configuration has to be serializable (i.e. could go in a database).
The config file is meant for simple use cases, for the average dev and it is managed with npx greenlock ..., as shown in the QuickStart.
If you have a dynamic or advanced use case (i.e. you need stuff in a database, or to change config on-the-fly), you can use the Greenlock API (not Greenlock Express) and you'll love it.
If you're layering a lot of complexity with dev ops tools, but you don't really understand the tools that well (i.e. Docker), either use ENVIRONMENT variables or put the npx greenlock ... commands in your setup script. You MUST use a database for lambda "cloud functions" and such.
You can also just mangle the Greenlock API to do what you want... but I don't recommend it. Keep it simple and your future self with thank you.
General rule of thumb: commit code, not data / config.
You don't. Not usually.
Let's Encrypt REQUIRES port 80 for HTTP-01 challenges.
But if you're using DNS-01 or you have a proxy in place, just use the raw node server. See these examples:
If you want to use Greenlock as a proxy, see this example:
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.
server.js and/or .greenlockrc to switch from the default configDir manager to your config system or databasenpx greenlock init --manager ./path-or-npm-name.js --manager-FOO 'set option FOO'defaults section of greenlock.d/config.json to change the certificate store or databasenpx greenlock defaults --store greenlock-store-fs --store-base-path ./greenlock.ddefaults section of greenlock.d/config.json to change the challenges by handnpx greenlock defaults --challenge-http-01 ./you-http-01.jsdefaults section of greenlock.d/config.json to change the challenges by handnpx 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.sites.set({
subject: "example.com",
challenges: {
"dns-01": {
module: "my-npm-module-name",
foo: "some option",
bar: "some other option"
}
}
});
If you're using the default configDir management you can edit greenlock.d/config.json by hand to change
which default and per-site modules are used.
You can use the CLI, even if you're using a database, buckets, or your own file storage.
You can also use the API, particularly if you need to set values dynamically per-site or per-user rather than using the global defaults. The certificate store and all challenges can be set per-site, but most per-site use cases are for DNS-01.
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.
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 @root/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
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.