[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.