goldilocks.js/README.md

158 lines
4.7 KiB
Markdown
Raw Normal View History

2016-12-30 09:41:04 +00:00
<!-- BANNER_TPL_BEGIN -->
2016-12-30 07:53:29 +00:00
About Daplie: We're taking back the Internet!
2016-11-25 17:20:39 +00:00
--------------
2016-12-30 07:53:29 +00:00
Down with Google, Apple, and Facebook!
We're re-decentralizing the web and making it read-write again - one home cloud system at a time.
Tired of serving the Empire? Come join the Rebel Alliance:
2016-11-25 17:20:39 +00:00
2016-12-30 07:53:29 +00:00
<a href="mailto:jobs@daplie.com">jobs@daplie.com</a> | [Invest in Daplie on Wefunder](https://daplie.com/invest/) | [Pre-order Cloud](https://daplie.com/preorder/), The World's First Home Server for Everyone
2016-11-25 17:20:39 +00:00
2016-12-30 09:41:04 +00:00
<!-- BANNER_TPL_END -->
2016-11-25 17:20:39 +00:00
serve-https
===========
2015-07-08 07:46:01 +00:00
A simple HTTPS static file server with valid TLS (SSL) certs.
2015-07-08 07:46:01 +00:00
Comes bundled a valid certificate for localhost.daplie.com,
which is great for testing and development, and you can specify your own.
2015-06-30 23:11:01 +00:00
Also great for testing ACME certs from letsencrypt.org.
2015-06-24 21:44:42 +00:00
Install
-------
```bash
2017-01-08 00:21:12 +00:00
# v2.x
npm install --global serve-https@2.x
# v1.x
2017-01-07 23:43:45 +00:00
npm install --global serve-https@1.x
2017-01-08 00:21:12 +00:00
# master in git (via ssh)
npm install -g git+ssh://git@git.daplie.com:Daplie/serve-https
# master in git (unauthenticated)
npm install -g git+https://git@git.daplie.com:Daplie/serve-https
2015-06-24 21:44:42 +00:00
```
2017-01-07 23:43:45 +00:00
```bash
serve-https
2015-06-24 21:44:42 +00:00
```
2017-01-07 23:43:45 +00:00
```bash
2015-07-08 06:45:40 +00:00
Serving /Users/foo/ at https://localhost.daplie.com:8443
2015-06-24 21:44:42 +00:00
```
Usage
-----
2016-10-17 23:50:17 +00:00
Examples:
```
2017-01-20 20:13:41 +00:00
# Install
npm install -g git+https://git@git.daplie.com:Daplie/serve-https
# Use tunnel
serve-https --servername jane.daplie.me --agree-tos --email jane@example.com --tunnel
# BEFORE you access in a browser for the first time, use curl
# (because there's a concurrency bug in the greenlock setup)
curl https://jane.daplie.me
2016-10-17 23:50:17 +00:00
```
2016-10-17 23:52:32 +00:00
Options:
2016-10-07 19:46:29 +00:00
* `-p <port>` - i.e. `sudo serve-https -p 443` (defaults to 80+443 or 8443)
2015-07-08 06:45:40 +00:00
* `-d <dirpath>` - i.e. `serve-https -d /tmp/` (defaults to `pwd`)
* `-c <content>` - i.e. `server-https -c 'Hello, World! '` (defaults to directory index)
2016-10-17 23:46:11 +00:00
* `--express-app <path>` - path to a file the exports an express-style app (`function (req, res, next) { ... }`)
2016-10-07 19:46:29 +00:00
* `--livereload` - inject livereload into all html pages (see also: [fswatch](http://stackoverflow.com/a/13807906/151312)), but be careful if `<dirpath>` has thousands of files it will spike your CPU usage to 100%
2016-10-17 23:46:11 +00:00
* `--email <email>` - email to use for Let's Encrypt, Daplie DNS, Daplie Tunnel
* `--agree-tos` - agree to terms for Let's Encrypt, Daplie DNS
* `--servername <servername>` - use `<servername>` instead of `localhost.daplie.com`
* `--tunnel` - make world-visible (must use `--servername`)
Specifying a custom HTTPS certificate:
2015-07-08 07:46:01 +00:00
* `--key /path/to/privkey.pem` specifies the server private key
2015-07-13 23:46:44 +00:00
* `--cert /path/to/fullchain.pem` specifies the bundle of server certificate and all intermediate certificates
* `--root /path/to/root.pem` specifies the certificate authority(ies)
2015-07-13 23:46:44 +00:00
Note: `--root` may specify single cert or a bundle, and may be used multiple times like so:
2015-07-08 07:46:01 +00:00
```
2015-07-13 23:46:44 +00:00
--root /path/to/primary-root.pem --root /path/to/cross-root.pem
2015-07-08 07:46:01 +00:00
```
Other options:
2015-07-13 23:46:44 +00:00
* `--serve-root true` alias for `-c` with the contents of root.pem
2015-07-08 07:46:01 +00:00
* `--servername example.com` changes the servername logged to the console
2015-07-13 23:46:44 +00:00
* `--letsencrypt-certs example.com` sets and key, fullchain, and root to standard letsencrypt locations
2015-06-30 23:11:01 +00:00
Examples
--------
```bash
serve-https -p 1443 -c 'Hello from 1443' &
serve-https -p 2443 -c 'Hello from 2443' &
2016-10-07 19:46:29 +00:00
serve-https -p 3443 -d /tmp &
2015-06-30 23:11:01 +00:00
curl https://localhost.daplie.com:1443
> Hello from 1443
curl --insecure https://localhost:2443
> Hello from 2443
curl https://localhost.daplie.com:3443
> [html index listing of /tmp]
```
2016-10-07 19:46:29 +00:00
And if you tested <http://localhost.daplie.com:3443> in a browser,
it would redirect to <https://localhost.daplie.com:3443> (on the same port).
(in curl it would just show an error message)
### Testing ACME Let's Encrypt certs
2015-07-08 06:51:38 +00:00
In case you didn't know, you can get free https certificates from
[letsencrypt.org](https://letsencrypt.org)
2015-07-08 06:48:18 +00:00
(ACME letsencrypt)
and even a free subdomain from <https://freedns.afraid.org>.
2015-07-08 06:51:38 +00:00
If you want to quickly test the certificates you installed,
you can do so like this:
```bash
sudo serve-https -p 8443 \
--letsencrypt-certs test.mooo.com \
2015-07-13 23:46:44 +00:00
--serve-root true
```
which is equilavent to
```bash
sudo serve-https -p 8443 \
--servername test.mooo.com
--key /etc/letsencrypt/live/test.mooo.com/privkey.pem \
2015-07-13 23:46:44 +00:00
--cert /etc/letsencrypt/live/test.mooo.com/fullchain.pem \
--root /etc/letsencrypt/live/test.mooo.com/root.pem \
-c "$(cat 'sudo /etc/letsencrypt/live/test.mooo.com/root.pem')"
```
and can be tested like so
```bash
2015-07-13 23:46:44 +00:00
curl --insecure https://test.mooo.com:8443 > ./root.pem
curl https://test.mooo.com:8843 --cacert ./root.pem
```
* [QuickStart Guide for Let's Encrypt](https://coolaj86.com/articles/lets-encrypt-on-raspberry-pi/)
* [QuickStart Guide for FreeDNS](https://coolaj86.com/articles/free-dns-hosting-with-freedns-afraid-org.html)