Commit 4f26e0a2 authored by Aral Balkan's avatar Aral Balkan

Update readme with changes for globally-trusted certificates

parent cf47b101
# https-server
# HTTPS Server
An HTTPS server that uses [nodecert](https://source.ind.ie/hypha/tools/nodecert).
HTTPS Server is a secure [Small Tech](https://ar.al/2019/03/04/small-technology/) personal server for seamless development and live use.
HTTP Server uses [nodecert](https://source.ind.ie/hypha/tools/nodecert) for seamless locally-trusted TLS certificate provisioning and use during development and [Greenlock](https://git.coolaj86.com/coolaj86/greenlock.js) for seamless globally-trusted [Let’s Encrypt](https://letsencrypt.org/) TLS certificate provisioning and use on live environments.
## Installation
## Install
```sh
npm i -g @ind.ie/https-server
```
## Usage
## Use
### Commandline
### Command-line
```sh
https-server [folder-to-serve] [--port N]
https-server [folder-to-serve] [--port N] [--global <email address>] [--version]
```
All arguments are optional. By default, a secure HTTPS server will be created to serve the current folder over port 443.
All command-line arguments are optional. By default, an HTTPS server with locally-trusted certificates will be created for you to serve the current folder over port 443.
If you do not already have TLS certificates, they will be created for you automatically using [nodecert](https://source.ind.ie/hypha/tools/nodecert).
All dependencies will be installed automatically for you if they do not exist if you have apt, pacman, or yum (untested) on Linux or if you have [Homebrew](https://brew.sh/) or [MacPorts](https://www.macports.org/) (untested) on macOS.
All dependencies are installed automatically for you if they do not exist if you have apt, pacman, or yum (untested) on Linux or if you have [Homebrew](https://brew.sh/) or [MacPorts](https://www.macports.org/) (untested) on macOS.
If you specify the `--global` flag and provide an email address, globally-trusted Let’s Encrypt TLS certificates are automatically provisioned for you using Greenlock the first time you hit your hostname. The hostname for the certificates is automatically set from the hostname of your system (and the _www._ subdomain is also automatically provisioned). The email address is a requirement of Let’s Encrypt.
__Note:__ the telemetry and “community member” “features” in Greenlock are, of course, disabled in HTTPS Server.
### API
__https-server__ provides a `createServer` method that behaves like the built-in _https_ module’s `createServer` function so anywhere you use `https.createServer`, you can simply replace it with `httpsServer.createServer`.
HTTPS Server’s `createServer` method behaves like the built-in _https_ module’s `createServer` function. Anywhere you use `https.createServer`, you can simply replace it with `httpsServer.createServer`.
#### createServer([options], [requestListener])
- __options__ _(object)___:__ see [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener). Populates the `cert` and `key` properties from the automatically-created [nodecert](https://source.ind.ie/hypha/tools/nodecert/) certificates and will overwrite them if they exist in the options object you pass in.
- __options__ _(object)___:__ see [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener). Populates the `cert` and `key` properties from the automatically-created [nodecert](https://source.ind.ie/hypha/tools/nodecert/) or Let’s Encrypt certificates and will overwrite them if they exist in the options object you pass in. If you pass in an email address (`options.email`), globally-trusted TLS certificates are obtained from Let’s Encrypt.
- __requestListener__ _(function)___:__ see [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener).
- __requestListener__ _(function)___:__ see [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener). If you don’t pass a request listener, HTTPS Server will use its default one.
- ___Returns:___ [https.Server](https://nodejs.org/api/https.html#https_class_https_server) instance, configured with locally-trusted certificates.
__Returns:__ [https.Server](https://nodejs.org/api/https.html#https_class_https_server) instance, configured with either locally-trusted certificates via nodecert or globally-trusted ones via Greenlock/Let’s Encrypt.
##### Example
......@@ -54,7 +58,7 @@ const server = httpsServer.createServer(options, app).listen(443, () => {
})
```
#### serve([pathToServe], [callback], [port])
#### serve([pathToServe], [callback], [port], [email])
- __pathToServe__ _(string)___:__ the directory to serve using [Express](http://expressjs.com/).static.
......@@ -62,7 +66,9 @@ const server = httpsServer.createServer(options, app).listen(443, () => {
- __port__ _(number)___:__ the port to serve on. Defaults to 443. (On Linux, privileges to bind to the port are automatically obtained for you.)
- ___Returns:___ [https.Server](https://nodejs.org/api/https.html#https_class_https_server) instance, configured with locally-trusted certificates.
- __email__ _(string)___:__ the email address to use for globally-trusted Let’s Encrypt certificates. If provided, globally-trusted certificates will be provisioned and used. (If absent, locally-trusted certificates will be provisioned using nodecert.)
__Returns:__ [https.Server](https://nodejs.org/api/https.html#https_class_https_server) instance, configured with either locally or globally-trusted certificates.
##### Example
......@@ -76,20 +82,18 @@ const server = httpsServer.serve()
## Help wanted
I can use your help to test https-server on other the following platforms:
I can use your help to test HTTPS Server on the following platform/package manager combinations:
- Windows 64-bit (should work without requiring any dependencies)
- Linux with yum
- macOS with MacPorts
Please [let me know how/if it works](https://github.com/indie-mirror/https-server/issues). Thank you!
## TODO
- Command-line app. ✔
- Easy integration with Express, etc. ✔
- To-do: Seamless switch to using ACME/Let’s Encrypt in production.
## Thanks
* [thagoat](https://github.com/thagoat) for confirming that [installation works on Arch Linux with Pacman](https://github.com/indie-mirror/https-server/issues/1).
* [Tim Knip](https://github.com/timknip) for confirming that [the module works with 64-bit Windows](https://github.com/indie-mirror/https-server/issues/2) with the following behaviour: “Install pops up a windows dialog to allow adding the cert.”
* [Run Rabbit Run](https://hackers.town/@nobody) for [the following information](https://hackers.town/@nobody/101670447262172957) on 64-bit Windows: “Win64: works with the windows cert install popup on server launch. Chrome and ie are ok with the site then. FF 65 still throws the cert warning even after restarting.”
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment