README.md 2.27 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 8
  * ✔ __Command-line use:__ https-server _directory_
  * TO-DO: Easy integration into Express
Aral Balkan's avatar
Aral Balkan committed
9 10 11 12 13 14 15 16 17

## Installation

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

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

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

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
40 41 42
## Usage

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

Aral Balkan's avatar
Aral Balkan committed
44
```sh
Aral Balkan's avatar
Aral Balkan committed
45
https-server <folder-to-serve>
Aral Balkan's avatar
Aral Balkan committed
46 47 48
```

If you do not already have TLS certificates, they will be created for you automatically using nodecert.
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72

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.