Merge pull request #1052 from hifi/feature/heisenbridge

Add Heisenbridge

README.md

@@ -67,6 +67,8 @@ Using this playbook, you can get the following services configured on your serve
 
 - (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
 
+- (optional) the [Heisenbridge](https://github.com/hifi/heisenbridge) for bridging your Matrix server to IRC bouncer-style - see [docs/configuring-playbook-bridge-heisenbridge.md](docs/configuring-playbook-bridge-heisenbridge.md) for setup documentation
+
 - (optional) the [mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-mx-puppet-skype.md](docs/configuring-playbook-bridge-mx-puppet-skype.md) for setup documentation
 
 - (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation

docs/configuring-playbook-bridge-heisenbridge.md

@@ -0,0 +1,34 @@
+# Setting up Heisenbridge (optional)
+
+The playbook can install and configure [Heisenbridge](https://github.com/hifi/heisenbridge) - the bouncer-style IRC bridge for you.
+
+See the project's [README](https://github.com/hifi/heisenbridge/blob/master/README.md) to learn what it does and why it might be useful to you.
+
+## Configuration
+
+Below are the common configuration options that you may want to set, exhaustive list is in [the bridge's defaults var file](../roles/matrix-bridge-heisenbridge/defaults/main.yml).
+
+At a minimum, you only need to enable the bridge to get it up and running (`inventory/host_vars/matrix.DOMAIN/vars.yml`):
+
+```yaml
+matrix_heisenbridge_enabled: true
+
+# set owner (optional)
+matrix_heisenbridge_owner: "@you:your-homeserver"
+
+# to enable identd on host port 113/TCP (optional)
+matrix_heisenbridge_identd_enabled: true
+```
+
+That's it! A registration file is automatically generated during the setup phase.
+
+Setting the owner is optional as the first local user to DM `@heisenbridge:your-homeserver` 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.
+
+## Usage
+
+After the bridge is successfully running just DM `@heisenbridge:your-homeserver` to start setting it up.
+Help is available for all commands with the `-h` switch.
+If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
+
+If you encounter issues or feel lost you can join the project room at [#heisenbridge:vi.fi](https://matrix.to/#/#heisenbridge:vi.fi) for help.

docs/configuring-playbook.md

@@ -126,6 +126,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Matrix SMS bridging](configuring-playbook-bridge-matrix-bridge-sms.md) (optional)
 
+- [Setting up Heisenbridge bouncer-style IRC bridging](configuring-playbook-bridge-heisenbridge.md) (optional)
+
 
 ### Bots
 

group_vars/matrix_servers

@@ -488,6 +488,32 @@ matrix_sms_bridge_homeserver_token: "{{ matrix_synapse_macaroon_secret_key | pas
 #
 ######################################################################
 
+######################################################################
+#
+# matrix-bridge-heisenbridge
+#
+######################################################################
+
+# We don't enable bridges by default.
+matrix_heisenbridge_enabled: false
+
+matrix_heisenbridge_appservice_token: "{{ matrix_synapse_macaroon_secret_key | password_hash('sha512', 'heisen.as.tok') | to_uuid }}"
+
+matrix_heisenbridge_homeserver_token: "{{ matrix_synapse_macaroon_secret_key | password_hash('sha512', 'heisen.hs.tok') | to_uuid }}"
+
+matrix_heisenbridge_systemd_wanted_services_list: |
+  {{
+    (['matrix-synapse.service'] if matrix_synapse_enabled else [])
+    +
+    (['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
+  }}
+
+######################################################################
+#
+# /matrix-bridge-heisenbridge
+#
+######################################################################
+
 ######################################################################
 #
 # matrix-bridge-mx-puppet-skype

roles/matrix-bridge-heisenbridge/defaults/main.yml

@@ -0,0 +1,47 @@
+# heisenbridge is a bouncer-style Matrix IRC bridge
+# See: https://github.com/hifi/heisenbridge
+
+matrix_heisenbridge_enabled: true
+
+matrix_heisenbridge_version: latest
+matrix_heisenbridge_docker_image: "{{ matrix_container_global_registry_prefix }}hif1/heisenbridge:{{ matrix_heisenbridge_version }}"
+matrix_heisenbridge_docker_image_force_pull: "{{ matrix_heisenbridge_docker_image.endswith(':latest') }}"
+
+# Set this to your Matrix ID if you want to enforce the owner, otherwise first _local_ user becomes one
+matrix_heisenbridge_owner: ""
+
+# Enabling identd will bind to host port 113/TCP
+matrix_heisenbridge_identd_enabled: false
+
+matrix_heisenbridge_base_path: "{{ matrix_base_data_path }}/heisenbridge"
+
+# A list of extra arguments to pass to the container
+matrix_heisenbridge_container_extra_arguments: []
+
+# List of systemd services that service depends on.
+matrix_heisenbridge_systemd_required_services_list: ['docker.service']
+
+# List of systemd services that service wants
+matrix_heisenbridge_systemd_wanted_services_list: []
+
+matrix_heisenbridge_homeserver_url: "{{ matrix_homeserver_container_url }}"
+
+matrix_heisenbridge_appservice_token: ''
+matrix_heisenbridge_homeserver_token: ''
+
+# Default registration file
+matrix_heisenbridge_registration_yaml:
+  id: heisenbridge
+  url: http://matrix-heisenbridge:9898
+  as_token: "{{ matrix_heisenbridge_appservice_token }}"
+  hs_token: "{{ matrix_heisenbridge_homeserver_token }}" 
+  rate_limited: false
+  sender_localpart: heisenbridge
+  namespaces:
+    users:
+    - regex: '@hbirc_.*'
+      exclusive: true
+    aliases: []
+    rooms: []
+
+matrix_heisenbridge_registration: "{{ matrix_heisenbridge_registration_yaml|from_yaml }}"

roles/matrix-bridge-heisenbridge/tasks/init.yml

@@ -0,0 +1,24 @@
+# If the matrix-synapse role is not used, `matrix_synapse_role_executed` won't exist.
+# We don't want to fail in such cases.
+- name: Fail if matrix-synapse role already executed
+  fail:
+    msg: >-
+      The matrix-bridge-heisenbridge role needs to execute before the matrix-synapse role.
+  when: "matrix_heisenbridge_enabled and matrix_synapse_role_executed|default(False)"
+
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-heisenbridge.service'] }}"
+  when: matrix_heisenbridge_enabled|bool
+
+# If the matrix-synapse role is not used, these variables may not exist.
+- set_fact:
+    matrix_synapse_container_extra_arguments: >
+      {{ matrix_synapse_container_extra_arguments|default([]) }}
+      +
+      ["--mount type=bind,src={{ matrix_heisenbridge_base_path }}/registration.yaml,dst=/heisenbridge-registration.yaml,ro"]
+
+    matrix_synapse_app_service_config_files: >
+      {{ matrix_synapse_app_service_config_files|default([]) }}
+      +
+      {{ ["/heisenbridge-registration.yaml"] }}
+  when: matrix_heisenbridge_enabled|bool

roles/matrix-bridge-heisenbridge/tasks/main.yml

@@ -0,0 +1,15 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/setup_install.yml"
+  when: "run_setup|bool and matrix_heisenbridge_enabled|bool"
+  tags:
+    - setup-all
+    - setup-heisenbridge
+
+- import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+  when: "run_setup|bool and not matrix_heisenbridge_enabled|bool"
+  tags:
+    - setup-all
+    - setup-heisenbridge

roles/matrix-bridge-heisenbridge/tasks/setup_install.yml

@@ -0,0 +1,38 @@
+---
+
+- name: Ensure heisenbridge image is pulled
+  docker_image:
+    name: "{{ matrix_heisenbridge_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_heisenbridge_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}" 
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_heisenbridge_docker_image_force_pull }}" 
+
+- name: Ensure heisenbridge paths exist
+  file:
+    path: "{{ item }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - "{{ matrix_heisenbridge_base_path }}"
+
+- name: Ensure heisenbridge registration.yaml installed if provided
+  copy:
+    content: "{{ matrix_heisenbridge_registration|to_nice_yaml }}"
+    dest: "{{ matrix_heisenbridge_base_path }}/registration.yaml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
+- name: Ensure matrix-heisenbridge.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-heisenbridge.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-heisenbridge.service"
+    mode: 0644
+  register: matrix_heisenbridge_systemd_service_result
+
+- name: Ensure systemd reloaded after matrix-heisenbridge.service installation
+  service:
+    daemon_reload: yes
+  when: matrix_heisenbridge_systemd_service_result.changed

roles/matrix-bridge-heisenbridge/tasks/setup_uninstall.yml

@@ -0,0 +1,24 @@
+---
+
+- name: Check existence of matrix-heisenbridge service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-heisenbridge.service"
+  register: matrix_heisenbridge_service_stat
+
+- name: Ensure matrix-heisenbridge is stopped
+  service:
+    name: heisenbridge
+    state: stopped
+    daemon_reload: yes
+  when: "matrix_heisenbridge_service_stat.stat.exists"
+
+- name: Ensure matrix-heisenbridge.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-heisenbridge.service"
+    state: absent
+  when: "matrix_heisenbridge_service_stat.stat.exists"
+
+- name: Ensure systemd reloaded after matrix-heisenbridge.service removal
+  service:
+    daemon_reload: yes
+  when: "matrix_heisenbridge_service_stat.stat.exists"

roles/matrix-bridge-heisenbridge/templates/systemd/matrix-heisenbridge.service.j2

@@ -0,0 +1,50 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=a bouncer-style Matrix IRC bridge
+{% for service in matrix_heisenbridge_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_heisenbridge_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_docker }} kill matrix-heisenbridge
+ExecStartPre=-{{ matrix_host_command_docker }} rm matrix-heisenbridge
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-heisenbridge \
+          --log-driver=none \
+          --user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+          --cap-drop=ALL \
+          --network={{ matrix_docker_network }} \
+          {% if matrix_heisenbridge_identd_enabled %}
+          -p 113:113 \
+          {% endif %}
+          -v {{ matrix_heisenbridge_base_path }}:/config:z \
+          {% for arg in matrix_heisenbridge_container_extra_arguments %}
+          {{ arg }} \
+          {% endfor %}
+          {{ matrix_heisenbridge_docker_image }} \
+          {% if matrix_heisenbridge_identd_enabled %}
+          --identd \
+          {% endif %}
+          {% if matrix_heisenbridge_owner %}
+          -o {{ matrix_heisenbridge_owner }} \
+          {% endif %}
+          --config /config/registration.yaml \
+          --listen-address 0.0.0.0 \
+          --listen-port 9898 \
+          {{ matrix_heisenbridge_homeserver_url }}
+
+ExecStop=-{{ matrix_host_command_docker }} kill matrix-heisenbridge
+ExecStop=-{{ matrix_host_command_docker }} rm matrix-heisenbridge
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-heisenbridge
+
+[Install]
+WantedBy=multi-user.target

setup.yml

@@ -32,6 +32,7 @@
     - matrix-bridge-mx-puppet-twitter
     - matrix-bridge-mx-puppet-instagram
     - matrix-bridge-sms
+    - matrix-bridge-heisenbridge
     - matrix-bot-matrix-reminder-bot
     - matrix-bot-go-neb
     - matrix-bot-mjolnir