A NethServer 8 module for Matrix chat service integration with LDAP authentication.
This module provides a complete Matrix chat solution including:
- Synapse (Matrix Homeserver) - Core Matrix server
- Element Web (Web Client) - Web interface for Matrix chat
- Cinny (Web Client) - Alternative web interface for Matrix chat
- Seamless integration with NethServer 8 LDAP user directory
- Configurable domain names for both Matrix server and Element web client
- Automatic SSL/TLS certificate management via Traefik
- Matrix Federation support
- Persistent data storage
- Postgresql database backend
Instantiate the module with:
add-module ghcr.io/nethserver/matrix:latest 1
The output of the command will return the instance name. Output example:
{"module_id": "matrix1", "image_name": "matrix", "image_url": "ghcr.io/nethserver/matrix:latest"}
Let's assume that the matrix instance is named matrix1.
Launch configure-module, by setting the following parameters:
synapse_domain_name: The fully qualified domain name for the Matrix server (e.g.,matrix.example.com)element_domain_name: The fully qualified domain name for the Element web client (e.g.,chat.example.com)cinny_domain_name: The fully qualified domain name for the Cinny client (e.g.,cinny.example.com)lets_encrypt: Set totrueto enable automatic SSL certificate generation via Let's Encrypt for both domains.ldap_domain: The LDAP domain name to be used for authentication.mail_from: The mail sender address for notification mailsnethvoice_auth_url: The NethVoice authentication URL to enable NethVoice integration, if set thematrix2acrobitsservice will be configured and started.
Example:
api-cli run module/matrix1/configure-module --data '{"synapse_domain_name": "matrix.example.com", "element_domain_name": "chat.example.com", "cinny_domain_name": "cinny.example.com", "lets_encrypt": true, "ldap_domain": "users.example.com", "mail_from": "[email protected]", "nethvoice_auth_url": "https://nethvoice.nethserver.org/freepbx/rest/testextauth"}'
The above command will:
- Start and configure the Synapse Matrix homeserver with LDAP authentication
- Deploy Element Web client and Cinny client configured to connect to the local Synapse instance
- Set up Traefik routes for both domains with automatic SSL certificates
- Start Matrix2Acrobits Application Service
Access your Matrix installation:
- Matrix server:
https://matrix.example.com - Element web client:
https://chat.example.com - Cinny client:
https://cinny.example.com
Two web clients are available, Element web and Cinny. They can be enabled in the UI or by using the enable_element or enable_cinny flag.
The Element client supports customized themes, examples are added to the configuration file in element-config/config.json.
"custom_themes": [
{
"name": "NethServer1",
"is_dark": false,
"fonts": {
"faces": [
{
"font-family": "Inter",
"src": [{"url": "/fonts/Inter.ttf", "format": "ttf"}]
}
],
"general": "Inter, sans",
"monospace": "'Courier New'"
},
"colors": {
"accent-color": "#3596fc",
"primary-color": "#368bd6",
"warning-color": "#ff4b55",
"sidebar-color": "#27303a",
"roomlist-background-color": "#f3f8fd",
"roomlist-text-color": "#2e2f32",
"roomlist-text-secondary-color": "#61708b",
"roomlist-highlights-color": "#ffffff",
"roomlist-separator-color": "#e3e8f0",
"timeline-background-color": "#ffffff",
"timeline-text-color": "#2e2f32",
"timeline-text-secondary-color": "#61708b",
"timeline-highlights-color": "#f3f8fd"
},
"compound": {
"--cpd-color-icon-accent-tertiary": "var(--cpd-color-blue-800)",
"--cpd-color-text-action-accent": "var(--cpd-color-blue-900)"
}
}
]
Cinny is an alternative web client for Matrix chat, included in this module to provide users with a modern, lightweight interface. It can be accessed via a web browser and supports essential Matrix features such as messaging, rooms, and user authentication via OpenID Connect. Cinny is pre-configured to work with the Synapse server for seamless integration with NethServer 8 LDAP.
The module automatically discovers LDAP settings from the NethServer 8 configuration. Synapse is configured to connect to the NS8 LDAP proxy to authenticate users against the centralized user directory.
The LDAP discovery happens every time the services start through the bin/discover-ldap
script, which refreshes the state/ldap.env file with current LDAP configuration.
If LDAP settings change while the module is running, the event handler
events/ldap-changed/10reload_services will restart the affected services.
The module supports Matrix federation by configuring the necessary server delegation and federation settings. The Synapse server is configured with the proper server name and federation endpoints are exposed through Traefik.
The used secrets are stored in matrix-secrets.env. To rotate or recreate those secrets, you can remove the file, it will be recreated with new secrets after reconfiguration of the app.
To uninstall the instance:
remove-module --no-preserve matrix1
Test the module using the test-module.sh script:
./test-module.sh <NODE_ADDR> ghcr.io/nethserver/matrix:latest
The tests are made using Robot Framework
Translated with Weblate.
To setup the translation process:
- add GitHub Weblate app to your repository
- add your repository to [hosted.weblate.org]((https://hosted.weblate.org) or ask a NethServer developer to add it to ns8 Weblate project
Stack explanation:
- Synapse is the standard de-fact Matrix homeserver implementation
- Element web is the official Matrix web client, it can be replaced with other web client clients like Cinny
Alternative stacks:
- Use MAS to add more authentication methods (SAML, OIDC, LDAP, etc.) and integrate with authentik 1 2
If the current stack will be used, the following must be made.
NethVoice CTI integration:
- test current available client integrations
- Chatterbox
- Cactus
- Plain Javascript SDK
- implement authentication, there 2 possible ways:
- add support for OIDC ID inside CTI middleware: the user authenticate against the Oauth 2 provider (like authentik, if 2FA is required) and the middleware uses the ID token to authenticate against Synapse with the obtained token
- use normal LDAP auhtentication: the CTI middleware takes care also to authenticate against Synapse using LDAP credentials
- Evaluate if Sygnal Push Gateway is required (it should not)
- Add support for VoIP and Video calls with Element Call
- Add Whatsapp Bridge with mautrix-whatsapp
- Add Telegram Bridge with mautrix-telegram
- Considerations for Implementing consolidated Matrix Bridges, Image: MAtrix Bridges Image