From 14f95852cbd29d0a565f3ca29f1583df26334f73 Mon Sep 17 00:00:00 2001 From: Benno Evers Date: Tue, 3 Mar 2026 12:11:47 +0000 Subject: [PATCH] docs: document gateway CORS config and browser certificate trust Add CORS_ALLOWED_ORIGINS documentation for the Tenzir Gateway service, needed when the UI frontend connects directly to the gateway from a different origin (e.g. different port or domain). Add a caution note in the self-signed certificates section explaining that when the browser connects directly to the gateway, it must explicitly trust the gateway certificate. The failure mode is subtle: the UI shows only a vague "Unable to fetch pipelines" message because the browser never navigates to the gateway port directly and therefore never displays the normal untrusted-certificate warning page. https://claude.ai/code/session_01GgSV84jmGtMoBNGDnYzWse --- .../configure-internal-services.mdx | 20 ++++++++++++++++++- .../configure-reverse-proxy.mdx | 19 ++++++++++++++++++ 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/src/content/docs/guides/platform-setup/configure-internal-services.mdx b/src/content/docs/guides/platform-setup/configure-internal-services.mdx index ac1763019..c3b40f7b1 100644 --- a/src/content/docs/guides/platform-setup/configure-internal-services.mdx +++ b/src/content/docs/guides/platform-setup/configure-internal-services.mdx @@ -152,4 +152,22 @@ in the identity provider configuration guide. ## Tenzir Gateway -The Tenzir Gateway doesn't offer any user-controlled settings at the moment. +### CORS + +When the Tenzir UI frontend connects directly to the Tenzir Gateway from the +browser—the default when `TENZIR_PLATFORM_USE_INTERNAL_WS_PROXY` is `false`— +and the UI and gateway are served from different origins (for example, on +different ports or domains), the browser enforces Cross-Origin Resource Sharing +(CORS) restrictions. You must explicitly allow the UI's origin by setting +`CORS_ALLOWED_ORIGINS` on the `websocket-gateway` service in your +`docker-compose.yaml`: + +```yaml +services: + websocket-gateway: + environment: + - CORS_ALLOWED_ORIGINS=https://app.platform.example:3000 +``` + +Specify the full origin including scheme and port. Separate multiple allowed +origins with commas. diff --git a/src/content/docs/guides/platform-setup/configure-reverse-proxy.mdx b/src/content/docs/guides/platform-setup/configure-reverse-proxy.mdx index e5d56c73d..90e8593b1 100644 --- a/src/content/docs/guides/platform-setup/configure-reverse-proxy.mdx +++ b/src/content/docs/guides/platform-setup/configure-reverse-proxy.mdx @@ -157,6 +157,25 @@ services: - ./ssl/ca.pem:/ssl/ca.pem ``` +:::caution[Browser certificate trust for direct gateway connections] +When the browser connects directly to the gateway (the default when +`TENZIR_PLATFORM_USE_INTERNAL_WS_PROXY` is `false`) and the gateway uses a +self-signed certificate, the browser must explicitly trust that certificate. +Because users do not navigate to the gateway port directly, the browser never +shows its usual untrusted-certificate warning page. The only visible symptom is +a vague message such as "Unable to fetch pipelines." The actual cause appears +only in the browser developer console, where it shows a failed connection to the +gateway URL. + +To resolve this, open the gateway URL directly in your browser (for example, +`https://nodes.platform.example`) and accept the security exception. After +accepting the certificate, reload the platform UI. + +Alternatively, set `TENZIR_PLATFORM_USE_INTERNAL_WS_PROXY=true` to route +gateway traffic through the UI backend. The browser then only needs to trust +the UI certificate, not the gateway certificate. +::: + #### Platform API To enable TLS serving for the Platform API, mount the certificate into the