finallycoffee/matrix-docker-ansible-deploy

Slavi Pantaleev e46ba5deba Add matrix-appservice-kakaotalk support

Adds support for: https://src.miscworks.net/fair/matrix-appservice-kakaotalk

This is pretty similar to
https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1977
which just appeared, but has mostly been done independently.

I've taken some inspiration and did some fixups based on that PR.
Thanks to https://github.com/hnarjis for taking the time to contribute!

Notable differences between this branch compared to that PR:

- better naming and documentation around the "configuration" variables
- no unnecessary (5 sec.) intentional delay when starting `matrix-appservice-kakaotalk-node.service`
- stores configuration in `config/`, not in `data/`
- passes configuration as read-only and starts the bridge with (`--no-update`) to ensure no changes are made to it
- starts containers more securely - with `matrix:matrix` user:group (not `root`) and
  reduced capabilities (`--cap-drop=ALL`)
- uses `tcp` for communication between the "node" and the appservice (simpler than sharing unix sockets)
- `registration.yaml` which is closer to the one generated by `matrix-appservice-kakaotalk` (no `de.sorunome.msc2409.push_ephemeral` stuff, etc.)
- `registration.yaml` which is more customizable (customizable bot username and prefix for puppets - see `matrix_appservice_kakaotalk_appservice_bot_username` and `matrix_appservice_kakaotalk_user_prefix`)
- less fragile and more extensible bridge permissions configuration via `matrix_appservice_kakaotalk_bridge_permissions`. Doing `{% if matrix_admin %}` in the bridge configuration sometimes causes syntax problems (I hit some myself) and is not ideal. Other bridges should be redone as well.
- configurable command prefix for the bridge, instead of hardcoding `!kt` (see `matrix_appservice_kakaotalk_command_prefix`)
- logging that is more consistent with the rest of the playbook (console / journald only, no logging to files), as well as configurable log level (via `matrix_appservice_kakaotalk_logging_level`)
- somewhat more detailed documentation (`docs/configuring-playbook-bridge-appservice-kakaotalk.md`)
- removed some dead code (data relocation tasks from `tasks/setup_install.yml`, as well as likely unnecessary SQLite -> Postgres migration)

2022-07-25 16:01:15 +03:00

4.0 KiB

Raw Blame History

Setting up Appservice Kakaotalk (optional)

The playbook can install and configure matrix-appservice-kakaotalk for you. matrix-appservice-kakaotalk is a bridge to Kakaotalk based on node-kakao (now unmaintained) and some mautrix-facebook code.

See the project's documentation to learn what it does and why it might be useful to you.

Installing

To enable the bridge, add this to your vars.yml file:

matrix_appservice_kakaotalk_enabled: true

You may optionally wish to add some Additional configuration, or to prepare for double-puppeting before the initial installation.

After adjusting your vars.yml file, re-run the playbook and restart all services: ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

To make use of the Kakaotalk bridge, see Usage below.

Additional configuration

There are some additional things you may wish to configure about the bridge.

Take a look at:

roles/matrix-bridge-appservice-kakaotalk/defaults/main.yml for some variables that you can customize via your vars.yml file
roles/matrix-bridge-appservice-kakaotalk/templates/config.yaml.j2 for the bridge's default configuration. You can override settings using the matrix_appservice_kakaotalk_configuration_extension_yaml variable

Here's some example configuration (which goes into your vars.yml file):

# This configuration:
# - enables encryption (it's off by default)
# - grants some user on your homeserver 'admin' access to the bridge
#   (note: the user specified in the `matrix_admin` (part of `roles/matrix-base/defaults/main.yml`) is made an admin by default)
matrix_appservice_kakaotalk_configuration_extension_yaml: |
  bridge:
    permissions:
      '@YOUR_USERNAME:{{ matrix_domain }}': admin

    encryption:
      allow: true
      default: true

Set up Double Puppeting

If you'd like to use Double Puppeting (hint: you most likely do), you have 2 ways of going about it.

Method 1: automatically, by enabling Shared Secret Auth

The bridge will automatically perform Double Puppeting if you enable Shared Secret Auth for this playbook.

This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.

Method 2: manually, by asking each user to provide a working access token

Note: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see Usage).

When using this method, each user that wishes to enable Double Puppeting needs to follow the following steps:

retrieve a Matrix access token for yourself. You can use the following command:

curl \
--data '{"identifier": {"type": "m.id.user", "user": "YOUR_MATRIX_USERNAME" }, "password": "YOUR_MATRIX_PASSWORD", "type": "m.login.password", "device_id": "Appservice-Kakaotalk", "initial_device_display_name": "Appservice-Kakaotalk"}' \
https://matrix.DOMAIN/_matrix/client/r0/login

send the access token to the bot. Example: login-matrix MATRIX_ACCESS_TOKEN_HERE
make sure you don't log out the Appservice-Kakaotalk device some time in the future, as that would break the Double Puppeting feature

Usage

Start a chat with @kakaotalkbot:YOUR_DOMAIN (where YOUR_DOMAIN is your base domain, not the matrix. domain).

Send login --save EMAIL_OR_PHONE_NUMBER to the bridge bot to enable bridging for your Kakaotalk account. The --save flag may be omitted, if you'd rather not save your password.

After successfully enabling bridging, you may wish to set up Double Puppeting, if you haven't already done so.

4.0 KiB Raw Blame History