From 7dafac8b8737bbb7809ba76ccb1474b0af9816f7 Mon Sep 17 00:00:00 2001
From: Nicolas Duchon <nicolas.duchon@gmail.com>
Date: Thu, 17 Oct 2024 08:13:11 +0200
Subject: [PATCH] docs: documentation for debug endpoint

---
 docs/README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 1 deletion(-)

diff --git a/docs/README.md b/docs/README.md
index 3990a7a..fbfe1e2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -982,7 +982,7 @@ docker exec <nginx-proxy-instance> nginx -T
 
 Pay attention to the `upstream` definition blocks, which should look like this:
 
-```Nginx
+```nginx
 # foo.example.com
 upstream foo.example.com {
 	## Can be connected with "my_network" network
@@ -1002,6 +1002,101 @@ The effective `Port` is retrieved by order of precedence:
 1. From the container's exposed port if there is only one
 1. From the default port 80 when none of the above methods apply
 
+### Debug endpoint
+
+The debug endpoint can be enabled:
+- globally by setting the `DEBUG_ENDPOINT` environment variable to `true` on the nginx-proxy container.
+- per container by setting the `com.github.nginx-proxy.nginx-proxy.debug-endpoint` label to `true` on a proxied container.
+
+Enabling it will expose the endpoint at `<your.domain.tld>/nginx-proxy-debug`.
+
+Querying the debug endpoint will show the global config, along with the virtual host and per path configs in JSON format.
+
+```yaml
+services:
+  nginx-proxy:
+    image: nginxproxy/nginx-proxy
+    ports:
+      - "80:80"
+    volumes:
+      - /var/run/docker.sock:/tmp/docker.sock:ro
+    environment:
+      DEBUG_ENDPOINT: "true"
+
+  test:
+    image: nginx
+    environment:
+      VIRTUAL_HOST: test.nginx-proxy.tld
+```
+
+(on the CLI, using [`jq`](https://jqlang.github.io/jq/) to format the output of `curl` is recommended)
+
+```console
+curl -s -H "Host: test.nginx-proxy.tld" localhost/nginx-proxy-debug | jq
+```
+
+```json
+{
+  "global": {
+    "default_cert_ok": false,
+    "default_root_response": "404",
+    "enable_access_log": true,
+    "enable_debug_endpoint": "true",
+    "enable_ipv6": false,
+    "external_http_port": "80",
+    "external_https_port": "443",
+    "nginx_proxy_version": "local",
+    "sha1_upstream_name": false,
+    "ssl_policy": "Mozilla-Intermediate",
+    "trust_downstream_proxy": true
+  },
+  "hostname": "test.nginx-proxy.tld",
+  "request": {
+    "host": "test.nginx-proxy.tld",
+    "http2": "",
+    "http3": "",
+    "https": "",
+    "ssl_cipher": "",
+    "ssl_protocol": ""
+  },
+  "vhost": {
+    "acme_http_challenge_enabled": true,
+    "acme_http_challenge_legacy": false,
+    "cert": "",
+    "cert_ok": false,
+    "default": false,
+    "enable_debug_endpoint": true,
+    "hsts": "max-age=31536000",
+    "http2_enabled": true,
+    "http3_enabled": false,
+    "https_method": "noredirect",
+    "paths": {
+      "/": {
+        "dest": "",
+        "keepalive": "disabled",
+        "network_tag": "external",
+        "ports": {
+          "legacy": [
+            {
+              "Name": "wip-test-1"
+            }
+          ]
+        },
+        "proto": "http",
+        "upstream": "test.nginx-proxy.tld"
+      }
+    },
+    "server_tokens": "",
+    "ssl_policy": "",
+    "upstream_name": "test.nginx-proxy.tld",
+    "vhost_root": "/var/www/public"
+  }
+}
+```
+
+:warning: please be aware that the debug endpoint work by rendering the response straight to the nginx configuration, which might result in an unparseable configuration if it exceeds nginx line character limit. Only activate it when needed.
+
+
 ⬆️ [back to table of contents](#table-of-contents)
 
 ## Contributing