@@ -8,16 +8,26 @@ At installation time, Auto Encrypt Localhost uses mkcert to create a local certi
At runtime, you can reach your server via the local loopback addresses (localhost, 127.0.0.1) on the device itself and also from other devices on the local area network by using your device’s external IPv4 address(es).
## System requirements
Tested and supported on:
- Linux (tested with elementary OS Hera)
- macOS (tested on Big Sur)
- Windows 10 (tested in Windows Terminal with PowerShell)
## Installation
```sh
npm i @small-tech/auto-encrypt-localhost
```
Note that during installation, Auto Encrypt Localhost will create your local certificate authority and install it in the system root store and generate locally-trusted certificates. These actions require elevated privileges (`sudo`). Since [npm does not handle sudo prompts correctly in lifecycle scripts](https://github.com/npm/cli/issues/2887), you will see a graphical sudo prompt pop up to ask you for your adminstrator password. Once you’ve provided it, installation will proceed as normal.
Note that during installation, Auto Encrypt Localhost will create your local certificate authority and install it in the system root store and generate locally-trusted certificates. These actions require elevated privileges. Since [npm does not handle sudo prompts correctly in lifecycle scripts](https://github.com/npm/cli/issues/2887), you will see a graphical sudo prompt pop up to ask you for your adminstrator password. Once you’ve provided it, installation will proceed as normal.
On Windows, you will also be prompted separately to allow the installation of the certificates.
@@ -25,22 +25,24 @@ __Not shown (for clarity):__ third-party Node modules, the `util` namespace with
Generated using [dependency cruiser](https://github.com/sverweij/dependency-cruiser).
To run dependecy cruiser, you will need to [install Graphviz](https://graphviz.org/download/).
To run dependency cruiser, you will need to [install Graphviz](https://graphviz.org/download/).
## How it works in more detail
Auto Encrypt Localhost is a Node.js wrapper for [mkcert](https://github.com/FiloSottile/mkcert/) that:
Auto Encrypt Localhost is a Node.js wrapper for [mkcert](https://github.com/FiloSottile/mkcert/) that, at the npm post-install stage:
* Downloads and uses correct mkcert release binary for you machine on Linux, macOS, and Windows.
- Downloads and uses correct mkcert release binary for you machine on Linux, macOS, and Windows.
* Automatically installs the _certutil_ (nss) dependency on Linux on systems with apt, pacman, yum (untested) and and on macOS if you have [Homebrew](https://brew.sh) or [MacPorts](https://www.macports.org/)(untested).
- Automatically installs the _certutil_ (nss) dependency on Linux on systems with apt, pacman, yum (untested) and and on macOS if you have [Homebrew](https://brew.sh) or [MacPorts](https://www.macports.org/)(untested).
* Creates a root Certificate Authority.
- Creates a root Certificate Authority.
* Creates locally-trusted TLS certificates for localhost, 127.0.0.1, and ::1.
- Creates locally-trusted TLS certificates for localhost, 127.0.0.1, and ::1.
You can use these certificates for local development without triggering self-signed certificate errors.
At runtime, you can use the library to create your HTTPS servers instead of using the built-in Node.js `https` module.
For more details on how Auto Encrypt Localhost works behind the scenes, please [see the mkcert README](https://github.com/FiloSottile/mkcert/blob/master/README.md).
## Tests
...
...
@@ -51,6 +53,12 @@ npm -s test
To see debug output, run `npm -s run test-debug` instead.
On Windows, run the following command instead:
```sh
npm -s run test-on-windows
```
## Coverage
```sh
...
...
@@ -59,6 +67,12 @@ npm -s run coverage
To see debug output, run `npm -s run coverage-debug` instead.
On Windows, run the following command instead:
```sh
npm -s run coverage-on-windows
```
## Documentation
To regenerate the dependency diagram and this documentation:
