docs(web-modeler): add configuration options for proxy servers and lo… (

#4467) * docs(web-modeler): add configuration options for proxy servers and log levels * apply the changes to corresponding versioned docs * address review hints * add proxy configuration to troubleshooting guide * address review hints * address review hint
camunda · Oct 24, 2024 · 402c77a · 402c77a
1 parent 4129dec
commit 402c77a
Show file tree

Hide file tree

Showing 14 changed files with 219 additions and 14 deletions.
diff --git a/docs/self-managed/modeler/web-modeler/configuration/configuration.md b/docs/self-managed/modeler/web-modeler/configuration/configuration.md
@@ -140,6 +140,20 @@ Refer to the [advanced SSL configuration guide](./ssl.md) for additional details
 | `RESTAPI_PORT`            | [Internal](#notes-on-host-names-and-port-numbers) port number on which the `restapi` serves the regular API endpoints.                 | `8081`                                                           | `8081`        |
 | `RESTAPI_MANAGEMENT_PORT` | [Internal](#notes-on-host-names-and-port-numbers) port number on which the `restapi` serves the management API endpoints.              | `8091`                                                           | `8091`        |
 
+### Proxy
+
+These settings are useful when the application needs to make outgoing network requests in environments that require traffic to pass through a proxy server.
+
+| Environment variable | Description                                                                                    | Example value                         | Default value |
+| -------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------- | ------------- |
+| `http_proxy`         | Specifies the proxy server to be used for outgoing HTTP requests.                              | `http://proxy.example.com:8080`       | -             |
+| `https_proxy`        | Specifies the proxy server to be used for outgoing HTTPS requests.                             | `https://secureproxy.example.com:443` | -             |
+| `no_proxy`           | A comma-separated list of domain names or IP addresses for which the proxy should be bypassed. | `localhost,127.0.0.1,.example.com`    | -             |
+
+:::note
+The proxy-related environment variables are lowercase because they follow a widely accepted convention used in many system environments and tools.
+:::
+
 ### Feature Flags
 
 | Environment variable            | Description                                                                                                                                                                                                                                                                 | Example value | Default value |
@@ -181,10 +195,13 @@ The `webapp` component sends certain events (e.g. "user opened diagram", "user l
 
 ### Logging
 
-| Environment variable | Description                            | Example value                |
-| -------------------- | -------------------------------------- | ---------------------------- |
-| `LOG_FILE_PATH`      | [optional]<br/>Path to log file output | `/full/path/to/log/file.log` |
+| Environment variable | Description                                     | Example value                |
+| -------------------- | ----------------------------------------------- | ---------------------------- |
+| `LOG_FILE_PATH`      | [optional]<br/>Path to log file output          | `/full/path/to/log/file.log` |
+| `LOG_LEVEL_CLIENT`   | [optional]<br/>Log level for the client         | `DEBUG`                      |
+| `LOG_LEVEL_WEBAPP`   | [optional]<br/>Log level for the Node.js server | `DEBUG`                      |
 
+The `LOG_LEVEL_*` options can be found [here](../../../operational-guides/troubleshooting/log-levels/#understanding-log-levels).
 Refer to the [Advanced Logging Configuration Guide](./logging.md#logging-configuration-for-the-webapp-component) for additional details on how to customize the `webapp` logging output.
 
 ### SSL

diff --git a/docs/self-managed/modeler/web-modeler/configuration/logging.md b/docs/self-managed/modeler/web-modeler/configuration/logging.md
@@ -38,6 +38,16 @@ To enable additional log output to a file, adjust the following environment vari
 LOG_FILE_PATH=/full/path/to/log/file.log
 ```
 
+### Configuring log levels
+
+To control the verbosity of the logs, adjust the environment variables `LOG_LEVEL_CLIENT` (browser client) and `LOG_LEVEL_WEBAPP` (Node.js server).
+
+```properties
+LOG_LEVEL_CLIENT=DEBUG
+```
+
+The `LOG_LEVEL_*` options can be found [here](../../../../operational-guides/troubleshooting/log-levels/#understanding-log-levels).
+
 ## Logging configuration for the `websocket` component
 
 By default, the `websocket` component logs to the Docker container's standard output.

diff --git a/...managed/modeler/web-modeler/troubleshooting/troubleshoot-proxy-configuration.md b/...managed/modeler/web-modeler/troubleshooting/troubleshoot-proxy-configuration.md
@@ -0,0 +1,36 @@
+---
+id: troubleshoot-proxy-configuration
+title: "Troubleshoot proxy configuration issues"
+sidebar_label: "Proxy configuration"
+description: "Troubleshooting guide for issues caused by incorrect proxy configuration in Web Modeler."
+---
+
+Troubleshoot and resolve issues in Web Modeler caused by incorrect or incomplete proxy configuration.
+
+## Issue
+
+Users experience a variety of failures when Web Modeler attempts to communicate with external services. These issues can manifest as:
+
+- Failed authentication due to the inability to access the JWKS (JSON Web Key Set) endpoint. Error message: "Expected 200 OK from the JSON Web Key Set HTTP response."
+- Failure to reach other external services, such as the Camunda Marketplace.
+
+## Cause
+
+Proxy settings must be correctly configured for Web Modeler to route outgoing requests through a network proxy. Common issues occur when:
+
+- The proxy server is not properly configured or unreachable.
+- Requests to external services are being blocked by the proxy configuration.
+- Authentication requests, such as those to the OIDC provider, fail when the JWKS endpoint is unreachable via the proxy.
+
+## Resolution
+
+Ensure correct proxy configuration for both `webapp` and `restapi` components.
+
+- For the `webapp` component, proxy configuration is handled via the environment variables `http_proxy`, `https_proxy` and `no_proxy`.
+  ```properties
+  http_proxy=http://proxy.example.com:8080 https_proxy=https://secureproxy.example.com:443 no_proxy=localhost,127.0.0.1,.example.com
+  ```
+- For the `restapi` component, the proxy configuration is handled via JVM settings passed as the value of the environment variable `JAVA_OPTS`.
+  ```properties
+  JAVA_OPTS=-Dhttp.proxyHost=<host> -Dhttps.proxyPort=<port>
+  ```
diff --git a/sidebars.js b/sidebars.js
@@ -1549,6 +1549,7 @@ module.exports = {
                     "self-managed/modeler/web-modeler/troubleshooting/troubleshoot-database-connection",
                     "self-managed/modeler/web-modeler/troubleshooting/troubleshoot-zeebe-connection",
                     "self-managed/modeler/web-modeler/troubleshooting/troubleshoot-missing-data",
+                    "self-managed/modeler/web-modeler/troubleshooting/troubleshoot-proxy-configuration",
                   ],
                 },
               ],

diff --git a/...ocs/version-8.4/self-managed/modeler/web-modeler/configuration/configuration.md b/...ocs/version-8.4/self-managed/modeler/web-modeler/configuration/configuration.md
@@ -144,10 +144,13 @@ The `webapp` component sends certain events (e.g. "user opened diagram", "user l
 
 ### Logging
 
-| Environment variable | Description                            | Example value                |
-| -------------------- | -------------------------------------- | ---------------------------- |
-| `LOG_FILE_PATH`      | [optional]<br/>Path to log file output | `/full/path/to/log/file.log` |
+| Environment variable | Description                                     | Example value                |
+| -------------------- | ----------------------------------------------- | ---------------------------- |
+| `LOG_FILE_PATH`      | [optional]<br/>Path to log file output          | `/full/path/to/log/file.log` |
+| `LOG_LEVEL_CLIENT`   | [optional]<br/>Log level for the client         | `DEBUG`                      |
+| `LOG_LEVEL_WEBAPP`   | [optional]<br/>Log level for the Node.js server | `DEBUG`                      |
 
+The `LOG_LEVEL_*` options can be found [here](../../../operational-guides/troubleshooting/log-levels/#understanding-log-levels).
 Refer to the [Advanced Logging Configuration Guide](./logging.md#logging-configuration-for-the-webapp-component) for additional details on how to customize the `webapp` logging output.
 
 ## Configuration of the `websocket` component

diff --git a/...oned_docs/version-8.4/self-managed/modeler/web-modeler/configuration/logging.md b/...oned_docs/version-8.4/self-managed/modeler/web-modeler/configuration/logging.md
@@ -42,6 +42,16 @@ To enable additional log output to a file, adjust the following environment vari
 LOG_FILE_PATH=/full/path/to/log/file.log
 ```
 
+### Configuring log levels
+
+To control the verbosity of the logs, adjust the environment variables `LOG_LEVEL_CLIENT` (browser client) and `LOG_LEVEL_WEBAPP` (Node.js server).
+
+```properties
+LOG_LEVEL_CLIENT=DEBUG
+```
+
+The `LOG_LEVEL_*` options can be found [here](../../../../operational-guides/troubleshooting/log-levels/#understanding-log-levels).
+
 ## Logging configuration for the `websocket` component
 
 By default, the `websocket` component logs to the Docker container's standard output.

diff --git a/...ocs/version-8.5/self-managed/modeler/web-modeler/configuration/configuration.md b/...ocs/version-8.5/self-managed/modeler/web-modeler/configuration/configuration.md
@@ -117,6 +117,20 @@ Refer to the [advanced SSL configuration guide](./ssl.md) for additional details
 | `RESTAPI_PORT`            | [Internal](#notes-on-host-names-and-port-numbers) port number on which the `restapi` serves the regular API endpoints.                 | `8081`                                                           | `8081`        |
 | `RESTAPI_MANAGEMENT_PORT` | [Internal](#notes-on-host-names-and-port-numbers) port number on which the `restapi` serves the management API endpoints.              | `8091`                                                           | `8091`        |
 
+### Proxy
+
+These settings are useful when the application needs to make outgoing network requests in environments that require traffic to pass through a proxy server.
+
+| Environment variable | Description                                                                                    | Example value                         | Default value |
+| -------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------- | ------------- |
+| `http_proxy`         | Specifies the proxy server to be used for outgoing HTTP requests.                              | `http://proxy.example.com:8080`       | -             |
+| `https_proxy`        | Specifies the proxy server to be used for outgoing HTTPS requests.                             | `https://secureproxy.example.com:443` | -             |
+| `no_proxy`           | A comma-separated list of domain names or IP addresses for which the proxy should be bypassed. | `localhost,127.0.0.1,.example.com`    | -             |
+
+:::note
+The proxy-related environment variables are lowercase because they follow a widely accepted convention used in many system environments and tools.
+:::
+
 ### Feature Flags
 
 | Environment variable            | Description                                                                                                                                                                                                                                                    | Example value | Default value |
@@ -158,10 +172,13 @@ The `webapp` component sends certain events (e.g. "user opened diagram", "user l
 
 ### Logging
 
-| Environment variable | Description                            | Example value                |
-| -------------------- | -------------------------------------- | ---------------------------- |
-| `LOG_FILE_PATH`      | [optional]<br/>Path to log file output | `/full/path/to/log/file.log` |
+| Environment variable | Description                                     | Example value                |
+| -------------------- | ----------------------------------------------- | ---------------------------- |
+| `LOG_FILE_PATH`      | [optional]<br/>Path to log file output          | `/full/path/to/log/file.log` |
+| `LOG_LEVEL_CLIENT`   | [optional]<br/>Log level for the client         | `DEBUG`                      |
+| `LOG_LEVEL_WEBAPP`   | [optional]<br/>Log level for the Node.js server | `DEBUG`                      |
 
+The `LOG_LEVEL_*` options can be found [here](../../../operational-guides/troubleshooting/log-levels/#understanding-log-levels).
 Refer to the [Advanced Logging Configuration Guide](./logging.md#logging-configuration-for-the-webapp-component) for additional details on how to customize the `webapp` logging output.
 
 ### SSL

diff --git a/...oned_docs/version-8.5/self-managed/modeler/web-modeler/configuration/logging.md b/...oned_docs/version-8.5/self-managed/modeler/web-modeler/configuration/logging.md
@@ -42,6 +42,16 @@ To enable additional log output to a file, adjust the following environment vari
 LOG_FILE_PATH=/full/path/to/log/file.log
 ```
 
+### Configuring log levels
+
+To control the verbosity of the logs, adjust the environment variables `LOG_LEVEL_CLIENT` (browser client) and `LOG_LEVEL_WEBAPP` (Node.js server).
+
+```properties
+LOG_LEVEL_CLIENT=DEBUG
+```
+
+The `LOG_LEVEL_*` options can be found [here](../../../../operational-guides/troubleshooting/log-levels/#understanding-log-levels).
+
 ## Logging configuration for the `websocket` component
 
 By default, the `websocket` component logs to the Docker container's standard output.

diff --git a/...managed/modeler/web-modeler/troubleshooting/troubleshoot-proxy-configuration.md b/...managed/modeler/web-modeler/troubleshooting/troubleshoot-proxy-configuration.md
@@ -0,0 +1,36 @@
+---
+id: troubleshoot-proxy-configuration
+title: "Troubleshoot proxy configuration issues"
+sidebar_label: "Proxy configuration"
+description: "Troubleshooting guide for issues caused by incorrect proxy configuration in Web Modeler."
+---
+
+Troubleshoot and resolve issues in Web Modeler caused by incorrect or incomplete proxy configuration.
+
+## Issue
+
+Users experience a variety of failures when Web Modeler attempts to communicate with external services. These issues can manifest as:
+
+- Failed authentication due to the inability to access the JWKS (JSON Web Key Set) endpoint. Error message: "Expected 200 OK from the JSON Web Key Set HTTP response."
+- Failure to reach other external services, such as the Camunda Marketplace.
+
+## Cause
+
+Proxy settings must be correctly configured for Web Modeler to route outgoing requests through a network proxy. Common issues occur when:
+
+- The proxy server is not properly configured or unreachable.
+- Requests to external services are being blocked by the proxy configuration.
+- Authentication requests, such as those to the OIDC provider, fail when the JWKS endpoint is unreachable via the proxy.
+
+## Resolution
+
+Ensure correct proxy configuration for both `webapp` and `restapi` components.
+
+- For the `webapp` component, proxy configuration is handled via the environment variables `http_proxy`, `https_proxy` and `no_proxy`.
+  ```properties
+  http_proxy=http://proxy.example.com:8080 https_proxy=https://secureproxy.example.com:443 no_proxy=localhost,127.0.0.1,.example.com
+  ```
+- For the `restapi` component, the proxy configuration is handled via JVM settings passed as the value of the environment variable `JAVA_OPTS`.
+  ```properties
+  JAVA_OPTS=-Dhttp.proxyHost=<host> -Dhttps.proxyPort=<port>
+  ```
diff --git a/...ocs/version-8.6/self-managed/modeler/web-modeler/configuration/configuration.md b/...ocs/version-8.6/self-managed/modeler/web-modeler/configuration/configuration.md
@@ -140,6 +140,20 @@ Refer to the [advanced SSL configuration guide](./ssl.md) for additional details
 | `RESTAPI_PORT`            | [Internal](#notes-on-host-names-and-port-numbers) port number on which the `restapi` serves the regular API endpoints.                 | `8081`                                                           | `8081`        |
 | `RESTAPI_MANAGEMENT_PORT` | [Internal](#notes-on-host-names-and-port-numbers) port number on which the `restapi` serves the management API endpoints.              | `8091`                                                           | `8091`        |
 
+### Proxy
+
+These settings are useful when the application needs to make outgoing network requests in environments that require traffic to pass through a proxy server.
+
+| Environment variable | Description                                                                                    | Example value                         | Default value |
+| -------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------- | ------------- |
+| `http_proxy`         | Specifies the proxy server to be used for outgoing HTTP requests.                              | `http://proxy.example.com:8080`       | -             |
+| `https_proxy`        | Specifies the proxy server to be used for outgoing HTTPS requests.                             | `https://secureproxy.example.com:443` | -             |
+| `no_proxy`           | A comma-separated list of domain names or IP addresses for which the proxy should be bypassed. | `localhost,127.0.0.1,.example.com`    | -             |
+
+:::note
+The proxy-related environment variables are lowercase because they follow a widely accepted convention used in many system environments and tools.
+:::
+
 ### Feature Flags
 
 | Environment variable            | Description                                                                                                                                                                                                                                                                 | Example value | Default value |
@@ -181,10 +195,13 @@ The `webapp` component sends certain events (e.g. "user opened diagram", "user l
 
 ### Logging
 
-| Environment variable | Description                            | Example value                |
-| -------------------- | -------------------------------------- | ---------------------------- |
-| `LOG_FILE_PATH`      | [optional]<br/>Path to log file output | `/full/path/to/log/file.log` |
+| Environment variable | Description                                     | Example value                |
+| -------------------- | ----------------------------------------------- | ---------------------------- |
+| `LOG_FILE_PATH`      | [optional]<br/>Path to log file output          | `/full/path/to/log/file.log` |
+| `LOG_LEVEL_CLIENT`   | [optional]<br/>Log level for the client         | `DEBUG`                      |
+| `LOG_LEVEL_WEBAPP`   | [optional]<br/>Log level for the Node.js server | `DEBUG`                      |
 
+The `LOG_LEVEL_*` options can be found [here](../../../operational-guides/troubleshooting/log-levels/#understanding-log-levels).
 Refer to the [Advanced Logging Configuration Guide](./logging.md#logging-configuration-for-the-webapp-component) for additional details on how to customize the `webapp` logging output.
 
 ### SSL

diff --git a/...oned_docs/version-8.6/self-managed/modeler/web-modeler/configuration/logging.md b/...oned_docs/version-8.6/self-managed/modeler/web-modeler/configuration/logging.md
@@ -38,6 +38,16 @@ To enable additional log output to a file, adjust the following environment vari
 LOG_FILE_PATH=/full/path/to/log/file.log
 ```
 
+### Configuring log levels
+
+To control the verbosity of the logs, adjust the environment variables `LOG_LEVEL_CLIENT` (browser client) and `LOG_LEVEL_WEBAPP` (Node.js server).
+
+```properties
+LOG_LEVEL_CLIENT=DEBUG
+```
+
+The `LOG_LEVEL_*` options can be found [here](../../../../operational-guides/troubleshooting/log-levels/#understanding-log-levels).
+
 ## Logging configuration for the `websocket` component
 
 By default, the `websocket` component logs to the Docker container's standard output.

diff --git a/...managed/modeler/web-modeler/troubleshooting/troubleshoot-proxy-configuration.md b/...managed/modeler/web-modeler/troubleshooting/troubleshoot-proxy-configuration.md
@@ -0,0 +1,36 @@
+---
+id: troubleshoot-proxy-configuration
+title: "Troubleshoot proxy configuration issues"
+sidebar_label: "Proxy configuration"
+description: "Troubleshooting guide for issues caused by incorrect proxy configuration in Web Modeler."
+---
+
+Troubleshoot and resolve issues in Web Modeler caused by incorrect or incomplete proxy configuration.
+
+## Issue
+
+Users experience a variety of failures when Web Modeler attempts to communicate with external services. These issues can manifest as:
+
+- Failed authentication due to the inability to access the JWKS (JSON Web Key Set) endpoint. Error message: "Expected 200 OK from the JSON Web Key Set HTTP response."
+- Failure to reach other external services, such as the Camunda Marketplace.
+
+## Cause
+
+Proxy settings must be correctly configured for Web Modeler to route outgoing requests through a network proxy. Common issues occur when:
+
+- The proxy server is not properly configured or unreachable.
+- Requests to external services are being blocked by the proxy configuration.
+- Authentication requests, such as those to the OIDC provider, fail when the JWKS endpoint is unreachable via the proxy.
+
+## Resolution
+
+Ensure correct proxy configuration for both `webapp` and `restapi` components.
+
+- For the `webapp` component, proxy configuration is handled via the environment variables `http_proxy`, `https_proxy` and `no_proxy`.
+  ```properties
+  http_proxy=http://proxy.example.com:8080 https_proxy=https://secureproxy.example.com:443 no_proxy=localhost,127.0.0.1,.example.com
+  ```
+- For the `restapi` component, the proxy configuration is handled via JVM settings passed as the value of the environment variable `JAVA_OPTS`.
+  ```properties
+  JAVA_OPTS=-Dhttp.proxyHost=<host> -Dhttps.proxyPort=<port>
+  ```