Add README and setup instructions

This commit is contained in:
Andrew Ferrazzutti 2022-03-13 00:57:45 -05:00
parent 491cdca7b6
commit 9c330350e0
4 changed files with 134 additions and 0 deletions

14
README.md Normal file
View File

@ -0,0 +1,14 @@
# matrix-appservice-kakaotalk
A Matrix-KakaoTalk puppeting bridge.
Uses [node-kakao](https://github.com/storycraft/node-kakao) to communicate with the KakaoTalk API.
Bridge code based on [mautrix-facebook](https://github.com/mautrix/facebook).
## Features & roadmap
[ROADMAP.md](ROADMAP.md)
contains a general overview of what is supported by the bridge.
## Setup
[SETUP.md](SETUP.md)
## Discussion
Matrix room: [`#matrix-appservice-kakaotalk:miscworks.net`](https://matrix.to/#/#matrix-appservice-kakaotalk:miscworks.net)

67
ROADMAP.md Normal file
View File

@ -0,0 +1,67 @@
# Features & roadmap
* Matrix → KakaoTalk
* [ ] Message content
* [x] Text
* [ ] Media
* [ ] Stickers
* [ ] Files
* [ ] Voice messages
* [ ] Videos
* [ ] Images
* [ ] Locations
* [ ] Formatting
* [ ] Replies
* [ ] Mentions
* [ ] Message redactions
* [ ] Message reactions
* [ ] Presence
* [ ] Typing notifications
* [ ] Read receipts
* [ ] Power level
* [ ] Membership actions
* [ ] Invite
* [ ] Kick
* [ ] Leave
* [ ] Room metadata changes
* [ ] Name
* [ ] Avatar
* [ ] Per-room user nick
* KakaoTalk → Matrix
* [ ] Message content
* [x] Text
* [ ] Media
* [ ] Stickers
* [ ] Videos
* [ ] Images
* [ ] Formatting
* [ ] Replies
* [ ] Mentions
* [ ] Message reactions
* [x] Message history
* [ ] Presence
* [ ] Typing notifications
* [ ] Read receipts
* [ ] Admin status
* [ ] Membership actions
* [ ] Add member
* [ ] Remove member
* [ ] Leave
* [ ] Chat metadata changes
* [x] Title
* [ ] Avatar
* [ ] Initial chat metadata
* [x] Title
* [ ] Avatar
* [x] User metadata
* [x] Name
* [x] Avatar
* Misc
* [x] Multi-user support
* [x] Shared group chat portals
* [ ] Automatic portal creation
* [x] At startup
* [ ] When added to chat
* [x] When receiving message
* [x] Private chat creation by inviting Matrix puppet of Messenger user to new room
* [x] Option to use own Matrix account for messages sent from other Messenger clients

49
SETUP.md Normal file
View File

@ -0,0 +1,49 @@
* [Manual setup](#manual-setup)
* [systemd](#systemd)
* [Docker](#docker)
---
# Manual setup
These instructions describe how to install and run the bridge manually from a clone of this repository.
## Minimum requirements
* Python 3.7
* Node 16.13 (not yet tested with earlier versions)
* postgresql 11
* A KakaoTalk account on a smartphone (Android or iOS)
## Optional requirements
* Native dependencies for [end-to-bridge](https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html): https://docs.mau.fi/bridges/python/optional-dependencies.html#all-python-bridges
## Initial setup
### node-kakao module
1. `cd` to the `node` directory and run `npm install`
1. Copy `node/example-config.json` to `node/config.json`
1. Edit `node/config.json` with desired settings (see [node/README.md](node/README.md) for details)
### Bridge module
1. `cd` to the repository root and create a Python virtual environment with `python3 -m venv .venv`, and enter it with `source .venv/bin/activate`
1. Install Python requirements:
* `pip install -Ur requirements.txt` for base functionality
* `pip install -Ur optional-requirements.txt` for [end-to-bridge](https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html) encryption and metrics
* Note that end-to-bridge encryption requires some native dependencies. For details, see https://docs.mau.fi/bridges/python/optional-dependencies.html#all-python-bridges
1. Copy `matrix_appservice_kakaotalk/example-config.yaml` to `config.yaml`, and update it with the proper settings to connect to your homeserver
* In particular, be sure to set the `rpc.connection` settings to use the socket you chose in `node/config.json`
1. Run `python -m matrix_appservice_kakaotalk -g` to generate an appservice registration file, and update your homeserver configuration to accept it
## Running manually
1. In the `node` directory, launch the node-kakao module with `node src/main.js`
1. In the project root directory, run the bridge module with `python -m matrix_appservice_kakaotalk`
1. Start a chat with the bot and use the `login <email>` command to sync your KakaoTalk account
* Note that on first use, you must enter a verification code on a smartphone version of KakaoTalk in order for the login to complete
## systemd
Coming soon!
## Upgrading
Simply `git pull` or `git rebase` the latest changes and rerun any installation commands (`npm install`, `pip install -Ur ...`).
# Docker
Coming soon!

4
node/README.md Normal file
View File

@ -0,0 +1,4 @@
### Listen config
If `type` is `unix`, `path` is the path where to create the socket.
If `type` is `tcp`, `port` and `host` are the host/port where to listen.