From cf2d34f3c1ab1c6b06d0d6fa40ac8ccbd29a0cb2 Mon Sep 17 00:00:00 2001
From: Exaviz <info@exaviz.com>
Date: Wed, 1 Jul 2026 22:06:45 -0400
Subject: [PATCH] docs: add Caddy reverse-proxy example and proxy guide

Add examples/Caddyfile (automatic HTTPS + transparent WebSocket support)
and guides/reverse-proxy.md covering nginx, Caddy, and Traefik, with the
key gotchas: forwarding WebSockets for the transactor, and keeping SECURE +
HOST_ADDRESS consistent so Huly emits https/wss. Link the guide from README.

Addresses the recurring 'how to use Caddy' request (upstream huly-selfhost#82).
Caddyfile validated with 'caddy validate'.

Signed-off-by: Exaviz <info@exaviz.com>
---
 README.md               |  4 ++++
 examples/Caddyfile      | 18 ++++++++++++++++++
 guides/reverse-proxy.md | 38 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 60 insertions(+)
 create mode 100644 examples/Caddyfile
 create mode 100644 guides/reverse-proxy.md

diff --git a/README.md b/README.md
index 5aae414..2a2451b 100644
--- a/README.md
+++ b/README.md
@@ -146,6 +146,10 @@ sudo docker compose up -d
 
 Now, launch your web browser and enjoy Huly! To stop all services, run `docker compose down` from the `huly-selfhost` project directory.
 
+> [!TIP]
+> Prefer **Caddy** (automatic HTTPS) or **Traefik** instead of nginx? See
+> [`guides/reverse-proxy.md`](guides/reverse-proxy.md).
+
 > [!IMPORTANT]
 > Provided configrations include deployments of CockroachDB and Redpanda which might not be production-ready. Please inspect them carefully before using in production. For more information on the recommended deployment configurations, please refer to the [CockroachDB](https://www.cockroachlabs.com/docs/stable/recommended-production-settings) and [Redpanda](https://docs.redpanda.com/24.3/deploy/) documentation.
 
diff --git a/examples/Caddyfile b/examples/Caddyfile
new file mode 100644
index 0000000..70453c5
--- /dev/null
+++ b/examples/Caddyfile
@@ -0,0 +1,18 @@
+# Caddyfile - front Huly with automatic HTTPS (Let's Encrypt) and WebSocket support.
+#
+# 1. Point your domain's DNS at this host (ports 80 and 443 reachable).
+# 2. In huly.conf / .env set:
+#      HTTP_BIND=127.0.0.1
+#      HTTP_PORT=8087
+#      SECURE=true
+#      HOST_ADDRESS=huly.example.com
+#    so Huly emits https/wss URLs that match what Caddy serves.
+# 3. Replace huly.example.com and 8087 below, then run:  caddy run --config ./Caddyfile
+#
+# Caddy provisions and renews the TLS certificate automatically, and forwards WebSocket
+# upgrades and the X-Forwarded-* headers with no extra configuration (the Huly transactor
+# needs WebSockets).
+
+huly.example.com {
+	reverse_proxy 127.0.0.1:8087
+}
diff --git a/guides/reverse-proxy.md b/guides/reverse-proxy.md
new file mode 100644
index 0000000..499b085
--- /dev/null
+++ b/guides/reverse-proxy.md
@@ -0,0 +1,38 @@
+# Reverse proxy options
+
+Huly's `front` service is served on a single local port (`HTTP_PORT`, default `8087`), and
+the app uses **WebSockets** (the transactor). So any reverse proxy in front of it must
+forward WebSocket upgrades and the usual `X-Forwarded-*` headers, and Huly must be told it
+is behind TLS so it emits `https`/`wss` URLs.
+
+> [!IMPORTANT]
+> Keep Huly's config consistent with the proxy. When you terminate TLS at the proxy, set
+> `SECURE=true` and `HOST_ADDRESS=your-domain` in `huly.conf` / `.env`. A mismatch (proxy on
+> HTTPS while Huly still emits `http://` / `ws://`) is the usual cause of "Failed to fetch"
+> and WebSocket errors after the UI loads.
+
+## nginx (default)
+
+`./setup.sh` generates `nginx.conf`, and `./nginx.sh` keeps `server_name`, `listen`, and
+`proxy_pass` in sync with your config. See the main README for the full walk-through.
+
+## Caddy (automatic HTTPS)
+
+[`examples/Caddyfile`](../examples/Caddyfile) fronts Huly with automatic Let's Encrypt TLS
+and transparent WebSocket support - no manual certificates, no renewal cron:
+
+```caddy
+huly.example.com {
+    reverse_proxy 127.0.0.1:8087
+}
+```
+
+Set `HTTP_BIND=127.0.0.1`, `HTTP_PORT=8087`, `SECURE=true`, and `HOST_ADDRESS=huly.example.com`
+in your config, then run `caddy run --config ./Caddyfile` (or point your system Caddy at the
+file). Caddy handles certificate issuance/renewal and the WebSocket upgrade for you.
+
+## Traefik
+
+A sample Traefik setup lives under [`traefik/`](../traefik). As with the others, set
+`SECURE=true` and `HOST_ADDRESS` so Huly emits `https`/`wss`, and make sure the router
+forwards WebSockets to the `front` service.