Andrew Ferrazzutti
f47bcd3f0c
- Add .dockerignore files - Make default Node config force-overwrite its socket file - puppet.sock -> rpc.sock - Warn against starting bridge module before node module
100 lines
7.6 KiB
Markdown
100 lines
7.6 KiB
Markdown
* [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.8
|
|
* Node 16.13 (not yet tested with earlier versions)
|
|
* postgresql 11 or sqlite3
|
|
* 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`
|
|
* If using Postgres as your database, create a new database that can be accessed via the URI you set for it in `appservice.database`
|
|
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
|
|
The [systemd](systemd) directory provides sample service unit configuration files for running the bridge & node-kakao modules:
|
|
|
|
* `matrix-appservice-kakao.service` for the bridge module
|
|
* `matrix-appservice-kakao-node.service` for the node-kakao module
|
|
|
|
To use them as-is, follow these steps after [initial setup](#initial-setup):
|
|
|
|
1. Place/link your clone of this repository in `/opt/matrix-appservice-kakaotalk`
|
|
* If moving your repo directory after having already created a Python virtual environment for the bridge module, re-create the virtual environment after moving to ensure its paths are up-to-date
|
|
* Alternatively, clone it to `/opt/matrix-appservice-kakaotalk` in the first place
|
|
1. Install the services as either system or user units
|
|
* To install as system units:
|
|
1. Copy/link the service files to a directory in the system unit search path, such as `/etc/systemd/system/`
|
|
1. Create the services' configuration directory with `sudo mkdir /etc/matrix-appservice-kakaotalk`
|
|
1. RECOMMENDED: Create the `matrix-appservice-kakaotalk` user on your system with `adduser` or an equivalent command, then uncomment the `User` and `Group` lines in the service files
|
|
* If creating this user, also give it write permissions on the services' configuration directory with `chgrp matrix-appservice-kakaotalk /etc/matrix-appservice-kakaotalk && chmod g+w /etc/matrix-appservice-kakaotalk`
|
|
* To install as user units:
|
|
1. Copy/link the service files to a directory in the user unit search path, such as `~/.config/systemd/user`
|
|
1. Create the services' configuration directory with `mkdir $XDG_CONFIG_HOME/matrix-appservice-kakaotalk`
|
|
1. Copy/link the bridge & node-kakao module configuration files to the services' configuration directory as `config.yaml` and `node-config.json`, respectively
|
|
1. Start the services now and on every boot boot with `[sudo] systemd [--user] enable --now matrix-appservice-kakaotalk{,-node}`
|
|
|
|
## Upgrading
|
|
Simply `git pull` or `git rebase` the latest changes and rerun any installation commands (`npm install`, `pip install -Ur ...`).
|
|
|
|
# Docker
|
|
These instructions describe how to run the bridge with Docker containers.
|
|
|
|
## Notes
|
|
* Any `docker` commands mentioned below need to be run with `sudo` unless you have configured your system otherwise. See [Docker docs](https://docs.docker.com/engine/install/linux-postinstall/) for details.
|
|
* All configuration files created by the Docker containers will be `chown`ed to UID/GID 1337. Use `sudo` access on the host to edit them.
|
|
* The `docker` commands below mount the working directory as `/data`, so make sure you always run them in the correct directory.
|
|
|
|
## Limitations
|
|
* Images must be built manually for now. It is planned for there to be prebuilt images available to pull.
|
|
|
|
## Initial setup
|
|
1. `cd` to the directory where you cloned this repository
|
|
1. Ensure that the repository root and `node` directories are writable by UID/GID 1337. A coarse way to achieve this is with `chmod o+w . node`
|
|
1. `cd` to the `node` directory, and build the image for the Node module with `docker build . -t matrix-appservice-kakaotalk-node`
|
|
1. Run a container for the Node module for the first time, so it can create a config file for you: `docker run --rm -v $(pwd):/data:z matrix-appservice-kakaotalk-node`
|
|
1. Update the generated config file `config.json` to your liking
|
|
1. Run the Node module with `docker run --restart unless-stopped -v $(pwd):/data:z matrix-appservice-kakaotalk-node`
|
|
1. Open a new shell, since the prior `docker run` command runs in the foreground (unless `-d` is used)
|
|
1. `cd` to the repository root, and build the image for the bridge module with `docker build . -t matrix-appservice-kakaotalk`
|
|
1. Run a container for the bridge module for the first time, so it can create a config file for you: `docker run --rm -v $(pwd):/data:z matrix-appservice-kakaotalk`
|
|
1. Update the generated config file `config.yaml` to your liking. You'll at least need to change the homeserver settings, appservice address and permissions, and the rpc connection to the Node module
|
|
* Note that the Node module container's `/data/` directory is accessible in the bridge module's container at `/data/node/`
|
|
* Thus, if the Node module is configured to use a unix socket at `/data/<sock_name>`, the bridge module's config must set `rpc.connection.path: /data/node/<sockname>`
|
|
1. Generate the appservice registration by running the container again, and update your homeserver configuration to accept it
|
|
1. Run the bridge module with `docker run --restart unless-stopped -v $(pwd):/data:z matrix-appservice-kakaotalk`
|
|
* Additionally, you should either add the bridge to the same Docker network as your homeserver and database with `--network=<name>` (when they are running in Docker), or expose the correct port(s) with `-p <port>:<port>` or `--network=host` (when they are running outside Docker).
|
|
* If the Node module is configured to use a unix socket, make sure to start the bridge module's container _after_ the Node module's container. Otherwise, the bridge module may not be able to find the socket file.
|
|
|
|
## Upgrading
|
|
Simply `git pull` or `git rebase` the latest changes, rerun all `docker build` commands, then run new containers for the freshly-built images.
|