AJ ONeal 67d6a60a37 | ||
---|---|---|
dist/etc/systemd/system | ||
examples | ||
lib | ||
scripts | ||
test | ||
.gitignore | ||
.prettierrc | ||
LICENSE | ||
README.md | ||
WALKTHROUGH.md | ||
config.js | ||
demo.js | ||
greenlock-express.js | ||
greenlock-shim.js | ||
http-middleware.js | ||
https-middleware.js | ||
install.sh | ||
main.js | ||
master.js | ||
package-lock.json | ||
package.json | ||
servers.js | ||
single.js | ||
sni.js | ||
worker.js |
README.md
Greenlock Express v4 is Let's Encrypt for Node
Free SSL for Node Web Servers
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"] }] }
Let's Encrypt for...
- IoT
- Enterprise On-Prem
- Local Development
- Home Servers
- Quitting Heroku
Features
- Let's Encrypt v2 (November 2019)
- ACME Protocol (RFC 8555)
- HTTP Validation (HTTP-01)
- DNS Validation (DNS-01)
- ALPN Validation (TLS-ALPN-01)
- Need ALPN validation? contact us
- Automated HTTPS
- Fully Automatic Renewals every 45 days
- Free SSL
- Wildcard SSL
- Localhost certificates
- HTTPS-enabled Secure WebSockets (
wss://
) - Cloud-ready with Node
cluster
.
- Fully customizable
- Reasonable defaults
- Domain Management
- Key and Certificate Management
- ACME Challenge Plugins
Compatibility
Works with any node http app, including
- Express
- Koa
- hapi
- rill
- http2
- cluster
- etc...
v4 QuickStart
Serving sites with Free SSL is as easy as 1, 2, 3... 4
Overview
- Create a Project with Greenlock Express
server.js
app.js
- Setup the config file (or database)
greenlock.d/config.json
- Add Domains
npx greenlock add --subject example.com --altnames example.com
- Hello, World!
npm start -- --staging
1. Create your Project
# 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.
2. Initialize and Config (Dir or DB)
# 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;
3. Add Sites
# Note: you can use the CLI to edit the config file
npx greenlock add --subject example.com --altnames example.com,www.example.com
greenlock.d/config.json
:
{ "sites": [{ "subject": "example.com", "altnames": [ "example.com", "www.example.com" ] }] }
4. Hello, Encrypted World!
# 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
Walkthrough
For a more detail read the full WALKTHROUGH.
FAQ
1. But did YOU read the QuickStart?
Most of the questions I get come from people not even looking at the QuickStart and just jumping to asking a quostion
2. How to use JavaScript configuration?
You don't. The configuration has to be serializable (i.e. could go in a database).
(General rule of thumb: commit code, not data / config.)
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 an advanced use case (i.e. you need stuff in a database), 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 can also just mangle the Greenlock API to do what you want... but I don't recommend it. Keep it simple.
3. How to use non-standard ports (not 80, 443)?
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:
Examples
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) |
Troubleshooting
What if the example didn't work?
Double check the following:
- Public Facing IP for
http-01
challenges- Are you running this as a public-facing webserver (good)? or localhost (bad)?
- Does
ifconfig
show a public address (good)? or a private one - 10.x, 192.168.x, etc (bad)? - If you're on a non-public server, are you using the
dns-01
challenge?
- valid email
- You MUST set
maintainerEmail
to a valid address - MX records must validate (
dig MX example.com
for'john@example.com'
)
- You MUST set
- valid DNS records
- Must have public DNS records (test with
dig +trace A example.com; dig +trace www.example.com
for[ 'example.com', 'www.example.com' ]
)
- Must have public DNS records (test with
- write access
- You MUST set
configDir
to a writeable location (test withtouch ./greenlock.d/config.json
)
- You MUST set
- port binding privileges
- You MUST be able to bind to ports 80 and 443
- You can do this via
sudo
orsetcap
- API limits
- You MUST NOT exceed the API usage limits per domain, certificate, IP address, etc
- Red Lock, Untrusted
- You MUST switch from
npm start -- --staging
tonpm start
to use the production server - The API URL should not have 'acme-staging-v02', but should have 'acme-v02'
- You MUST switch from
Using a Database, S3, etc
If 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.
Advanced Configuration
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.
Easy to Customize
- Custom Domain Management
- edit
server.js
and/or.greenlockrc
to switch from the defaultconfigDir
manager to your config system or database - CLI example:
npx greenlock init --manager ./path-or-npm-name.js --manager-FOO 'set option FOO'
- edit
- Custom Key & Cert Storage
- edit the
defaults
section ofgreenlock.d/config.json
to change the certificate store or database - CLI example:
npx greenlock defaults --store greenlock-store-fs --store-base-path ./greenlock.d
- edit the
- Custom ACME HTTP-01 Challenges
- edit the
defaults
section ofgreenlock.d/config.json
to change the challenges by hand - CLI example:
npx greenlock defaults --challenge-http-01 ./you-http-01.js
- edit the
- Custom ACME DNS-01 Challenges
- edit the
defaults
section ofgreenlock.d/config.json
to change the challenges by hand - CLI example:
npx greenlock defaults --challenge-dns-01 acme-dns-01-ovh --challenge-dns-01-token xxxx
- Per-site example:
npx greenlock update --subject example.com --challenge-dns-01 ./your-dns-01.js
- API example:
greenlock.sites.set({ subject: "example.com", challenges: { "dns-01": { module: "my-npm-module-name", foo: "some option", bar: "some other option" } } });
- edit the
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.
Ready-made Integrations
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.
Full Documentation
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.
Commercial Support
Do you need...
- training?
- specific features?
- different integrations?
- bugfixes, on your timeline?
- custom code, built by experts?
- commercial support and licensing?
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.
Legal & Rules of the Road
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