matrix-docker-ansible-deploy/docs/configuring-playbook-bridge-heisenbridge.md

Setting up Heisenbridge bouncer-style IRC bridging (optional)

Note: bridging to IRC can also happen via the matrix-appservice-irc bridge supported by the playbook.

The playbook can install and configure Heisenbridge - the bouncer-style IRC bridge for you.

See the project's README to learn what it does and why it might be useful to you. You can also take a look at this demonstration video.

Configuration

To enable Heisenbridge, add the following configuration to your inventory/host_vars/matrix.example.com/vars.yml file:

matrix_heisenbridge_enabled: true

# Setting the owner is optional as the first local user to DM `@heisenbridge:example.com` will be made the owner.
# If you are not using a local user you must set it as otherwise you can't DM it at all.
matrix_heisenbridge_owner: "@alice:{{ matrix_domain }}"

# Uncomment to enable identd on host port 113/TCP (optional)
# matrix_heisenbridge_identd_enabled: true

For a more complete list of variables that you could override, see the defaults/main.yml file of the Heisenbridge Ansible role.

Adjusting the Heisenbridge URL

By default, this playbook installs Heisenbridge on the matrix. subdomain, at the /heisenbridge path (https://matrix.example.com/heisenbridge). It would handle media requests there (see the release notes for Heisenbridge v1.15.0).

This makes it easy to install it, because it doesn't require additional DNS records to be set up. If that's okay, you can skip this section.

By tweaking the matrix_heisenbridge_hostname and matrix_heisenbridge_path_prefix variables, you can easily make the service available at a different hostname and/or path than the default one.

Example additional configuration for your inventory/host_vars/matrix.example.com/vars.yml file:

# Change the default hostname and path prefix
matrix_heisenbridge_hostname: heisenbridge.example.com
matrix_heisenbridge_path_prefix: /

Adjusting DNS records

If you've changed the default hostname, you may need to adjust your DNS records to point the Heisenbridge domain to the Matrix server.

See Configuring DNS for details about DNS changes.

If you've decided to use the default hostname, you won't need to do any extra DNS configuration.

Installing

After configuring the playbook and potentially adjusting your DNS records, run the playbook with playbook tags as below:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start

Notes:

• The ensure-matrix-users-created playbook tag makes the playbook automatically create the bot's user account.

• The shortcut commands with the just program are also available: just install-all or just setup-all

  just install-all is useful for maintaining your setup quickly (2x-5x faster than just setup-all) when its components remain unchanged. If you adjust your vars.yml to remove other components, you'd need to run just setup-all, or these components will still remain installed.

Usage

After the bridge is successfully running just DM @heisenbridge:example.com to start setting it up. If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.

Help is available for all commands with the -h switch.

You can also learn the basics by watching this demonstration video.

If you encounter issues or feel lost you can join the project room at #heisenbridge:vi.fi for help.