Skip to content

Commit a919875

Browse files
daquinoaldodaquinoaldo
authored
Update README.md
1 parent d74105c commit a919875

1 file changed

Lines changed: 59 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 59 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# HTTPS server running on localhost
2-
Run an express server on localhost with HTTP2 and SSL for free.
2+
Run an express server on localhost with HTTP2 and SSL. Serve static files or import as module in your project.
33

4-
Serve static files or import as module in your project.
4+
https-localhost is a lightweight tool for serving static content on SSL thanks to locally-trusted development certificates.
5+
It works with MacOS, Linux and Windows, on Chrome and Firefox, and requires you no configuration.
56

67
[![NPM](https://nodei.co/npm/https-localhost.png)](https://nodei.co/npm/https-localhost/)
78

@@ -10,75 +11,73 @@ Serve static files or import as module in your project.
1011
[![Dependency Status](https://img.shields.io/david/daquinoaldo/https-localhost.svg)](https://david-dm.org/daquinoaldo/https-localhost)
1112
[![Known Vulnerabilities](https://snyk.io/test/npm/https-localhost/badge.svg)](https://snyk.io/test/npm/https-localhost)
1213
[![GitHub issues](https://img.shields.io/github/issues/daquinoaldo/https-localhost.svg)](https://github.com/daquinoaldo/https-localhost/issues)
13-
[![npm version](https://img.shields.io/npm/v/https-localhost.svg)](https://www.npmjs.com/package/https-localhost?activeTab=versions)
1414

15-
### Install
15+
## Install
1616
```
17-
npm install -g --unsafe-perm=true https-localhost
17+
npm i -g https-localhost
1818
```
19-
#### Why `unsafe-perm=true`?
20-
Is needed on Ubuntu to correctly run the post-install script that trust the localhost SSl certificate.
21-
You can skip it on other platforms.
22-
23-
If you don't trust the script, you can install it in the usual way and than follow the [optional instructions](#optional--trust-the-certificate).
2419

2520
### Use standalone
26-
From terminal navigate into the folder and run `sudo npm install -g` to install this tool globally.
27-
28-
Then serve static file with `sudo serve <static-path>`.
29-
If a static path is not provided the current directory content will be served.
30-
31-
**You must use the absolute path.**
32-
33-
You can change the port setting the PORT environmental variable: `sudo PORT=<port-number> serve <static-path>`.
21+
```
22+
serve ~/myproj
23+
```
24+
- `sudo` may be necessary.
25+
- If a static path is not provided the current directory content will be served.
26+
- You can change the port setting the PORT environmental variable: `PORT=4433 serve ~/myproj`.
3427

3528

3629
### Use as module
37-
Install the dependency with `npm install -s https-localhost`.
30+
Install the dependency
31+
```
32+
npm i -s https-localhost
33+
```
3834

39-
Put in your index.js file:
35+
Put in your `index.js` file:
4036
```
4137
const app = require("https-localhost")
4238
// app is an express app, do what you usually do with express
4339
app.listen(port)
4440
```
45-
If the port number is not provided, it will listen on 443.
46-
47-
To redirect the http traffic to https use `app.redirect()`.
48-
49-
You can also serve static files with `app.serve(path)`
50-
51-
52-
### [Optional] Trust the certificate
53-
**If you are not on MacOS or Ubuntu, you should follow this instructions.**
54-
55-
After `npm install` will run a script that tries to install and validate automatically the certificate.
56-
However, this script is in beta and provided as-is, so there isn't any guarantee that will work.
57-
For that reason you can also install the certificate manually, as follows.
58-
59-
If you decide to not install it, it's fine, the package still work.
60-
However, visiting localhost there will be a invalid certificate issue.
61-
62-
To trust the certificate just add the [cert/defaultCA.pem](cert/defaultCA.pem) certificate
63-
to your list of trusted certificates.
64-
65-
This step depends on the operating system you're running:
66-
- Mac OS:
67-
open Keychain Access, choose System from the left navigation bar, choose "Import items..." from the File app
68-
menu and select the file. Then double-click on the certificate and select always-trust in the Trust panel.
69-
- Linux:
70-
Depending on your Linux distribution, you can use `trust`, `update-ca-certificates`
71-
or another command to mark the generated root certificate as trusted.
72-
73-
#### TL;DR
74-
Looking for something easier? Take a look to [mkcert](https://github.com/FiloSottile/mkcert) (requires Go).
75-
76-
Install it, then move into the https-localhost folder and run:
77-
```
78-
mkcert -install
79-
mkcert -cert-file cert/localhost.crt -key-file cert/localhost.key localhost
80-
```
81-
82-
83-
### License
84-
[AGPL-3.0](LICENSE)
41+
- If the port number is not provided, it will listen on 443.
42+
- To redirect the http traffic to https use `app.redirect()`.
43+
- You can serve static files with `app.serve(path)`.
44+
45+
## Why and how it works
46+
Serving static content on localhost in a trusted SSL connection is not so simple.
47+
It requires to manually generate and trust certificates, with complicate commands and many manual steps.
48+
49+
sserve, serves static content using a locally-trusted certificate, generated with the well-knowed [mkcert](https://github.com/FiloSottile/mkcert) tool.
50+
51+
When you install sserve it automatically creates and installs a local CA in the system (and browsers) root store, and generates the certificate for you.
52+
No configuration is required, just lunch the tool and we take care of everything you need.
53+
54+
### Supported root stores
55+
_The supported root stores are the one supported by mkcert.
56+
Checkout the updated list [here](https://github.com/FiloSottile/mkcert/blob/master/README.md#supported-root-stores)._
57+
58+
**Here there is a handy copy:**
59+
- macOS system store
60+
- Windows system store
61+
- Linux variants that provide either
62+
- `update-ca-trust` (Fedora, RHEL, CentOS) or
63+
- `update-ca-certificates` (Ubuntu, Debian) or
64+
- `trust` (Arch)
65+
- Firefox (macOS and Linux only)
66+
- Chrome and Chromium
67+
- Java (when `JAVA_HOME` is set)
68+
69+
70+
## License
71+
Is released under [AGPL-3.0 - GNU Affero General Public License v3.0](LICENSE).
72+
73+
### Briefly:
74+
- modification and redistribution allowed for both private and **commercial use**
75+
- you must **grant patent rigth to the owner and to all the contributors**
76+
- you must **keep it open source** and distribute under the **same license**
77+
- changes must be documented
78+
- include a limitation of liability and it **does not provide any warranty**
79+
80+
### Warranty
81+
THIS TOOL IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
82+
THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
83+
For the full warranty check the [LICENSE](LICENSE).

0 commit comments

Comments
 (0)