-
-
Notifications
You must be signed in to change notification settings - Fork 15
/
developer-documentation.hbs
102 lines (57 loc) · 3.77 KB
/
developer-documentation.hbs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
# Developer Documentation
This documentation includes the implementation details of Auto Encrypt Localhost and is intended to aid you if you’re trying to improve, debug, or get a deeper understanding of Auto Encrypt.
If you just want to use Auto Encrypt Localhost, please see the public API, as documented in the [README](readme.md).
## Like this? Fund us!
[Small Technology Foundation](https://small-tech.org) is a tiny, independent not-for-profit.
We exist in part thanks to patronage by people like you. If you share [our vision](https://small-tech.org/about/#small-technology) and want to support our work, please [become a patron or donate to us](https://small-tech.org/fund-us) today and help us continue to exist.
## Requirements
Auto Encrypt Localhost is supported on:
- __Node:__ LTS (currently 14.16.0).
- __ECMAScript:__ [ES2019](https://node.green/#ES2019)
## Overview of relationships
__Not shown (for clarity):__ third-party Node modules, the `util` namespace with helper modules – for logging, error handling, and an async `forEach` implementation – and the `typedefs` namespace with JSDoc type definitions.
Generated using [dependency cruiser](https://github.com/sverweij/dependency-cruiser).
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, at the npm post-install stage:
- Downloads and uses correct mkcert release binary for you machine on Linux, macOS, and Windows.
And, on first run (or if the root certificate authority or your TLS certificates are missing):
- 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 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
```sh
npm -s test
```
To see debug output, run `npm -s run test-debug` instead.
Note that [npm cannot prompt for sudo passwords due to a bug](https://github.com/npm/cli/issues/2887) so you will be prompted for your password prior to the running of the tests in order to unlock sudo while the tests are running.
On Windows, run the following command instead:
```sh
npm -s run test-on-windows
```
## Coverage
```sh
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:
```sh
npm -s run generate-developer-documentation
```
{{>main}}
## Like this? Fund us!
[Small Technology Foundation](https://small-tech.org) is a tiny, independent not-for-profit.
We exist in part thanks to patronage by people like you. If you share [our vision](https://small-tech.org/about/#small-technology) and want to support our work, please [become a patron or donate to us](https://small-tech.org/fund-us) today and help us continue to exist.
## Copyright
© 2019-2021 [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).
## License
[AGPL version 3.0 or later.](https://www.gnu.org/licenses/agpl-3.0.en.html)