From eb4a7387466d7c9011c4662766fc17014f320ce2 Mon Sep 17 00:00:00 2001
From: Jason Kulatunga <jason@thesparktree.com>
Date: Mon, 9 May 2022 16:37:05 -0700
Subject: [PATCH] documentation & updates for configuring scrutiny behind a
 reverse proxy with path rewriting.

---
 README.md                                     |  2 +-
 .../collector-metrics/collector-metrics.go    |  3 +-
 .../collector-selftest/collector-selftest.go  |  2 +-
 docs/TROUBLESHOOTING_REVERSE_PROXY.md         | 58 +++++++++++++++++++
 example.collector.yaml                        |  4 ++
 5 files changed, 66 insertions(+), 3 deletions(-)
 create mode 100644 docs/TROUBLESHOOTING_REVERSE_PROXY.md

diff --git a/README.md b/README.md
index 2bebda4..af4d1f3 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ docker run --rm \
   --cap-add SYS_RAWIO \
   --device=/dev/sda \
   --device=/dev/sdb \
-  -e SCRUTINY_API_ENDPOINT=http://SCRUTINY_WEB_IPADDRESS:8080 \
+  -e COLLECTOR_API_ENDPOINT=http://SCRUTINY_WEB_IPADDRESS:8080 \
   --name scrutiny-collector \
   ghcr.io/analogj/scrutiny:master-collector
 ```
diff --git a/collector/cmd/collector-metrics/collector-metrics.go b/collector/cmd/collector-metrics/collector-metrics.go
index 14782e0..a170f16 100644
--- a/collector/cmd/collector-metrics/collector-metrics.go
+++ b/collector/cmd/collector-metrics/collector-metrics.go
@@ -161,7 +161,8 @@ OPTIONS:
 					&cli.StringFlag{
 						Name:    "api-endpoint",
 						Usage:   "The api server endpoint",
-						EnvVars: []string{"SCRUTINY_API_ENDPOINT"},
+						EnvVars: []string{"COLLECTOR_API_ENDPOINT", "SCRUTINY_API_ENDPOINT"},
+						//SCRUTINY_API_ENDPOINT is deprecated, but kept for backwards compatibility
 					},
 
 					&cli.StringFlag{
diff --git a/collector/cmd/collector-selftest/collector-selftest.go b/collector/cmd/collector-selftest/collector-selftest.go
index a603b4a..ac2e2fa 100644
--- a/collector/cmd/collector-selftest/collector-selftest.go
+++ b/collector/cmd/collector-selftest/collector-selftest.go
@@ -114,7 +114,7 @@ OPTIONS:
 						Name:    "api-endpoint",
 						Usage:   "The api server endpoint",
 						Value:   "http://localhost:8080",
-						EnvVars: []string{"SCRUTINY_API_ENDPOINT"},
+						EnvVars: []string{"COLLECTOR_API_ENDPOINT"},
 					},
 
 					&cli.StringFlag{
diff --git a/docs/TROUBLESHOOTING_REVERSE_PROXY.md b/docs/TROUBLESHOOTING_REVERSE_PROXY.md
new file mode 100644
index 0000000..667f31e
--- /dev/null
+++ b/docs/TROUBLESHOOTING_REVERSE_PROXY.md
@@ -0,0 +1,58 @@
+# Reverse Proxy Support
+
+Scrutiny is designed so that it can be used with a reverse proxy, leveraging `domain`, `port` or `path` based matching to correctly route to the Scrutiny service.
+
+For simple `domain` and/or `port` based routing, this is easy.
+
+If your domain:port pair is similar to `http://scrutiny.example.com` or `http://localhost:54321`, just update your reverse proxy configuration
+to route traffic to the Scrutiny backend, which is listening on `0.0.0.0:8080` by default.
+
+```yaml
+# default config
+web:
+  listen:
+    port: 8080
+    host: 0.0.0.0
+```
+
+However if you're using `path` based routing to differentiate your reverse proxy protected services, things become more complicated.
+
+If you'd like to access Scrutiny using a path like: `http://example.com/scrutiny/`, then we need a way to configure Scrutiny so that it
+understands `http://example.com/scrutiny/api/health` actually means `http://localhost:8080/api/health`.
+
+Thankfully this can be done by changing **two** settings. 
+
+1. The webserver has a `web.listen.basepath` key
+2. The collectors have a `api.endpoint` key.
+
+## Webserver Configuration
+
+When setting the `web.listen.basepath` key in the web config file, make sure the `basepath` key is prefixed with `/`.
+
+```yaml
+# customized webserver config
+web:
+  listen:
+    port: 8080
+    host: 0.0.0.0
+    # if you're using a reverse proxy like apache/nginx, you can override this value to serve scrutiny on a subpath.
+    # eg. http://example.com/custombasepath/* vs http://example.com:8080
+    basepath: '/custombasepath'
+```
+
+## Collector Configuration 
+
+Here's how you can update the collector `api.endpoint` key:
+
+```yaml
+# customized collector config
+api:
+  endpoint: 'http://localhost:8080/custombasepath'
+```
+
+# Environmental Variables.
+
+You may also configure these values using the following environmental variables
+
+- `COLLECTOR_API_ENDPOINT=http://localhost:8080/custombasepath`
+- `SCRUTINY_WEB_LISTEN_BASEPATH=/custombasepath`
\ No newline at end of file
diff --git a/example.collector.yaml b/example.collector.yaml
index 113aebf..008927d 100644
--- a/example.collector.yaml
+++ b/example.collector.yaml
@@ -60,6 +60,10 @@ devices:
 #
 #api:
 #  endpoint: 'http://localhost:8080'
+#  endpoint: 'http://localhost:8080/custombasepath'
+# if you need to use a custom base path (for a reverse proxy), you can add a suffix to the endpoint.
+#  See docs/TROUBLESHOOTING_REVERSE_PROXY.md for more info,
+
 
 ########################################################################################################################
 # FEATURES COMING SOON