From 90e840c3c93cae2c0ac133eb1cf67d637946fa02 Mon Sep 17 00:00:00 2001
From: Mike Lloyd <mike.lloyd03@pm.me>
Date: Sun, 4 Sep 2022 09:42:23 -0700
Subject: [PATCH] Add reverse proxy documentation

---
 docs/README.md        |  1 +
 docs/reverse-proxy.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 docs/reverse-proxy.md

diff --git a/docs/README.md b/docs/README.md
index 9f8e681a..dfad6116 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -28,6 +28,7 @@ written by community members. It is _not_ verified by `headscale` developers.
 
 - [Running headscale in a container](running-headscale-container.md)
 - [Running headscale on OpenBSD](running-headscale-openbsd.md)
+- [Running headscale behind a reverse proxy](reverse-proxy.md)
 
 ## Misc
 
diff --git a/docs/reverse-proxy.md b/docs/reverse-proxy.md
new file mode 100644
index 00000000..c9a1d1b7
--- /dev/null
+++ b/docs/reverse-proxy.md
@@ -0,0 +1,43 @@
+# Running behind a reverse proxy
+
+Running Headscale behind a reverse proxy is suitable for container-based deployments. This is especially useful on a server were port 443 is already being used for other web services.
+
+Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration values to your headscale config file.
+
+```yaml
+server_url: https://<YOUR_SERVER_NAME> # This should be the FQDN at which headscale will be served
+listen_addr: 0.0.0.0:8080
+metrics_listen_addr: 0.0.0.0:9090
+tls_cert_path: ""
+tls_key_path: ""
+```
+
+## nginx
+The following example configuration can be used in your nginx setup, substituting values as necessary. `<IP:PORT>` should be the IP address and port where headscale is running. In most cases, this will be `http://localhost:8080`.
+
+```Nginx
+server {
+    listen 80;
+	listen [::]:80;
+
+	listen 443      ssl http2;
+	listen [::]:443 ssl http2;
+
+    server_name <YOUR_SERVER_NAME>;
+
+    ssl_certificate <PATH_TO_CERT>;
+    ssl_certificate_key <PATH_CERT_KEY>;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    location / {
+        proxy_pass http://<IP:PORT>;
+        proxy_set_header Host $server_name;
+        proxy_redirect http:// https://;
+        proxy_buffering off;
+        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 $http_x_forwarded_proto;
+        add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
+    }
+}
+```