README.md 2.63 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 use:__ https-server _directory_
8
9
  * To-do: Easy integration into Express
  * 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

## Installation

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

(On macOS, you must [manually install the dependency](#macos-dependency) for now.)

19
## Note regarding port 443
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

The server is started on port 443 by default. This is on purpose as an overarching goal of https-server is to make your development environment mirror your production environment as closely possible to remove that complexity from the code you have to write. 

However, you must have your system setup to allow Node (Linux) or your account (macOS) to bind to so-called “privileged” ports so that this works. I will automate this as part of the process in the future but, for the time being:

### Linux

```sh
sudo setcap 'cap_net_bind_service=+ep' $(which node)
```

### macOS

```sh
sudo touch /etc/authbind/byport/443
sudo chown $(whoami) /etc/authbind/byport/443
sudo chmod 755 /etc/authbind/byport/443
```

macOS instructions courtesy of [Setup authbind on Mac OS](https://medium.com/@steve.mu.dev/setup-authbind-on-mac-os-6aee72cb828) by Steve Mu.

Aral Balkan's avatar
Aral Balkan committed
41
42
43
## Usage

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

Aral Balkan's avatar
Aral Balkan committed
45
```sh
46
https-server [folder-to-serve] [port]
Aral Balkan's avatar
Aral Balkan committed
47
```
48
49
50
51
52

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)
  * `[port]` defaults to 443. (See [note regarding port 443](#note-regarding-port-443), above.)
Aral Balkan's avatar
Aral Balkan committed
53
54

If you do not already have TLS certificates, they will be created for you automatically using nodecert.
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

On Linux, all dependencies will be installed automatically for you if they do not exist (only tested with apt).

For macOS, see the note on manually installing the macOS dependency, below.

## macOS dependency

On macOS, you must currently install a mkcert dependency manually:

For your certificate to work in Firefox:

  * [Homebrew](https://brew.sh/): `brew install nss`
  * [MacPorts](https://www.macports.org/): `sudo port install install nss`

## Help wanted

I’ve currently only tested this on Pop!_OS 18.10 (Ubuntu-based distro). I can use your help to test this on other platforms:

  * Windows 64-bit (should work without requiring any dependencies)
  * Linux with yum
  * Linux with pacman
  * macOS (I will be looking at this next)

If you get a chance to try out https-server on the above platforms, please [let me know how/if it works](https://github.com/indie-mirror/https-server/issues). Thank you.