[wip] port readme contents over to an mdbook

book/src/proxy/README.md

@@ -0,0 +1,91 @@
+# Proxy
+
+By default, instances can be accessed by their IP. In order to get more
+memorable URLs and allow supporting https. haze comes with a builtin reverse
+proxy to allow using a wildcard domain.
+
+## Setup
+
+- [Setup a DNS record](./dns.html) for `*.haze.example.com` and
+  `haze.example.com` pointing to your development machine.
+- Set the `proxy` configuration with your domain and desired listen endpoint.
+- Set up a service to run `haze proxy` in the background as your own user. A
+  systemd user service is recommended (see
+  [haze.service](<[./haze.service](https://codeberg.org/icewind/haze/src/branch/main/haze.service)>)
+  for an example).
+- If you're already running a reverse proxy, configure your reverse proxy of
+  choice to proxy `*.haze.example.com` and `haze.example.com` to the proxy's
+  listen endpoint.
+- (Optionally) [setup https](./https.html) for the proxy.
+
+### Configuration
+
+Add the following configuration to the `haze.toml` config file:
+
+```toml
+[proxy]
+address = "haze.example.com" # the base domain for the proxy to use
+listen = "127.0.0.1:8080" # the port+ip to listen on
+# listen = "/var/run/haze/haze.sock" # or a unix socket path
+```
+
+### Without a reverse proxy
+
+If you have no other http(s) servers on your development machine, you can setup
+things without a reverse proxy.
+
+Simply configure the proxy to listen on port `80` (or `443` when using http).
+
+Binding to port 80 or443 as a regular user requires either giving the haze
+binary the `net_bind_service` capability with
+`sudo setcap cap_net_bind_service=+ep $(which haze)` (this will have to be done
+every time your upgrade haze) or configure your system to allow unpriviled users
+to bind on the low port numbers. Using
+`sysctl net.ipv4.ip_unprivileged_port_start=80` and writing
+
+```
+net.ipv4.ip_unprivileged_port_start=80
+```
+
+to `/etc/sysctl.d/bind.conf` to make it persistent across reboot.
+
+### With a reverse proxy
+
+If you're already have other http(s) services listening on your machine, you'll
+probably want to setup a reverse proxy to allow them to all be served on your
+machine.
+
+The setup for this will depend on your reverse proxy of the choice, the
+following example config is for `nginx`.
+
+```nginx
+upstream haze-handler {
+    server unix:/var/run/haze/haze.sock;
+}
+
+server {
+    listen 80;
+    server_name *.haze.example.com;
+
+    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;
+    }
+}
+```
+
+## Usage
+
+When the proxy is configured, generated URLs for the instances will use a
+subdomain of the configured domain, e.g. the `rolling-bees` instance will be
+available at `rolling-bees.haze.example.com`. Additionally, `haze.example.com`
+will automatically point to the last created instance.
+
+Additionally, the proxy allows access to the service containers trough either
+`<instance id>-<service id>.haze.example.com` for a specific instance, or
+`<service-id>.haze.example.com` for the last created instance. For example
+`rolling-bees-mail.haze.example.com` will give access to the smtp4dev web
+interface of the `rolling-bees` instance.

book/src/proxy/dns.md

@@ -0,0 +1,27 @@
+# DNS
+
+Since the domain name used for the instance is dynamic, a wildcard dns record is
+required.
+
+## With your domain's DNS provider
+
+If you own a domain you would like to use, you can create a wildcard domain
+withing the DNS settings of your DNS provider. For example creating a record an
+`A` record for `*.haze.example.com` with a value of `127.0.0.1` and a similar
+one for `haze.example.com`.
+
+## With a local dnsmasq
+
+If you do not own a "real" domain for using with haze, you can setup `dnsmasq`
+locally to achieve the same goal instead.
+
+How to install and enable `dnsmasq` will depend on your distro of choice and
+should be documented by it's documentation.
+
+Once setup, a configuration line like
+
+```
+address=/haze.local/172.0.0.1
+```
+
+should be enough to point `haze.local` and `*.haze.local` to your local host.

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;
+    }
+}
+```