diff --git a/docs/ci.md b/docs/ci.md
index 2584d4f2..f0555faa 100644
--- a/docs/ci.md
+++ b/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.
-- `MAIL_DOMAIN` = (optional) Specify domain (f.e. root FQDN) for Mail, defaults to `DOMAIN`.
-- `SYNAPSE_DOMAIN` = (optional) Specify domain (f.e. root FQDN) for Synapse, defaults to `DOMAIN`.
-- `NAMESPACE`: Defines into which namespace of your K8s cluster openDesk will be installed
-- `MASTER_PASSWORD_WEB_VAR`: Overwrites value of `MASTER_PASSWORD`
+- `DOMAIN`: Primary domain for your deployment making the openDesk services available e.g. as `https://portal.DOMAIN`.
+- `MAIL_DOMAIN`: (optional) Domain for the users mail addresses, defaults to `DOMAIN`.
+- `MATRIX_DOMAIN`: (optional) Domain for the users Matrix IDs, defaults to `DOMAIN`.
+- `NAMESPACE`: Namespace of your K8s cluster openDesk will be installed to.
+- `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.
diff --git a/docs/enhanced-configuration/matrix-federation.md b/docs/enhanced-configuration/matrix-federation.md
index e69de29b..852496c2 100644
--- a/docs/enhanced-configuration/matrix-federation.md
+++ b/docs/enhanced-configuration/matrix-federation.md
@@ -0,0 +1,32 @@
+
+
+Matrix federation
+
+* [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.
diff --git a/docs/enhanced-configuration/separate-mail-matrix-domain.md b/docs/enhanced-configuration/separate-mail-matrix-domain.md
index e69de29b..a5888a73 100644
--- a/docs/enhanced-configuration/separate-mail-matrix-domain.md
+++ b/docs/enhanced-configuration/separate-mail-matrix-domain.md
@@ -0,0 +1,68 @@
+
+
+Separate domains for mail and or matrix
+
+* [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 `@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.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 9f56ac1f..28035b30 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -56,16 +56,16 @@ The deployment is designed to deploy each application/service under a dedicated
For your convenience, we recommend to create a `*.domain.tld` A-Record to your cluster ingress controller,
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 |
-| mail.domain.tld | AAAA | IPv6 address of your postfix NodePort/LoadBalancer | Optional mail should directly be delivered to openDesk's Postfix |
-| 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. |
+| 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 |
+| mail.domain.tld | AAAA | IPv6 address of your postfix NodePort/LoadBalancer | Optional mail should directly be delivered to openDesk's Postfix |
+| 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` | `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`.
diff --git a/helmfile/apps/element/values-matrix-neodatefix-widget.yaml.gotmpl b/helmfile/apps/element/values-matrix-neodatefix-widget.yaml.gotmpl
index 2d8964f4..2c1e6a04 100644
--- a/helmfile/apps/element/values-matrix-neodatefix-widget.yaml.gotmpl
+++ b/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
diff --git a/helmfile/apps/element/values-synapse.yaml.gotmpl b/helmfile/apps/element/values-synapse.yaml.gotmpl
index 133e2e4d..c073316a 100644
--- a/helmfile/apps/element/values-synapse.yaml.gotmpl
+++ b/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 }}
diff --git a/helmfile/environments/default/global.gotmpl b/helmfile/environments/default/global.gotmpl
index cb9951f7..59603c4e 100644
--- a/helmfile/environments/default/global.gotmpl
+++ b/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.
#