[wip] port readme contents over to an mdbook

book/src/proxy/https.md

@@ -0,0 +1,78 @@
+# HTTPS
+
+The proxy can be setup to enable using https to access the running instances.
+Besides the warm and fuzy feeling of knowing that nobody can snoop on the trafic
+that is happening completely local inside your machine. Accessing the page over
+https is required for some javascript features (such as service workers), as
+they are only available in "secure contexts".
+
+## Getting a wildcard certificate
+
+Since the domain name used for the instance is dynamic, a wildcard certificate
+is required.
+
+## Let's encrypt
+
+Let's encrypt allows getting trusted wildcard certificates for free if you can
+use DNS validation.
+
+How to setup DNS validation will depend on the specifics of the DNS provider and
+ACME client.
+[This](https://community.letsencrypt.org/t/dns-providers-who-easily-integrate-with-lets-encrypt-dns-validation/86438)
+lists some DNS providers and supported ACME clients.
+
+## Self signed
+
+You can also create a self-signed wildcard certificate using a tool like
+`mkcert`. This certificate will not be trusted by your browser and tools like
+curl, but you can add manually add it to the trusted certificates on your
+system, or bypass the certficate warning in the browser/curl every time.
+
+```bash
+# Generate local wildcard certificate
+mkcert -cert-file <path-to-your-certificats>haze.example.com.crt -key-file <path-to-your-certificats>haze.example.com.key '*.haze.example.com'
+```
+
+## Using the certificate
+
+### Without reverse proxy
+
+The haze proxy can serve over https directly, to enable that add the following
+to the `[proxy]` section of your `haze.toml`.
+
+```toml
+https = true
+cert = "/path/to/haze.example.com.crt"
+key = "/path/to/haze.example.com.key"
+```
+
+You might also want to change the port it's listening on to `443`.
+
+### With a reverse proxy
+
+This depends on what reverse proxy you have setup. The following example is for
+`nginx`.
+
+```nginx
+upstream haze-handler {
+    server unix:/run/haze/haze.sock;
+}
+
+server {
+    listen 80;
+    listen 443 ssl;
+    http2 on;
+    server_name *.haze.example.com;
+
+    ssl_certificate     <path-to-your-certificats>/haze.example.com.crt;
+    ssl_certificate_key <path-to-your-certificats>/haze.example.com.key;
+
+    location / {
+            proxy_pass http://haze-handler;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```