README.md

Automated Matrix (synapse) deployment with appservices integration

This repository provides an automated setup for element-web and synapse with appservices for Kubernetes cluster deployment.

Request Feature · Report Bug

Table of Contents

1. About the Repository
2. Prerequisites
3. Getting Started
4. Element-web Installation
   • Installing element-web separately
5. Synapse
   • Updating an already existing synapse server with new appservices
   • Installing hookshot
   • Installing Mautrix Telegram
6. Updating configuration of already running appservices
   • Updating running matrix-hookshot config

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, synapse server, matrix-hookshot and 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 as our OpenID Connect provider. For further information on its usage and setup instructions, please refer to their documentation.

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 for instructions.

• Kubernetes: Install and configure Kubernetes using kubectl. Refer to the official Kubernetes documentation for instructions.

• Helm: Install Helm for managing applications on Kubernetes clusters. Refer to the official Helm documentation 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:

   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
• synapse
• matrix-hookshot
• 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:

   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:

   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:

      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:

      experimental_features:
         msc2409_to_device_messages_enabled: true
         msc3202_device_masquerading: true
         msc3202_transaction_extensions: true

3. Open the Synapse server deployment file within the kubernetes dashboard. Locate the volumes section and append:

      - configMap:
         defaultMode: 420
         name: registration-hookshot
      name: hookshot
      - configMap:
         defaultMode: 420
         name: registration-telegram
      name: telegram

   Find the volumeMounts section and include:

      - 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 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:

      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:

      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:

      - configMap:
         defaultMode: 420
         name: registration-hookshot
      name: hookshot

   Find the volumeMounts section and include:

         - 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.

Installing mautrix-telegram

Make sure your synapse server is running before installing matrix-hookshot. If it's not running, refer to this section 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:

      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:

      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:

      - configMap:
         defaultMode: 420
         name: registration-telegram
      name: telegram

   Find the volumeMounts section and include:

         - 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

---

Request Feature · Report Bug

---