https://github.com/teonite/matrix
Easy & automated Matrix, Element and Bridges deployment using Kubernetes
https://github.com/teonite/matrix
bots bridge deployment kubernetes matrix synapse
Last synced: 8 months ago
JSON representation
Easy & automated Matrix, Element and Bridges deployment using Kubernetes
- Host: GitHub
- URL: https://github.com/teonite/matrix
- Owner: teonite
- Created: 2023-07-04T10:29:48.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-05T08:25:36.000Z (about 2 years ago)
- Last Synced: 2025-07-11T15:32:49.856Z (9 months ago)
- Topics: bots, bridge, deployment, kubernetes, matrix, synapse
- Language: Makefile
- Homepage:
- Size: 295 KB
- Stars: 7
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[contributors-shield]: https://img.shields.io/github/contributors/teonite/matrix.svg?style=for-the-badge
[contributors-url]: https://github.com/teonite/matrix/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/teonite/matrix.svg?style=for-the-badge
[forks-url]: https://github.com/teonite/matrix/network/members
[stars-shield]: https://img.shields.io/github/stars/teonite/matrix.svg?style=for-the-badge
[stars-url]: https://github.com/teonite/matrix/stargazers
[issues-shield]: https://img.shields.io/github/issues/teonite/matrix.svg?style=for-the-badge
[issues-url]: https://github.com/teonite/matrix/issues
Automated Matrix (synapse) deployment with appservices integration
This repository provides an automated setup for element-web and synapse with appservices for Kubernetes cluster deployment.
Table of Contents
- About the Repository
- Prerequisites
- Getting Started
-
Element-web Installation
-
Synapse
- Updating an already existing synapse server with new appservices
- Installing hookshot
- Installing Mautrix Telegram
-
Updating configuration of already running appservices
## About the repository
The purpose of this repository is to provide an **easy** way to **automate** the launch process using a combination of [element-web](https://github.com/vector-im/element-web), [synapse server](https://github.com/matrix-org/synapse), [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) and [mautrix-telegram](https://github.com/mautrix/telegram).
The repository contains configurations and instructions for integrating the aforementioned application services, allowing external services to interact with the Matrix network. This enables automation of various tasks and workflows.
Using this repository, users can effortlessly configure and set up the necessary components to automate the process of running the Synapse server and all related application services.
We utilized [Defguard](https://defguard.net/) as our OpenID Connect provider. For further information on its usage and setup instructions, please refer to their [documentation](https://defguard.gitbook.io/defguard/).
## Prerequisites
Before integrating, ensure you have the following prerequisites:
- **kubectl**: Install kubectl, the command-line tool for Kubernetes clusters. Refer to the [official kubectl documentation](https://kubernetes.io/docs/tasks/tools/#kubectl) for instructions.
- **Kubernetes**: Install and configure Kubernetes using `kubectl`. Refer to the [official Kubernetes documentation](https://kubernetes.io/docs/setup/) for instructions.
- **Helm**: Install Helm for managing applications on Kubernetes clusters. Refer to the [official Helm documentation](https://helm.sh/docs/intro/install/) for instructions.
## Getting Started
To begin, you don't necessarily need to modify any variables inside the `config/config.sh` file, but in most cases, it is recommended to consider changing the namespace and cluster name.
Follow the steps below to get started:
1. Run the `make init` command to create configuration files from templates.
2. Configure the files inside the `config/` directory.
> **NOTE:** In the files provided in the `config/` directory, make sure to replace all instances of the **openearth.space** domain with your domain name.
3. After configuring the files, if you want a full setup, execute the following command:
```bash
make install_full
```
This command will install element-web and synapse server with all appservices.
If you want to install appservices to an existing Synapse server, only install Element Web, or solely install the Synapse server, please refer to the appropriate sections below:
- [element-web](#installing-element-web-separately)
- [synapse](#synapse-installation)
- [matrix-hookshot](#installing-matrix-hookshot)
- [mautrix-telegram](#installing-mautrix-telegram)
## Installing element-web separately
To install Element Web separately, follow these straightforward steps after ensuring that the namespace and cluster_name in the `config/config.sh` file align with your specific requirements:
1. Run the `make init` command to generate the element-web configuration file.
2. Edit the values inside `config/element-web.yaml`.
3. Execute the following command:
```bash
make install_element_web
```
This command will initiate the installation of element-web, by default element-web will create ingress on ***chat.openearth.space***.
## Synapse Installation
To operate a federating Matrix server, you must have a publicly accessible subdomain with a Kubernetes ingress (which will be automatically created). If you intend to utilize a well-known entry, you must obtain a valid certificate for the desired subdomain to serve Synapse. Furthermore, if you opt for an SRV record, you will need a valid certificate for the main domain used for your MXIDs.
If you wish not to install appservices with synapse server, follow those steps:
1. Run the `make init` command to generate the necessary configuration files.
2. Edit `/config/synapse.yaml` and ensure the removal of any undesired app services configuration file paths and volumes contained within.
3. Execute the following command:
```bash
make install_synapse
```
> _**NOTE:**_ Additional configuration and setup may be required based on your specific requirements.
## Updating an already existing synapse server with new appservices
To update an existing Synapse server with new app services, you need to add the following lines to your Matrix-Synapse config map.
1. Begin by running `make init`. Modify the files within the `/config/` directory, excluding `element-web.yaml` and `synapse.yaml`. Remember to adjust the values in `config.sh` to match your Kubernetes setup.
2. Access the kubernetes dashboard and locate the Synapse server config map. In the `homeserver.yaml` value, incorporate the following lines:
```yaml
app_service_config_files:
- /synapse/config/hookshot/registration.yml
- /synapse/config/telegram/registration.yml
```
If you desire your app services to function in end-to-end encrypted rooms, include the subsequent lines:
```yaml
experimental_features:
msc2409_to_device_messages_enabled: true
msc3202_device_masquerading: true
msc3202_transaction_extensions: true
```
2. Open the Synapse server deployment file within the kubernetes dashboard. Locate the `volumes` section and append:
```yaml
- configMap:
defaultMode: 420
name: registration-hookshot
name: hookshot
- configMap:
defaultMode: 420
name: registration-telegram
name: telegram
```
Find the `volumeMounts` section and include:
```yaml
- mountPath: /synapse/config/hookshot
name: hookshot
- mountPath: /synapse/config/telegram
name: telegram
```
Ensure that no syntax errors are introduced.
3. Execute `make update_synapse_server`.
## Installing matrix-hookshot
Make sure your synapse server is running before installing matrix-hookshot. If it's not running, refer to [this section](#synapse-installation) for instructions.
To match your Kubernetes setup, modify the values in `/config/config.sh` and then run `make init`.
1. Open `config/hookshot` folder and edit files inside as needed.
2. Execute:
```
make install_hookshot
```
3. Access the Kubernetes dashboard and find the config map for the Synapse server. Add the following lines to the homeserver.yaml value:
```yaml
app_service_config_files:
- /synapse/config/hookshot/registration.yml
```
If you desire hookshot to function in end-to-end encrypted rooms, include the subsequent lines:
```yaml
experimental_features:
msc2409_to_device_messages_enabled: true
msc3202_device_masquerading: true
msc3202_transaction_extensions: true
```
4. Open the Synapse server deployment file within the kubernetes dashboard. Locate the `volumes` section and append:
```yaml
- configMap:
defaultMode: 420
name: registration-hookshot
name: hookshot
```
Find the `volumeMounts` section and include:
```yaml
- mountPath: /synapse/config/hookshot
name: hookshot
```
Ensure that no syntax errors are introduced.
Keep in mind that hookshot need some time to start responding or joining rooms
> For more detailed setup instructions, refer to the [official guide](https://matrix-org.github.io/matrix-hookshot/latest/setup.html).
## Installing mautrix-telegram
Make sure your synapse server is running before installing matrix-hookshot. If it's not running, refer to [this section](#synapse-installation) for instructions.
To match your Kubernetes setup, modify the values in `/config/config.sh` and then run `make init`.
1. Open `config/telegram` folder and edit files inside as needed.
2. Execute:
```
make install_telegram
```
3. Access the Kubernetes dashboard and find the config map for the Synapse server. Add the following lines to the homeserver.yaml value:
```yaml
app_service_config_files:
- /synapse/config/telegram/registration.yml
```
If you desire mautrix-telegram to function in end-to-end encrypted rooms, include the subsequent lines:
```yaml
experimental_features:
msc2409_to_device_messages_enabled: true
msc3202_device_masquerading: true
msc3202_transaction_extensions: true
```
4. Open the Synapse server deployment file within the kubernetes dashboard. Locate the `volumes` section and append:
```yaml
- configMap:
defaultMode: 420
name: registration-telegram
name: telegram
```
Find the `volumeMounts` section and include:
```yaml
- mountPath: /synapse/config/telegram
name: telegram
```
Ensure that no syntax errors are introduced.
## Updating running matrix-hookshot config
Updating already running matrix-hookshot config is straight forward:
1. Execute `make pull_hookshot_config`
2. Edit files inside `/temp/` directory
3. Execute `make update_hookshot_config`