README.md 3.69 KB
Newer Older
Aral Balkan's avatar
Aral Balkan committed
1
2
3
4
5
6
# https-server

An HTTPS server that uses [nodecert](https://source.ind.ie/hypha/tools/nodecert).

## Design goals

7
  * ✔ Command-line app
8
  * ✔ Easy integration with Express, etc.
9
  * To-do: Seamless switch to using ACME/Let’s Encrypt in production
Aral Balkan's avatar
Aral Balkan committed
10
11
12
13
14
15
16
17
18
19

## Installation

```sh
npm i -g @ind.ie/https-server
```

## Usage

### Commandline
Aral Balkan's avatar
Aral Balkan committed
20

Aral Balkan's avatar
Aral Balkan committed
21
```sh
22
https-server [folder-to-serve] [port]
Aral Balkan's avatar
Aral Balkan committed
23
```
24
25
26
27

Both arguments are optional. Currently, if you want to specify the port manually, you must also specify the folder-to-serve.

  * `[folder-to-serve]` defaults to `.` (the current directory)
28
  * `[port]` defaults to 443 (automatically privileges Node.js to bind to it on Linux. This is not an issue on macOS & Windows.)
Aral Balkan's avatar
Aral Balkan committed
29

30
If you do not already have TLS certificates, they will be created for you automatically using [nodecert](https://source.ind.ie/hypha/tools/nodecert).
31

32
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.
33

34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
### API

http-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`.

### createServer([options], [requestListener])

  * options: [(Object)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Accepts options from [tls.createServer()](https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener), [tls.createSecureContext()](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) and [http.createServer()](https://nodejs.org/api/http.html#http_http_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.

  * requestListener: [(Function)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) A listener to be added to the 'request' event.

  * Returns: [https.Server](https://nodejs.org/api/https.html#https_class_https_server) instance, configured with locally-trusted certificates.

#### Example

```js
const httpsServer = require('https-server')
const express = require('express')

const app = express()
app.use(express.static('.'))

Aral Balkan's avatar
Aral Balkan committed
55
const options = {} // (optional) customise your server
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
const server = httpsServer.createServer(options, app).listen(443, () => {
  console.log(` 🎉 Serving on https://localhost\n`)
})
```

### serve([pathToServe], [port])

  * pathToServe: [(string)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/string) path to serve using [Express](http://expressjs.com/).static.

  * port: [(number)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) the port to serve on. Defaults to 443. (On Linux, privileges to bind to the port are automatically obtained for you.)

#### Example

```js
const httpsServer = require('https-server')

// Serve the current directory over https://localhost
const server = httpsServer.serve()
```

76
77
## Help wanted

78
I can use your help to test https-server on other the following platforms:
79
80
81

  * Windows 64-bit (should work without requiring any dependencies)
  * Linux with yum
82
  * macOS with MacPorts
83

84
Please [let me know how/if it works](https://github.com/indie-mirror/https-server/issues). Thank you!
85
86
87
88

## 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).