Index by title

Setup of Matrix homeserver

Running a Matrix homeserver (like Synapse) on localhost without DNS can be done for testing and development purposes.
Here's a general outline of the steps that needs to be followed:

  1. Prerequisites:

python3 -m venv path/to/venv
source path/to/venv/bin/activate
pip install package_name
  1. Install Synapse:
    You can install Synapse using pip. Open a terminal and run the following command:
pip install matrix-synapse
  1. Configure Synapse:
    Create a configuration file for Synapse. You can generate a basic configuration file using the following command:
python -m synapse.app.homeserver --server-name your.server.name --config-path /path/to/config

  1. Replace your.server.name with a unique server name. Modify the generated configuration file (/path/to/config) to your requirements.

    In your configuration file, you may want to set the listeners section to bind the server to your localhost IP (e.g., "127.0.0.1") on a specific port (e.g., 8008) to ensure that it only listens on your local machine.

  2. Create a Self-Signed Certificate:
    For testing purposes, you can create a self-signed SSL certificate. This step is optional but recommended if you want to use HTTPS.

    You can create a self-signed certificate using tools like OpenSSL.

openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 -keyout server.key -out server.crt

  1. Then, configure your Synapse server to use these certificates in your configuration file.

  2. Database Configuration:
    Configure the database settings in your Synapse configuration file. For Postgres follow these steps:

sudo apt install postgresql postgresql-contrib

sudo -u postgres bash

createuser --pwprompt synapse_user

createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse 

exit

sudo nano /etc/postgresql/15/main/postgresql.conf

#------------------------------------------------------------------------------
# CONNECTIONS AND AUTHENTICATION
#------------------------------------------------------------------------------

# - Connection Settings -

listen_addresses = 'localhost'          # what IP address(es) to listen on; 

sudo nano /etc/postgresql/15/main/pg_hba.conf

local   synapse         synapse_user                            md5

# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     peer
host    replication     all             127.0.0.1/32            md5
host    replication     all             ::1/128                 md5
local   synapse         synapse_user                            md5

database:
name: psycopg2
args:
user: synapse_user
password: <pass>
database: synapse
host: localhost
cp_min: 5
cp_max: 10

pip install psycopg2
pip install psycopg2-binary
  1. Start the Homeserver:
    To start the Synapse server, use the following command:
python -m synapse.app.homeserver --config-path /path/to/config

  1. Access your Homeserver:
    You can access your Matrix homeserver by using a Matrix client such as Element. Point your client to your localhost IP and the port you configured in the listeners section. For example, http://127.0.0.1:8008.

  2. User Registration:
    Register a new user on your homeserver using your Matrix client.

Remember that running a homeserver without DNS means you won't be able to access it from other devices on your network or the internet. It's suitable for local testing and development purposes. If you want to make your homeserver accessible outside your localhost, you'll need to configure DNS and network settings accordingly.

References

Overview

This integration bridges OpenProject, a project management tool, and Matrix/Element, a decentralized communication platform, using Matrix Hookshot. The integration enables seamless project collaboration by syncing users, projects, and notifications between OpenProject and Matrix/Element.

Key Features

  1. Permission Management:

  2. Project Room Creation:

  3. User Synchronization:

  4. Future Enhancements:

Prerequisites

  1. Matrix Hookshot:

  2. OpenProject:

  3. Matrix Server:

  4. Configuration Files:

Installation

Step 1: Clone and Set Up the Project

git clone https://github.com/girish17/matrix-hookshot.git
cd matrix-hookshot
npm install

Step 2: Configure Environment Variables

Create a .env file with the following:

OPENPROJECT_URL=https://openproject.example.com
OPENPROJECT_API_KEY=your_api_key
MATRIX_HOMESERVER=https://matrix.example.com
MATRIX_ACCESS_TOKEN=your_bot_access_token

Step 3: Configure Hookshot

Update the config.yaml file:

integrations:
  openproject:
    url: "https://openproject.example.com"
    api_key: "your_api_key"

Step 4: Build the Project

npm run build

Step 5: Run the Server

npm start

Features

1. Adding Users to Matrix Channels

Workflow

  1. The m.room.member event is captured by the Matrix Hookshot bot.

  2. The bot retrieves the project ID linked to the room.

  3. The user is added to the OpenProject project with the required permissions.

Example Code (Matrix Event Listener)

async function onRoomMemberEvent(event, roomId) {
    if (event.membership === "join") {
        const userId = event.state_key;
        const projectId = await getLinkedProjectId(roomId);
        const openProjectUser = await mapMatrixUserToOpenProject(userId);

        if (openProjectUser) {
            await addUserToOpenProject(projectId, openProjectUser);
        }
    }
}

2. Automatically Creating Project Rooms

Workflow

  1. A webhook from OpenProject triggers the bot.

  2. The bot creates a private Matrix room with the project name.

  3. The room ID and project ID are stored for synchronization.

Example Code (Project Creation Handler)

async function onProjectCreated(project) {
    const room = await matrixClient.createRoom({
        visibility: "private",
        name: project.name,
        topic: `OpenProject: ${project.name}`,
    });

    await linkRoomToProject(room.room_id, project.id);
}

3. Synchronizing Members

Workflow

  1. Periodic synchronization task or OpenProject webhook triggers the bot.

  2. Compare OpenProject members with Matrix room members.

  3. Add/remove users in the Matrix room to match OpenProject.

Example Code (Synchronization Task)

async function syncProjectMembers(projectId, roomId) {
    const projectMembers = await getOpenProjectMembers(projectId);
    const roomMembers = await getMatrixRoomMembers(roomId);

    for (const member of projectMembers) {
        if (!roomMembers.includes(member)) {
            await addMemberToMatrixRoom(roomId, member);
        }
    }

    for (const member of roomMembers) {
        if (!projectMembers.includes(member)) {
            await removeMemberFromMatrixRoom(roomId, member);
        }
    }
}

Testing

Local Testing

  1. Run Locally:
npm start
  1. Use Ngrok:
ngrok http 9000

  1. Configure the Ngrok URL in OpenProject webhook settings.

  2. Trigger events (e.g., project creation, member addition) and verify in Matrix.

Test Cases

Feature

Test Scenario

Expected Outcome

User joins Matrix room

Join a linked room

User added to OpenProject project

Project creation

Create a project in OpenProject

Matrix room created and linked

Member synchronization

Add/remove members in OpenProject

Members synced in Matrix room

Deployment

  1. Build and Package:
npm run build

  1. Deploy on Server:

  2. Webhook Setup:

Future Work

Resources