Prepare for v0.1.0

- Basic usage doc
- Sample config files
- Travis-ci.org integration

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

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

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'

build.gradle

@@ -18,6 +18,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+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()
 }

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