1 files changed, 58 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3540e48
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# Easybridge
+
+Easybridge is a Matrix-to-everything (almost) bridge.
+It acts as a client under your name on all instant messaging networks where
+you have an account, and presents your private messages as well as group
+conversations in Matrix in a uniform view.
+Basically, Matrix becomes your everything chat client!
+
+Current features:
+
+- Backends: IRC, XMPP, Mattermost (more to come)
+- Private messages and group/chat room messages
+- Automatic setup of Matrix rooms that bridge to outside rooms
+- Room name and topic synchronization (partially)
+- Images and file transfers (Mattermost backend)
+- Avatar and room pictures (Mattermost backend, one-way only)
+- Web interface for setting up accounts so that new accounts can be easily
+  added and you don't have to type your credentials in a clear-text Matrix room
+- Credentials are stored encrypted in the database using users' Matrix passwords
+
+There is lot to do! See the issues if you want to join us on this project.
+
+A Docker image is provided on the [Docker hub](https://hub.docker.com/r/lxpz/easybridge_amd64).
+
+Easybridge takes a single command line argument, `-config <filename>`, which is the
+path to its config file (defaults to `./config.json`).
+The configuration file is a JSON file whose contents is described in the following section.
+
+Easybridge is licensed under the terms of the GPLv3.
+
+
+## Building Easybridge
+
+Easybridge requires go 1.13 or later.
+
+To build Easybridge, clone this repository outside of your `$GOPATH`.
+Then, run `make` in the root of the repo.
+
+
+## Configuring Easybridge
+
+Easybridge acts as a Matrix application service: in this regard,
+it requires a registration file to be added to your homeserver.
+It uses a database to store configuration and state information,
+which can be any backend supported by [Gorm](https://gorm.io).
+
+Easybridge is configured using a single JSON configuration file, which contains
+a dictionnary whose keys are the following:
+
+- `log_level`: what log level Easybridge runs with (trace, debug, info, warn, error, fatal, panic). **Warning:** in `trace` level, the content of all calls to the Matrix API and some other information will be dumped, exposing user's credentials and messages. In `debug` level, room join/leave information will be exposed. The `info` level (default) does not expose any user's private information.
+- `appservice_bind_addr`: on what IP/port to bind as a Matrix app service (HTTP only, no HTTPS)
+- `web_bind_addr`: on what IP/port to bind for the web interface that allows adding and configuring accounts (HTTP only, no HTTPS, use a reverse proxy for that)
+- `web_url`: the outside HTTP/HTTPS address at which the web interface is made available. If set, a widget will be added in the Easybridge room so that users can configure the bridge without leaving the Riot client.
+- `registration`: path to the YAML appservice registration file
+- `homeserver_url`: HTTP address of the Matrix homeserver
+- `matrix_domain`: the dmoain name of the Matrix homeserver (i.e. the domain used in user identifiers, room identifiers, etc)
+- `db_type` and `db_path`: the database backend and path to use (see the [Gorm documentation](http://gorm.io/docs/connecting_to_the_database.html))
+- `session_key`: a key with which session cookies are encrypted for the web interface