matrix-appservice-kakaotalk/SETUP.md

• Manual setup
  • systemd
• 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/python/optional-dependencies.html#all-python-bridges

Initial setup

node-kakao module

1. cd to the node directory and run npm install
2. Copy node/example-config.json to node/config.json
3. Edit node/config.json with desired settings (see 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
2. Install Python requirements:
   • pip install -Ur requirements.txt for base functionality
   • pip install -Ur optional-requirements.txt for end-to-bridge 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
3. 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
4. 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
2. In the project root directory, run the bridge module with python -m matrix_appservice_kakaotalk
3. 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 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:

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
2. 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/
     2. Create the services' configuration directory with sudo mkdir /etc/matrix-appservice-kakaotalk
     3. 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
     2. Create the services' configuration directory with mkdir $XDG_CONFIG_HOME/matrix-appservice-kakaotalk
3. Copy/link the bridge & node-kakao module configuration files to the services' configuration directory as config.yaml and node-config.json, respectively
4. 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 for details.
• All configuration files created by the Docker containers will be chowned 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
2. 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
3. cd to the node directory, and build the image for the Node module with docker build . -t matrix-appservice-kakaotalk-node
4. 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
5. Update the generated config file config.json to your liking
6. Run the Node module with docker run --restart unless-stopped -v $(pwd):/data:z matrix-appservice-kakaotalk-node
7. Open a new shell, since the prior docker run command runs in the foreground (unless -d is used)
8. cd to the repository root, and build the image for the bridge module with docker build . -t matrix-appservice-kakaotalk
9. 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
10. 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>
11. Generate the appservice registration by running the container again, and update your homeserver configuration to accept it
12. 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.