README.md 3.38 KB
Newer Older
Aral Balkan's avatar
Aral Balkan committed
1 2 3 4 5 6 7 8 9 10 11
# https-server

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


## Installation

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

12

Aral Balkan's avatar
Aral Balkan committed
13 14
## Usage

15

Aral Balkan's avatar
Aral Balkan committed
16
### Commandline
Aral Balkan's avatar
Aral Balkan committed
17

Aral Balkan's avatar
Aral Balkan committed
18
```sh
19
https-server [folder-to-serve] [--port N]
Aral Balkan's avatar
Aral Balkan committed
20
```
21

Aral Balkan's avatar
Aral Balkan committed
22
All arguments are optional. By default, a secure HTTPS server will be created to serve the current folder over port 443.
Aral Balkan's avatar
Aral Balkan committed
23

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

26
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.
27

28

29 30
### API

Aral Balkan's avatar
Aral Balkan committed
31
__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`.
32

33

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

36
  - __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.
37

38
  - __requestListener__ _(function)___:__ see [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener).
39

40
  - ___Returns:___ [https.Server](https://nodejs.org/api/https.html#https_class_https_server) instance, configured with locally-trusted certificates.
41

42
##### Example
43 44 45 46 47 48 49 50

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

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

Aral Balkan's avatar
Aral Balkan committed
51
const options = {} // (optional) customise your server
52 53 54 55 56
const server = httpsServer.createServer(options, app).listen(443, () => {
  console.log(` 🎉 Serving on https://localhost\n`)
})
```

57
#### serve([pathToServe], [callback], [port])
58

59
  - __pathToServe__ _(string)___:__ the directory to serve using [Express](http://expressjs.com/).static.
60

61 62 63 64 65 66 67 68
  - __callback__ _(function)___:__ a function to be called when the server is ready. If you do not specify a callback, you can specify the port as the second argument.

  - __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.


##### Example
69 70 71 72 73 74 75 76

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

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

77 78
## Help wanted

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

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

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

87 88 89 90 91 92
## TODO

  - Command-line app. ✔
  - Easy integration with Express, etc. ✔
  - To-do: Seamless switch to using ACME/Let’s Encrypt in production.

93 94 95
## 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).