From 559c2c81bceb56e44695de7f56ef587ecbeaa620 Mon Sep 17 00:00:00 2001
From: Christopher Bisset <chris@gurucomputing.com.au>
Date: Wed, 27 Jul 2022 18:27:33 +1000
Subject: [PATCH] additional documentation

---
 README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 72 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 26c11bf..1a6a8d0 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,80 @@
 A web frontend for the [headscale](https://github.com/juanfont/headscale) Tailscale-compatible coordination server.
 
 ## Installation
-Headscale-UI is designed to compile to a vanilla SPA that can be statically hosted on any site. Just take the latest build and host using a file server such as [caddy](https://caddyserver.com/), [apache httpd](https://httpd.apache.org/) or [nginx](https://www.nginx.com/). A sample Caddyfile is provided for self signed TLS certificates, and can be easily adjusted to proper HTTPS hosting.
+Headscale-UI is currently released as a static site: just take the release and host with your favorite web server. Headscale-UI expects to be served from the `/web` path to avoid overlap with headscale on the same domain.
 
-While not currently embedded into the headscale binary, there is no reason why the compiled files couldn't be embedded in the future.
+### Docker Installation
+If you are using docker, you can install `headscale` alongside `headscale-ui`, like so:
 
-> :warning: Headscale (not headscale-ui) requires special configuration to provide CORS headers for headscale-ui to operate. See [This Github Issue](https://github.com/juanfont/headscale/issues/623) for details
+```yaml
+version: '3.5'
+services:
+  headscale:
+    image: headscale/headscale:latest-alpine
+    container_name: headscale
+    volumes:
+      - ./container-config:/etc/headscale
+      - ./container-data/data:/var/lib/headscale
+    # ports:
+      # - 27896:8080
+    command: headscale serve
+    restart: unless-stopped
+  headscale-ui:
+    image: ghcr.io/gurucomputing/headscale-ui:latest
+    container_name: headscale-ui
+    security_opt:
+      - label:disable
+    networks:
+      - reverseproxy-nw
+    # ports:
+      # - 9443:443
+```
+
+Headscale UI serves on port 443 and uses a self signed cert by default.
+
+### Proxy Settings
+You will need a reverse proxy to install `headscale-ui` on the your domain. Here is an example [Caddy Config](https://caddyserver.com/) to achieve this:
+```
+https://hs.yourdomain.com.au {
+	reverse_proxy /web* https://headscale-ui {
+		transport http {
+			tls_insecure_skip_verify
+		}
+	}
+
+	reverse_proxy * http://headscale:8080
+}
+
+```
+
+### Cross Domain Installation
+If you do not want to configure headscale-ui on the same subdomain as headscale, you must intercept headscale traffic via your reverse proxy to fix CORS (see https://github.com/juanfont/headscale/issues/623). Here is an example fix with Caddy:
+```
+hs.yourdomain.com.au {
+  @hs-options {
+    host hs.gurucomputing.com.au
+    method OPTIONS
+  }
+  @hs-other {
+    host hs.gurucomputing.com.au
+  }
+  handle @hs-options {
+    header {
+      Access-Control-Allow-Origin https://hs-ui.yourdomain.au
+      Access-Control-Allow-Headers *
+      Access-Control-Allow-Methods "POST, GET, OPTIONS, DELETE"
+    }
+    respond 204
+  }
+  handle @hs-other {
+    reverse_proxy http://headscale:8080 {
+      header_down Access-Control-Allow-Origin https://hs-ui.yourdomain.com.au
+      header_down Access-Control-Allow-Methods "POST, GET, OPTIONS, DELETE"
+      header_down Access-Control-Allow-Headers *
+    }
+  }
+}
+```
 
 ## Development
 Development can be done either by using the official development docker image, or via a normal nodejs installation.