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 documentation to learn what it does and why it might be useful to you. You can also take a look at this demonstration video.

Adjusting DNS records (optional)

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.

If you wish to adjust it, see the section below for details about DNS configuration.

Adjusting the playbook 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

Adjusting the Heisenbridge URL (optional)

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 vars.yml file:

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

If you've changed the default hostname, you may need to create a CNAME record for the Heisenbridge domain (heisenbridge.example.com), which targets matrix.example.com.

When setting, replace example.com with your own.

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

To use the bridge, you need to start a chat with @heisenbridge:example.com (where example.com is your base domain, not the matrix. domain). 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.