Skip to content

Commit

Permalink
feat(self-managed/console): describe tls config (#4317)
Browse files Browse the repository at this point in the history 
* feat(self-managed/console): describe tls config

* style(formatting): grammatical adjustments

* update application config links to point to correct version

* Restructure content

---------

Co-authored-by: Christina Ausley <[email protected]>
Co-authored-by: Cole Garbo <[email protected]>
  • Loading branch information
@urbanisierung @christinaausley @conceptualshark
3 people authored Dec 16, 2024
1 parent f8726b7 commit 16e5145
Show file tree
Hide file tree
Showing 6 changed files with 99 additions and 33 deletions.
38 changes: 23 additions & 15 deletions ...naged/console-deployment/configuration.md → ...deployment/configuration/configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: configuration
title: "Configuration"
sidebar_label: "Configuration"
title: "Console configuration"
sidebar_label: "Overview"
description: "Read details on the configuration variables of Console Self-Managed."
---

Expand All @@ -13,19 +13,27 @@ Underscores in environment variables correspond to configuration file key levels

## Environment variables

| Environment variable | Description | Example value |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `KEYCLOAK_BASE_URL` | Base URL for Keycloak | https://example.com/auth |
| `KEYCLOAK_INTERNAL_BASE_URL` | Internal Base URL for Keycloak | http://camunda-platform-keycloak:80/auth |
| `KEYCLOAK_REALM` | Realm for Keycloak | camunda-platform |
| `CAMUNDA_IDENTITY_AUDIENCE` | Audience for Console client | console |
| `CAMUNDA_IDENTITY_CLIENT_ID` | Client ID for Console client | console |
| `CAMUNDA_CONSOLE_CONTEXT_PATH` | Context path for Console | console |
| `CAMUNDA_CONSOLE_CUSTOMERID` | Unique identifier of the customer | `customer-id` |
| `CAMUNDA_CONSOLE_INSTALLATIONID` | Unique installation ID of the current customer installation | `installation-id` |
| `CAMUNDA_CONSOLE_TELEMETRY` | Telemetry config for Console Self-Managed: `disabled`, `online`, or `download` | `online` |
| `CAMUNDA_CONSOLE_DISABLE_AUTH` | Disables authentication for Console. With this option, set users don't have to log in to use Console and API requests can be executed without an Authorization header. <br /> By disabling authentication all `CAMUNDA_IDENTITY`, variables won't be used. | `true` |
| `CAMUNDA_LICENSE_KEY` | Your Camunda 8 license key, if your installation requires a license. For Helm installations, license keys can be configured globally in your `values.yaml` file. See the [Helm installation documentation](/self-managed/setup/install.md#configure-license-key) for more details. | N/A |
| Environment variable | Description | Example value |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `KEYCLOAK_BASE_URL` | Base URL for Keycloak | https://example.com/auth |
| `KEYCLOAK_INTERNAL_BASE_URL` | Internal base URL for Keycloak | http://camunda-platform-keycloak:80/auth |
| `KEYCLOAK_REALM` | Realm for Keycloak | camunda-platform |
| `CAMUNDA_IDENTITY_AUDIENCE` | Audience for Console client | console |
| `CAMUNDA_IDENTITY_CLIENT_ID` | Client ID for Console client | console |
| `CAMUNDA_CONSOLE_CONTEXT_PATH` | Context path for Console | console |
| `CAMUNDA_CONSOLE_CUSTOMERID` | Unique identifier of the customer | `customer-id` |
| `CAMUNDA_CONSOLE_INSTALLATIONID` | Unique installation ID of the current customer installation | `installation-id` |
| `CAMUNDA_CONSOLE_TELEMETRY` | Telemetry config for Console Self-Managed: `disabled`, `online`, or `download` | `online` |
| `CAMUNDA_CONSOLE_DISABLE_AUTH` | Disables authentication for Console. With this option, set users don't have to log in to use Console and API requests can be executed without an authorization header. <br /> By disabling authentication, all `CAMUNDA_IDENTITY` variables won't be used. | `true` |
| `CAMUNDA_LICENSE_KEY` | Your Camunda 8 license key, if your installation requires a license. For Helm installations, license keys can be configured globally in your `values.yaml` file. See the [Helm installation documentation](/self-managed/setup/install.md#configure-license-key) for more details. | N/A |
| `SERVER_SSL_ENABLED` | [optional]<br/>Whether to enable SSL support.<br/>Default: `false` | `true` |
| `SERVER_SSL_CERTIFICATE` | [optional]<br/>Path to a PEM-encoded SSL certificate file. | `file:/full/path/to/certificate.pem` |
| `SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | [optional]<br/>Path to a PEM-encoded private key file for the SSL certificate. | `file:/full/path/to/key.pem` |
| `SERVER_SSL_PASSPHRASE` | [optional]<br/>Passphrase for the key. | `passphrase` |
| `MANAGEMENT_SERVER_SSL_ENABLED` | [optional]<br/>Whether to enable SSL support for the management server routes.<br/>Default: `false` | `true` |
| `MANAGEMENT_SERVER_SSL_CERTIFICATE` | [optional]<br/>Path to a PEM-encoded SSL certificate file. | `file:/full/path/to/certificate.pem` |
| `MANAGEMENT_SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | [optional]<br/>Path to a PEM-encoded private key file for the SSL certificate. | `file:/full/path/to/key.pem` |
| `MANAGEMENT_SERVER_SSL_PASSPHRASE` | [optional]<br/>Passphrase for the key. | `passphrase` |

Console environment variables could be set in Helm via the `console.env` key. For more details, check [Console Helm values](https://artifacthub.io/packages/helm/camunda/camunda-platform#console-parameters).

Expand Down
53 changes: 53 additions & 0 deletions docs/self-managed/console-deployment/configuration/ssl.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
id: ssl
title: "Console SSL configuration"
sidebar_label: "SSL"
description: "Read details on additional SSL configuration for Console."
---

By default, communication between Console, Identity, and other components is not encrypted, as it usually occurs backend-to-backend within the same [Docker](/self-managed/setup/deploy/other/docker.md) network or [Kubernetes](/self-managed/setup/install.md) cluster.

TLS-encrypted communication can be enabled by following the steps below (for example, if backend-to-backend communication is not possible in a custom Camunda 8 installation setup).

## Configure Console for secure connections

Console can be configured using [environment variables](/self-managed/console-deployment/configuration/configuration.md#environment-variables) to enable secure connections to both Console and Identity.

### Configure the Identity base URL

Set the base URL (starting with `https://`) of your Identity instance using the following properties:

| Environment variable | Example value |
| ---------------------------- | ------------------------------ |
| `KEYCLOAK_BASE_URL` | `https://identity.example.com` |
| `KEYCLOAK_INTERNAL_BASE_URL` | `https://identity.example.com` |

### Configure SSL certificate

Enable and configure SSL by setting the following properties:

| Environment variable | Description | Example value |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `SERVER_SSL_ENABLED` | To enable SSL, set to `true`. | `true` |
| `SERVER_SSL_CERTIFICATE` | The path to a PEM-encoded SSL certificate file. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `file:/full/path/to/certificate.pem` |
| `SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | The path to a PEM-encoded private key file for the SSL certificate. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `file:/full/path/to/key.pem` |
| `SERVER_SSL_PASSPHRASE` | _Optional_ A passphrase for the private key. | `passphrase` |

SSL can be configured separately for the management routes using the `MANAGEMENT_` properties:

| Environment variable | Description | Example value |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `MANAGEMENT_SERVER_SSL_ENABLED` | To enable SSL, set to `true`. | `true` |
| `MANAGEMENT_SERVER_SSL_CERTIFICATE` | The path to a PEM-encoded SSL certificate file. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `file:/full/path/to/certificate.pem` |
| `MANAGEMENT_SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | The path to a PEM-encoded private key file for the SSL certificate. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `file:/full/path/to/key.pem` |
| `MANAGEMENT_SERVER_SSL_PASSPHRASE` | _Optional_ A passphrase for the private key. | `passphrase` |

## (Optional) Provide a custom certificate

If you are using a custom (self-signed) TLS certificate in Console or Identity, configure Console to accept the certificate.

Provide the path to the certificate file via the environment variable `NODE_EXTRA_CA_CERTS`:

| Environment variable | Description | Example value |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `NODE_EXTRA_CA_CERTS` | The path to your self-signed TLS certificate. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `/path/to/certificate.crt` |
2 changes: 1 addition & 1 deletion docs/self-managed/console-deployment/telemetry.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The telemetry feature categorizes the collected data into general Camunda data a

### How to enable telemetry

By default, the telemetry configuration is set to `disabled`. Telemetry can be activated by setting the appropriate configuration in the Camunda 8 Helm chart or setting the appropriate environment variables in the Console configuration. Refer to [Console configuration](./configuration.md) for more information.
By default, the telemetry configuration is set to `disabled`. Telemetry can be activated by setting the appropriate configuration in the Camunda 8 Helm chart or setting the appropriate environment variables in the Console configuration. Refer to [Console configuration](./configuration/configuration.md) for more information.

### Telemetry configuration options explained

Expand Down
Loading

0 comments on commit 16e5145

Please sign in to comment.