From b18fc66c1afe0fde49836174b68dd185f7e851f2 Mon Sep 17 00:00:00 2001 From: Thomas Belin Date: Thu, 7 Sep 2023 09:26:23 +0200 Subject: [PATCH 1/4] doc: Add documentation about webapp config for multi-ingress envs --- .../src/developer/reference/config-options.md | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/src/developer/reference/config-options.md b/docs/src/developer/reference/config-options.md index 3d9dc14c4f4..b602f768dac 100644 --- a/docs/src/developer/reference/config-options.md +++ b/docs/src/developer/reference/config-options.md @@ -764,4 +764,35 @@ Example: multiIngress: red.example.com: https://accounts.red.example.com/conversation-join/ green.example.com: https://accounts.green.example.net/conversation-join/ -``` \ No newline at end of file +``` + +### Webapp + +In order to completely hide the root domain to the webapp, some environment variable need to be set. They will allow the webapp hostname to be used to generate the API endpoint, team settings links, account page links and CSP headers. + +To enable dynamic hostname replacement, first set this variable: + +``` +ENABLE_DYNAMIC_HOSTNAME="true" +``` + +Then any other variable that will contain the string `[[hostname]]` will then be replaced by the hostname of the running webapp. (eg. if a webapp is running on `webapp.red.example.com` then any occurence of `[[hostname]]` in the config will be replaced by `red.example.com`). + +You may then add this `[[hostname]]` in any environment variable + +``` +APP_BASE: https://[[hostname]] +BACKEND_REST: https://nginz-https.[[hostname]] +BACKEND_WS: wss://nginz-ssl.[[hostname]] +CSP_EXTRA_CONNECT_SRC: https://*.[[hostname]], wss://*.[[hostname]] +CSP_EXTRA_DEFAULT_SRC: https://*.[[hostname]] +CSP_EXTRA_FONT_SRC: https://*.[[hostname]] +CSP_EXTRA_FRAME_SRC: https://*.[[hostname]] +CSP_EXTRA_IMG_SRC: https://*.[[hostname]] +CSP_EXTRA_MANIFEST_SRC: https://*.[[hostname]] +CSP_EXTRA_MEDIA_SRC: https://*.[[hostname]] +CSP_EXTRA_PREFETCH_SRC: https://*.[[hostname]] +CSP_EXTRA_SCRIPT_SRC: https://*.[[hostname]] +CSP_EXTRA_STYLE_SRC: https://*.[[hostname]] +CSP_EXTRA_WORKER_SRC: https://*.[[hostname]] +``` From e9fba92472ef1bb95b5bf1906acc861932adb26e Mon Sep 17 00:00:00 2001 From: Thomas Belin Date: Thu, 7 Sep 2023 10:26:36 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Sven Tennie --- docs/src/developer/reference/config-options.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/src/developer/reference/config-options.md b/docs/src/developer/reference/config-options.md index b602f768dac..7c5666f9fa2 100644 --- a/docs/src/developer/reference/config-options.md +++ b/docs/src/developer/reference/config-options.md @@ -768,7 +768,7 @@ multiIngress: ### Webapp -In order to completely hide the root domain to the webapp, some environment variable need to be set. They will allow the webapp hostname to be used to generate the API endpoint, team settings links, account page links and CSP headers. +In order to completely hide the root domain to the webapp, some environment variables need to be set. They will allow the webapp hostname to be used to generate the API endpoint, team settings links, account page links and CSP headers. To enable dynamic hostname replacement, first set this variable: @@ -776,9 +776,11 @@ To enable dynamic hostname replacement, first set this variable: ENABLE_DYNAMIC_HOSTNAME="true" ``` -Then any other variable that will contain the string `[[hostname]]` will then be replaced by the hostname of the running webapp. (eg. if a webapp is running on `webapp.red.example.com` then any occurence of `[[hostname]]` in the config will be replaced by `red.example.com`). +Then, any other variable that will contain the string `[[hostname]]` will be replaced by the hostname of the running webapp. (eg. if a webapp is running on `webapp.red.example.com` then any occurrence of `[[hostname]]` in the config will be replaced by `red.example.com`). -You may then add this `[[hostname]]` in any environment variable +You may use the template variable `[[hostname]]` in any environment variable to not provide (reveal) actual domain names. + +For example: ``` APP_BASE: https://[[hostname]] From b7a85db9e0ac193ff9805f7334fad31114db1a12 Mon Sep 17 00:00:00 2001 From: Thomas Belin Date: Thu, 7 Sep 2023 15:18:17 +0200 Subject: [PATCH 3/4] doc: Add explanation on the webapp's config architecture --- docs/src/developer/reference/config-options.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/src/developer/reference/config-options.md b/docs/src/developer/reference/config-options.md index 7c5666f9fa2..4c09cb5f9bc 100644 --- a/docs/src/developer/reference/config-options.md +++ b/docs/src/developer/reference/config-options.md @@ -768,7 +768,15 @@ multiIngress: ### Webapp -In order to completely hide the root domain to the webapp, some environment variables need to be set. They will allow the webapp hostname to be used to generate the API endpoint, team settings links, account page links and CSP headers. +The webapp runs its own web server (a NodeJS server) to serve static files and the webapp config (based on environment variables). +In an multi-ingress configuration, a single webapp instance will be deployed and be accessible from multiple domains (say `webapp.red.example.com` and `webapp.green.example.com`). +When the webapp is loaded from one of those domains it first does a request to the web server to get the config (that will give it, for example, the backend endpoint that it should hit). + +Because of the single instance nature of the webapp, by default the configuration is static and the root url to the backend API can be set there (say `nginz-https.root.example.com`). +In order to completely hide this root domain to the webapp, an environment variable can be set to allow the webapp hostname to be used to generate the API endpoint, team settings links, account page links and CSP headers. + +The "hostname" is the result of the domain name minus the `webapp.` part of it. +So querying the webapp on `webapp.red.example.com` will resolve to `red.example.com`. To enable dynamic hostname replacement, first set this variable: From c7274ff2d57ab18db17cf42e5bb0778db2609562 Mon Sep 17 00:00:00 2001 From: Thomas Belin Date: Thu, 7 Sep 2023 15:40:55 +0200 Subject: [PATCH 4/4] Update docs/src/developer/reference/config-options.md Co-authored-by: Sven Tennie --- docs/src/developer/reference/config-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/developer/reference/config-options.md b/docs/src/developer/reference/config-options.md index 4c09cb5f9bc..d92d461479b 100644 --- a/docs/src/developer/reference/config-options.md +++ b/docs/src/developer/reference/config-options.md @@ -769,7 +769,7 @@ multiIngress: ### Webapp The webapp runs its own web server (a NodeJS server) to serve static files and the webapp config (based on environment variables). -In an multi-ingress configuration, a single webapp instance will be deployed and be accessible from multiple domains (say `webapp.red.example.com` and `webapp.green.example.com`). +In a multi-ingress configuration, a single webapp instance will be deployed and be accessible from multiple domains (say `webapp.red.example.com` and `webapp.green.example.com`). When the webapp is loaded from one of those domains it first does a request to the web server to get the config (that will give it, for example, the backend endpoint that it should hit). Because of the single instance nature of the webapp, by default the configuration is static and the root url to the backend API can be set there (say `nginz-https.root.example.com`).