7.6 KiB
7.6 KiB
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
cd
to thenode
directory and runnpm install
- Copy
node/example-config.json
tonode/config.json
- Edit
node/config.json
with desired settings (see node/README.md for details)
Bridge module
cd
to the repository root and create a Python virtual environment withpython3 -m venv .venv
, and enter it withsource .venv/bin/activate
- Install Python requirements:
pip install -Ur requirements.txt
for base functionalitypip 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
- Copy
matrix_appservice_kakaotalk/example-config.yaml
toconfig.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 innode/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
- In particular, be sure to set the
- Run
python -m matrix_appservice_kakaotalk -g
to generate an appservice registration file, and update your homeserver configuration to accept it
Running manually
- In the
node
directory, launch the node-kakao module withnode src/main.js
- In the project root directory, run the bridge module with
python -m matrix_appservice_kakaotalk
- 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 modulematrix-appservice-kakao-node.service
for the node-kakao module
To use them as-is, follow these steps after initial setup:
- 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
- Install the services as either system or user units
- To install as system units:
- Copy/link the service files to a directory in the system unit search path, such as
/etc/systemd/system/
- Create the services' configuration directory with
sudo mkdir /etc/matrix-appservice-kakaotalk
- RECOMMENDED: Create the
matrix-appservice-kakaotalk
user on your system withadduser
or an equivalent command, then uncomment theUser
andGroup
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
- If creating this user, also give it write permissions on the services' configuration directory with
- Copy/link the service files to a directory in the system unit search path, such as
- To install as user units:
- Copy/link the service files to a directory in the user unit search path, such as
~/.config/systemd/user
- Create the services' configuration directory with
mkdir $XDG_CONFIG_HOME/matrix-appservice-kakaotalk
- Copy/link the service files to a directory in the user unit search path, such as
- To install as system units:
- Copy/link the bridge & node-kakao module configuration files to the services' configuration directory as
config.yaml
andnode-config.json
, respectively - 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 withsudo
unless you have configured your system otherwise. See Docker docs for details. - All configuration files created by the Docker containers will be
chown
ed to UID/GID 1337. Usesudo
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
cd
to the directory where you cloned this repository- Ensure that the repository root and
node
directories are writable by UID/GID 1337. A coarse way to achieve this is withchmod o+w . node
cd
to thenode
directory, and build the image for the Node module withdocker build . -t matrix-appservice-kakaotalk-node
- 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
- Update the generated config file
config.json
to your liking - Run the Node module with
docker run --restart unless-stopped -v $(pwd):/data:z matrix-appservice-kakaotalk-node
- Open a new shell, since the prior
docker run
command runs in the foreground (unless-d
is used) cd
to the repository root, and build the image for the bridge module withdocker build . -t matrix-appservice-kakaotalk
- 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
- 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 setrpc.connection.path: /data/node/<sockname>
- Note that the Node module container's
- Generate the appservice registration by running the container again, and update your homeserver configuration to accept it
- 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.
- Additionally, you should either add the bridge to the same Docker network as your homeserver and database with
Upgrading
Simply git pull
or git rebase
the latest changes, rerun all docker build
commands, then run new containers for the freshly-built images.