lx
/
easybridge
0
0
Fork 0
Code Issues 1.6k Pull Requests Releases Activity

Update README

This commit is contained in:
Alex 2020-05-04 19:54:36 +02:00
parent d7973a98fe
commit 4fe24cf545
1 changed files with 32 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@ -7,19 +7,23 @@ conversations in Matrix in a uniform view.
Basically, Matrix becomes your everything chat client!
**WARNING** Easybridge is still very experimental and crashes sometimes.
Also, the Facebook Messenger backend might get you rate-limited on login
attempts if you restart the bridge too often, which will lock you out of
your Facebook account asking you to recover your account and change your password.
See below for information on how to avoid this situation.
Current backend status:
- IRC: text messages only (private messages and public channels). Has bugs, most notably: messages will be duplicated if several users connect to the same channel.
- XMPP: text messages only (private chat and MUCs), no backlog, no avatars, no file transfer.
- Mattermost: in quite good shape. Private & group conversations with text messages and attachments (images or other files). Handles retrieving of message backlog, user avatars and room avatars from the server.
- Facebook messenger: in quite good shape, handles private messages and groups, text messages, attachments, stickers, profile pictures (low res only), backlog. Sometimes disconnects from the server and messages stop arriving.
Current features:
- Backends: IRC, XMPP, Mattermost, Facebook Messenger (more to come)
- Private messages and group/chat room messages
- Handles private chats (one-to-one conversations) as well as group chats (sometimes called channels, multi-user chats, or chat rooms)
- 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)
- Images and file transfers (Mattermost and FB Messenger backends)
- Avatar and room pictures (Mattermost backend and FB Messenger backends, one-way only)
- Retrieving old messages / missed messages when backend was disconnected (Mattermost and FB Messenger)
- 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
@ -28,28 +32,34 @@ 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.
Easybridge requires go 1.13 or later. The Facebook Messenger backend requires Python 3 and the `fbchat` library (tested with v1.9.6).
To build Easybridge, clone this repository outside of your `$GOPATH`.
Then, run `make` in the root of the repo.
## Configuring Easybridge
## Operating 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 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.
If the config file does not exist, a template will be created.
A template appservice registration file will also be created if necessary.
## Configurating Easybridge
Easybridge is configured using a single JSON configuration file, which contains
a dictionnary whose keys are the following:
@ -77,13 +87,16 @@ a dictionnary whose keys are the following:
## Facebook Messenger alternative login procedure
The default login proedure for the Messenger backend is to log in with your email and password each time
Easybridge starts. Unfortunately, if Easybridge restarts too often, this will get you rate limited on login
attempts quite rapidly. To bypass this issue, the Messenger backend provides the ability to login
using a *client pickle*, i.e. a serialized client that contains all of the cookies obtained during a single
initial login procedure, so that further logins are not required any longer.
The default login procedure for the Messenger backend is to log in with your email and password.
Unfortunately, if this login procedure happenned to often, you would get rate limited on login
attempts quite rapidly.
To bypass this issue, once sucessfully logged in Easybridge will store a *client pickle* in your account
configuration, i.e. a blob that contains your Facebook cookies so that the username+password procedure
doesn't need to be repeated everytime Easybridge restarts.
To use this method, **do not enter your password in Easybridge when configuring the Messenger backend**.
If the automated username+password procedure fails, the user can generate a client pickle from the
command line and use that in the configuration instead of entering a username and a password.
To use this method, **do not enter your password in Easybridge when configuring the Messenger backend (only enter your email address)**.
Generate your client pickle by running the following command:
```