From 32a492e571d89a5c701d7e981b7dbc9f8e57e21e Mon Sep 17 00:00:00 2001 From: Max Dor Date: Tue, 3 Jul 2018 02:44:04 +0200 Subject: [PATCH] Prepare for v0.1.0 - Basic usage doc - Sample config files - Travis-ci.org integration --- .travis.yml | 8 ++++ README.md | 100 ++++++++++++++++++++++++++++++++++++++- application-sample.yaml | 35 ++++++++++++++ build.gradle | 7 ++- registration-sample.yaml | 11 +++++ 5 files changed, 158 insertions(+), 3 deletions(-) create mode 100644 .travis.yml create mode 100644 application-sample.yaml create mode 100644 registration-sample.yaml diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..367c1ef --- /dev/null +++ b/.travis.yml @@ -0,0 +1,8 @@ +language: java +before_cache: + - rm -f $HOME/.gradle/caches/modules-2/modules-2.lock + - rm -fr $HOME/.gradle/caches/*/plugin-resolution/ +cache: + directories: + - $HOME/.gradle/caches/ + - $HOME/.gradle/wrapper/ diff --git a/README.md b/README.md index 19e828d..19942ab 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,101 @@ # Matrix Bridge to Voice and Video networks +[![Build Status](https://travis-ci.org/kamax-io/matrix-appservice-voip.svg?branch=master)](https://travis-ci.org/kamax-io/matrix-appservice-voip) -Coming very soon (TM) +[Requirements](#requirements) +[Setup](#setup) +[Integration](#integration) +[Usage](#usage) + +--- + +This is a Voice/Video/SMS bridge for Matrix using the Application Services (AS) API. + +This software is currently in alpha phase and is not ready for production: Your feedback and ideas are extremely welcome! +Please help us by opening an issue or joining us on Matrix at +[#mxasd-email:kamax.io](https://matrix.to/#/#mxasd-voip:kamax.io) + +# Requirements +You will need Java 8 to build and run this bridge. + +# Setup +Setup can either be done via downloading [the latest binary](https://github.com/kamax-io/matrix-appservice-voip/releases), +or by building the binary yourself. +Java JRE 1.8 or higher is required to run the binary. +Java JDK 1.8 or higher is required to build the binary. + +## Steps overview +1. [Build the bridge](#build) (Optional) +0. [Configure the bridge](#configure) +0. [Run the bridge](#run) +0. [Configure your HS](#homeserver) +0. [Configure your VoIP backend](#voip-providers) +0. [See Usage instructions](#usage) to see how to interact with the bridge +0. Start calling! + +## Build +If you would rather build the binary yourself rather than downloading the compiled one of the +[latest release](https://github.com/kamax-io/matrix-appservice-voip/releases): + +Checkout the repo: +```bash +git clone https://github.com/kamax-io/matrix-appservice-voip.git +cd matrix-appservice-voip +``` + +Run the following command in the repo base directory. The runnable jar `mxasd-email.jar` will be present in `./build/libs`: +```bash +./gradlew build +``` + +## Configure +Copy the default config file `application-sample.yaml` in the same directory as the jar file. +The configuration file contains a detailed description for each possible configuration item. +Edit it to suit your environment. + +## Run +### Manual +Place the binary into the directory of your choice and run it. +Example using `/opt/mxasd-email`: +```bash +cd build/libs/mxasd-email.jar /opt/mxasd-email/ +/opt/mxasd-email/mxasd-email.jar +``` + +# Integration +## Homeserver +### Synapse +Like any bridge, a registration file must be generated which will then be added to the HS config. +Currently, there is no mechanism to automatically generate this config file. + +You will find a working example at `registration-sample.yaml`, which you should copy at the same location as the Bridge configuration file. +Configuration must match the various sections in the bridge config file. + +Synapse can then be configured with: +``` +app_service_config_files: + - "/path/to/registration.yaml" +``` + +## VoIP providers +### FreeSWITCH +This bridge relies on the Verto module of FreeSWITCH which natively handles WebRTC. +Edit the `providers.freeswitch.verto` section in the config file to suit your installation and provide the Websocket URI +and relevant credentials. + +To be continued: a FreeSWITCH guide to help getting a basic setup running + +# Usage +At this time, there is no easy way to invite someone by phone number in Matrix clients. Therefore, you'll need to compute +the Matrix ID that correspond to the phone number on your own. + +The following step-by-step assumes you: +- Have `example.org` as your Matrix domain +- Have a user template with `_voip_%REMOTE_ID%` +- Want to place a call to `00123456789` + +1. Manually compute the Matrix ID, which will be `@_voip_00123456789:example.org` +2. Create a new room/chat and invite that Matrix ID. This room must only have the virtual user and yourself as members. +3. Place a call, the device at `00123456789` should ring + +# Support +On Matrix: #mxasd-email:kamax.io \ No newline at end of file diff --git a/application-sample.yaml b/application-sample.yaml new file mode 100644 index 0000000..2ec2e45 --- /dev/null +++ b/application-sample.yaml @@ -0,0 +1,35 @@ +# Domain that this AS belongs to. Used in a various place when generating/validating Matrix IDs. +# This value is typically the same as your HS domain. +matrix.domain: 'domain.tld' + +# A list of localpart templates used to generate virtual User IDs and produce a regexp for the HS config. +matrix.users: + - template: '_voip_%REMOTE_ID%' + +# HS Client endpoint address +matrix.home.host: 'http://localhost:8008' + +# The token used by the AS when communicating with the HS +# On *Nix-based system, running the following command is a good start point: pwgen 64 1 +matrix.home.asToken: 'MY_SECRET_AS_TOKEN_CHANGE_ME' + +# The token used by the HS when communicating with the AS +# On *Nix-based system, running the following command is a good start point: pwgen 64 1 +matrix.home.hsToken: 'MY_SECRET_HS_TOKEN_CHANGE_ME' + +# The localpart of the AS global user. The domain will always be the one of the HS +matrix.home.localpart: 'appservice-voip' + +# FreeSWITCH Verto Websocket endpoint and credentials +providers.freeswitch.verto: + url: 'wss://localhost:8082' + login: '1000' + password: '12345' + +# Mapping form Matrix localpart to Remote ID, used to match incoming remote calls +# +# Per ex, user1 would be turned into @user1:domain.tld and would receive all calls that the extension 1000 receives +bridge.mapping.users: + user1: '1000' + user2: '1001' + user3: '1002' diff --git a/build.gradle b/build.gradle index 9b1790f..fd436a9 100644 --- a/build.gradle +++ b/build.gradle @@ -18,6 +18,8 @@ * along with this program. If not, see . */ +import java.util.regex.Pattern + apply plugin: 'java' apply plugin: 'org.springframework.boot' @@ -29,13 +31,13 @@ buildscript { } dependencies { - classpath 'org.springframework.boot:spring-boot-gradle-plugin:2.0.1.RELEASE' + classpath 'org.springframework.boot:spring-boot-gradle-plugin:2.0.3.RELEASE' } } dependencies { compile 'io.kamax:matrix-java-sdk:0.0.12-9-ga7b4871' - compile 'org.springframework.boot:spring-boot-starter-web:2.0.1.RELEASE' + compile 'org.springframework.boot:spring-boot-starter-web:2.0.3.RELEASE' compile 'org.apache.commons:commons-collections4:4.1' testCompile 'junit:junit:4.12' } @@ -47,5 +49,6 @@ repositories { } bootJar { + baseName = 'mxasd-email' launchScript() } diff --git a/registration-sample.yaml b/registration-sample.yaml new file mode 100644 index 0000000..fab2603 --- /dev/null +++ b/registration-sample.yaml @@ -0,0 +1,11 @@ +id: "appservice-voip" +url: "http://localhost:8092" +as_token: "MY_SECRET_AS_TOKEN_CHANGE_ME" +hs_token: "MY_SECRET_HS_TOKEN_CHANGE_ME" +sender_localpart: "appservice-voip" +namespaces: + users: + - regex: "@_voip_*" + exclusive: true + aliases: [] + rooms: []