mirror of
https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk.git
synced 2025-12-06 15:31:38 +01:00
100 lines
4.0 KiB
Markdown
100 lines
4.0 KiB
Markdown
<!--
|
|
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)
|
|
* [DNS](#dns)
|
|
* [Webserver](#webserver)
|
|
* [Content Security Policy](#content-security-policy)
|
|
* [.well-known](#well-known)
|
|
|
|
# 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
|
|
```
|
|
|
|
### DNS
|
|
|
|
The following changes apply to the standard DNS:
|
|
|
|
| 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.
|
|
|
|
### Webserver
|
|
|
|
#### Content Security Policy
|
|
|
|
The webserver of `my_organization.tld` should add `*.opendesk.domain.tld` to its CSP header.
|
|
|
|
#### .well-known
|
|
|
|
If you want to use other Matrix clients,
|
|
e.g., Element Messenger for [iOS](https://apps.apple.com/de/app/element-messenger/id1083446067)
|
|
or [Android](https://play.google.com/store/apps/details?id=im.vector.app),
|
|
you need to create a JSON file with the following contents that is served from
|
|
`https://my_organization.tld/.well-known/matrix/client`:
|
|
|
|
```json
|
|
{
|
|
"m.homeserver": {
|
|
"base_url": "https://matrix.opendesk.domain.tld"
|
|
}
|
|
}
|
|
```
|
|
|
|
This ensures clients know where to find the Matrix protocol endpoint when users specify `my_organization.tld`
|
|
as their homeserver.
|