fix(docu): Rename SYNAPSE_DOMAIN to MATRIX_DOMAIN. If you use SYNAPSE_DOMAIN in your deployment, ensure you set the MATRIX_DOMAIN accordingly before upgrading.

docs/ci.md

@@ -15,17 +15,16 @@ This page covers openDesk deployment automation via Gitlab CI.
 
 The project includes a `.gitlab-ci.yml` that allows you to execute the deployment from a GitLab instance of your choice.
 
-
 When starting the pipeline through the GitLab UI, you will be queried for some variables plus the following ones:
 
-- `DOMAIN` = The domain to deploy to.
+- `DOMAIN`: Primary domain for your deployment making the openDesk services available e.g. as `https://portal.DOMAIN`.
-- `MAIL_DOMAIN` = (optional) Specify domain (f.e. root FQDN) for Mail, defaults to `DOMAIN`.
+- `MAIL_DOMAIN`: (optional) Domain for the users mail addresses, defaults to `DOMAIN`.
-- `SYNAPSE_DOMAIN` = (optional) Specify domain (f.e. root FQDN) for Synapse, defaults to `DOMAIN`.
+- `MATRIX_DOMAIN`: (optional) Domain for the users Matrix IDs, defaults to `DOMAIN`.
-- `NAMESPACE`: Defines into which namespace of your K8s cluster openDesk will be installed
+- `NAMESPACE`: Namespace of your K8s cluster openDesk will be installed to.
-- `MASTER_PASSWORD_WEB_VAR`: Overwrites value of `MASTER_PASSWORD`
+- `MASTER_PASSWORD_WEB_VAR`: Overwrites value of `MASTER_PASSWORD`.
 
 Based on your input, the following variables will be set:
-- `MASTER_PASSWORD` = `MASTER_PASSWORD_WEB_VAR`. If `MASTER_PASSWORD_WEB_VAR`
+- `MASTER_PASSWORD:`: `MASTER_PASSWORD_WEB_VAR`. If `MASTER_PASSWORD_WEB_VAR`
   is not set, the default for `MASTER_PASSWORD` will be used, unless you set
   `MASTER_PASSWORD` as a masked CI/CD variable in GitLab to supersede the default.
 

docs/enhanced-configuration/matrix-federation.md

@@ -0,0 +1,32 @@
+<!--
+SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
+SPDX-License-Identifier: Apache-2.0
+-->
+
+<h1>Matrix federation</h1>
+
+* [Use case](#use-case)
+* [Example configuration](#example-configuration)
+  * [DNS setup](#dns-setup)
+
+# Use case
+
+By default you only can chat with users that also have an account within your openDesk installation. The Element chat application and its server component Synapse are based on the Matrix protocol that supports federation with other Matrix servers to communicate with the users with accounts on these servers.
+
+# Example configuration
+
+The following values are used in this example documentation. Please ensure when you come across such a value even if it is part of a URL hostname or path that you adapt it where needed to your setup:
+
+- `opendesk.domain.tld`: the mandatory `DOMAIN` setting for your deployment resulting in `https://chat.opendesk.domain.tld` to access the Element chat.
+- `my_organization.tld`: an optional alternative domain used for mail and/or Matrix. If not used it is also set to `opendesk.domain.tld`.
+
+## DNS setup
+
+If you want to federate with other Matrix instances, you need to have both SRV records:
+
+| Record name                         | Type | Value                                  | Additional Information                                                             |
+| ----------------------------------- | ---- | -------------------------------------- | ---------------------------------------------------------------------------------- |
+| _matrix._tcp.my_organization.tld    | SRV  | `1 10 PORT matrix.opendesk.domain.tld` | `PORT` is your NodePort/LoadBalancer port of `opendesk-synapse-federation` service |
+| matrix-fed._tcp.my_organization.tld | SRV  | `1 10 PORT matrix.opendesk.domain.tld` | `PORT` is your NodePort/LoadBalancer port of `opendesk-synapse-federation` service |
+
+*Note:* `matrix.opendesk.domain.tld` in the "Value" column can also be the IP address where synapse TLS port is listening to.

docs/enhanced-configuration/separate-mail-matrix-domain.md

@@ -0,0 +1,68 @@
+<!--
+SPDX-FileCopyrightText: 2024 Zentrum für Digitale Souveränität der Öffentlichen Verwaltung (ZenDiS) GmbH
+SPDX-License-Identifier: Apache-2.0
+-->
+
+<h1>Separate domains for mail and or matrix</h1>
+
+* [Use case](#use-case)
+* [Example configuration](#example-configuration)
+  * [Mail domain](#mail-domain)
+  * [Matrix domain](#matrix-domain)
+
+# Use case
+
+As communication over mail and chat can go beyond the borders of your openDesk installation you may want to use different domains for the mail and/or matrix.
+
+# Example configuration
+
+The following values are used in this example documentation. Please ensure when you come across such a value even if it is part of a URL hostname or path that you adapt it where needed to your setup:
+
+- `opendesk.domain.tld`: the mandatory `DOMAIN` setting for your deployment resulting in `https://mail.opendesk.domain.tld` to access emails and `https://chat.opendesk.domain.tld` to access the Element chat that is based on the Matrix protocol.
+- `my_organization.tld`: the alternative domain used for mail and/or Matrix.
+
+## Mail domain
+
+By default all email addresses in openDesk are created based on the `DOMAIN` you specified for your deployment. In our example resulting in the users having `<username>@opendesk.domain.tld` as mail addresses. In case you prefer the users to send and receive emails with another domain you can set that one using the optional `MAIL_DOMAIN` in the deployment:
+
+```yaml
+global:
+  mailDomain: "my_organization.tld"
+```
+
+or via environment variable
+
+```shell
+export MAIL_DOMAIN=my_organization.tld
+```
+
+This of course requires the MX record for the domain to point to the mail host for your openDesk deployment. Optionally add the SPF and DMARC records.
+
+| Record name                | Type | Value                                            |
+| -------------------------- | ---- | ------------------------------------------------ |
+| my_organization.tld        | MX   | `10 mail.opendesk.domain.tld`                    |
+| my_organization.tld        | TXT  | `v=spf1 +a +mx +a:mail.opendesk.domain.tld ~all` |
+| _dmarc.my_organization.tld | TXT  | `v=DMARC1; p=quarantine`                         |
+
+## Matrix domain
+
+Similar to the specific domain for email addresses you may want to specify a domain that differs from your deployment's default `DOMAIN` to define your users Matrix IDs. Use the `MATRIX_DOMAIN` to do so:
+
+```yaml
+global:
+  matrixDomain: "my_organization.tld"
+```
+
+or via environment variable
+
+```shell
+export MATRIX_DOMAIN=my_organization.tld
+```
+
+This setup requires also a different DNS setup:
+
+| Record name                      | Type | Value                                  | Comment                                                                            |
+| -------------------------------- | ---- | -------------------------------------- | ---------------------------------------------------------------------------------- |
+| _matrix._tcp.my_organization.tld | SRV  | `1 10 PORT matrix.opendesk.domain.tld` | `PORT` is your NodePort/LoadBalancer port of `opendesk-synapse-federation` service |
+
+*Note:* `matrix.opendesk.domain.tld` in the "Value" column can also be the IP address where synapse TLS port is listening to.

docs/getting-started.md

@@ -57,7 +57,7 @@ For your convenience, we recommend to create a `*.domain.tld` A-Record to your c
 otherwise you need to create an A-Record for each subdomain.
 
 | Record name             | Type | Value                                              | Additional information                                                             |
-| ----------------------- | ---- | -------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| ----------------------- | ---- | -------------------------------------------------- | ---------------------------------------------------------------------------------- |
 | *.domain.tld            | A    | IPv4 address of your Ingress Controller            |                                                                                    |
 | *.domain.tld            | AAAA | IPv6 address of your Ingress Controller            |                                                                                    |
 | mail.domain.tld         | A    | IPv4 address of your postfix NodePort/LoadBalancer | Optional mail should directly be delivered to openDesk's Postfix                   |
@@ -65,7 +65,7 @@ otherwise you need to create an A-Record for each subdomain.
 | domain.tld              | MX   | `10 mail.domain.tld`                               |                                                                                    |
 | domain.tld              | TXT  | `v=spf1 +a +mx +a:mail.domain.tld ~all`            | Optional, use proper MTA record if present                                         |
 | _dmarc.domain.tld       | TXT  | `v=DMARC1; p=quarantine`                           | Optional                                                                           |
-| _matrix._tcp.domain.tld | SRV  | `1 10 PORT matrix.domain.tld`                      | The `PORT` is your NodePort/LoadBalancer port of `opendesk-synapse-federation` service. |
+| _matrix._tcp.domain.tld | SRV  | `1 10 PORT matrix.domain.tld`                      | `PORT` is your NodePort/LoadBalancer port of `opendesk-synapse-federation` service |
 
 ## Domain
 
@@ -92,40 +92,6 @@ or via environment variable
 export DOMAIN=domain.tld
 ```
 
-Additionally, you can announce/specify an alternative domain for mail and chat.
-
-As an example, if your domain is `domain.tld` and you want to send mails with this domain, then you can deploy openDesk to
-`*.opendesk.domain.tld` and send mail as `default.user@domain.tld`.
-Webmail will be accessed via `mail.opendesk.domain.tld` in this scenario.
-The required routing have to be implemented by yourself.
-
-The alternative domains have to be set either via `dev` environment
-
-```yaml
-global:
-  mailDomain: "open.desk"
-  synapseDomain: "open.desk"
-```
-
-or via environment variable
-
-```shell
-export MAIL_DOMAIN=open.desk
-export SYNAPSE_DOMAIN=open.desk
-```
-
-If you want to federate with other Matrix instances, you need to add an SRV record to signal Matrix delegation.
-
-| Record name                    | Type | Value                     |
-|--------------------------------|------|---------------------------|
-| _matrix._tcp.SYNAPSE_DOMAIN    | SRV  | `1 10 PORT matrix.DOMAIN` |
-| matrix-fed._tcp.SYNAPSE_DOMAIN | SRV  | `1 10 PORT matrix.DOMAIN` |
-| MAIL_DOMAIN                    | MX   | `10 mail.domain.tld`    |
-
-_Hint:_ Replace `SYNAPSE_DOMAIN`, `MAIL_DOMAIN` and `DOMAIN` with proper values of your domain settings.
-
-_Hint:_ `matrix.DOMAIN` can also be an IP address where synapse tls port is listening to.
-
 ### Apps
 
 All available apps and their default value can be found in `helmfile/environments/default/workplace.yaml`.

helmfile/apps/element/values-matrix-neodatefix-widget.yaml.gotmpl

@@ -4,7 +4,7 @@
 configuration:
   bot:
     username: "meetings-bot"
-    homeserver: {{ .Values.global.synapseDomain | default .Values.global.domain }}
+    homeserver: {{ .Values.global.matrixDomain | default .Values.global.domain }}
 
 containerSecurityContext:
   allowPrivilegeEscalation: false

helmfile/apps/element/values-synapse.yaml.gotmpl

@@ -29,7 +29,7 @@ configuration:
     password: {{ .Values.databases.synapse.password | default .Values.secrets.postgresql.matrixUser | quote }}
 
   homeserver:
-    serverName: {{ .Values.global.synapseDomain | default .Values.global.domain }}
+    serverName: {{ .Values.global.matrixDomain | default .Values.global.domain }}
     appServiceConfigs:
       - as_token: {{ .Values.secrets.intercom.synapseAsToken | quote }}
         hs_token: {{ .Values.secrets.intercom.synapseAsToken | quote }}

helmfile/environments/default/global.gotmpl

@@ -17,7 +17,7 @@ global:
 
   ## Define synapse host
   #
-  synapseDomain: {{ env "SYNAPSE_DOMAIN" | quote }}
+  matrixDomain: {{ env "MATRIX_DOMAIN" | quote }}
 
   ## Define docker registry address.
   #