Hades Matrix Bridge

This is the start of an implementation of a Matrix Bridge for connecting to Hades talker (hades-talker.org 6660).

This is a work in progress, and a successor to the mx-puppet-hades project.

It's pretty rough round the edges, with a pile of things still needing fixed. But it does work in the most basic sense.

Installation

An initial registration yaml file needs to be created for matrix. This can be generated by running the application with the --generate-yaml flag. This will create a file in the data directory called hades-bridge-registration.yaml.

e.g. ./HadesMatrixBridge --generate-yaml

This file requires to be edited, specifically to check and set the url parameter, which is the URL that the matrix server will use to communicate with the bridge. This URL must be accessible from the matrix server.

This file then needs to be registered with your matrix server.

If using docker, the following command will create the registration file and then exit. Note: Currently the '/path/to/data' directroy needs to be 'chmod 777', this should be fixed in a future release.

docker run --rm -v /path/to/data:/app/data ghcr.io/neilsb/hades-matrix-bridge:latest --generate-yaml

Configuration

The application can be configured using either the appsettings.json file, environment variables or command line parameters. The command line parameters take precedence over environment variables, and Environment variables take precedence over the configuration file.

Command Line Options

The following command line options are available:

• --server-url: The URL of the Matrix server.
• --port: The port for the bridge to listen on. (Default: 9000)
• --bind: The address for the bridge to bind to. (Default: 0.0.0.0)
• --hades-server: The hades server hostname/ip (Default: hades-talker.org)
• --hades-port: The hades server port (Default 6660)

Configuration File Structure

The application will check the data directory for a file called appsettings.json.

{
  "Matrix": {
    "ServerUrl": "https://matrix.example.com",
    "Port": 9000
  },
  "Database": {
    "Path": "data/hades_bridge.db"
  },
  "Hades": {
    "Server": "hades-talker.org",
    "Port": 6660
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Environment Variables

You can override any configuration setting using environment variables. The naming convention is:

SectionName__SettingName

For example:

Matrix__ServerUrl=https://matrix.example.com
Matrix__Port=9000
Database__Path=data/hades_bridge.db
Hades__Server=hades-talker.org
Hades__Port=6660

Docker Configuration

When running in Docker, you can pass environment variables using the -e flag: NOTE: For Matrix__ServerUrl, if not using the standard https port (443), remember to append your port, eg :8448

docker run -d \
  -e Matrix__ServerUrl=https://matrix.example.com \
  -e Matrix__Port=9000 \
  -e Database__Path=data/hades_bridge.db \
  -e Hades__Server=hades-talker.org \
  -e Hades__Port=6666 \
  -p 9000:9000 
  ghcr.io/neilsb/hades-matrix-bridge:latest

Or using a docker-compose.yml file: NOTE: For Matrix__ServerUrl, if not using the standard https port (443), remember to append your port, eg :8448

version: '3'
services:
  hadesmatrixbridge:
    image: ghcr.io/neilsb/hades-matrix-bridge:latest
    environment:
      - Matrix__ServerUrl=https://matrix.example.com
      - Matrix__Port=9000
      - Database__Path=data/hades_bridge.db
      - Hades__Server=hades-talker.org
      - Hades__Port=6660
    ports:
      - "9000:9000"
    volumes:
      - ./data:/app/data

Building from Source

To build the project from source, you'll need to have .NET 9.0 installed. You can then build the project using the following command:

dotnet build

For local development, you can create an appsettings.Development.json file with your development settings. This file is excluded from git by default.

Usage

First you create a room with the bridge bot (@hadesbot:YOURSERVER.COM), and say something to get the bot to join. Next you type link <username> <password> [matrix name], e.g. link bob p@ssw0rd.

The option "Matrix Name" parameter is your user on matrix. If set, when someone mentions your username on Hades your Matrix name will be added to the text to produce a matrix mention notification.

To see a list of existing puppets, use list. To unlink a puppet just talk to the brige bot and type unlink <puppet_id>.

Once linked, restart the application and when someone speaks in the Hades talker, a new room will be created, you'll need to rememer to accept the invitation.