cqrenet/matrix-docker-ansible-deploy
3
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2026-04-25 09:57:35 +00:00
Code Issues Wiki Activity

Add MatrixMeshtasticRelay (#4840)

Browse Source 
* Add Matrix <-> Meshtastic bridge (meshtastic-matrix-relay)

Vendors the meshtastic-matrix-relay (mmrelay) role into roles/custom/
following the conventions used by other bridge roles.

Co-authored-by: luschmar <90399580+luschmar@users.noreply.github.com>

* Add docs and CHANGELOG entry for Matrix <-> Meshtastic bridge

Co-authored-by: luschmar <90399580+luschmar@users.noreply.github.com>

---------

Co-authored-by: Slavi Pantaleev <slavi@devture.com>
This commit is contained in:
luschmar
2026-04-24 09:31:18 +02:00
committed by GitHub
parent 2949e0931f
commit 243b4d0fd9
13 changed files with 542 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
roles/custom/matrix-bridge-meshtastic-relay/defaults/main.yml Normal file
View File

@@ -0,0 +1,198 @@
# SPDX-FileCopyrightText: 2025 - 2026 luschmar
# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
# matrix-meshtastic-relay is a Matrix <-> Meshtastic bridge.
# Project source code URL: https://github.com/jeremiah-k/meshtastic-matrix-relay
matrix_meshtastic_relay_enabled: true
# renovate: datasource=docker depName=jeremiah-k/mmrelay packageName=ghcr.io/jeremiah-k/mmrelay
matrix_meshtastic_relay_version: 1.2.8
matrix_meshtastic_relay_container_image: "{{ matrix_meshtastic_relay_container_image_registry_prefix }}jeremiah-k/mmrelay:{{ matrix_meshtastic_relay_version }}"
matrix_meshtastic_relay_container_image_registry_prefix: "{{ matrix_meshtastic_relay_container_image_registry_prefix_upstream }}"
matrix_meshtastic_relay_container_image_registry_prefix_upstream: "{{ matrix_meshtastic_relay_container_image_registry_prefix_upstream_default }}"
matrix_meshtastic_relay_container_image_registry_prefix_upstream_default: "ghcr.io/"
matrix_meshtastic_relay_container_image_force_pull: "{{ matrix_meshtastic_relay_container_image.endswith(':latest') }}"
matrix_meshtastic_relay_base_path: "{{ matrix_base_data_path }}/meshtastic-relay"
matrix_meshtastic_relay_config_path: "{{ matrix_meshtastic_relay_base_path }}/config"
matrix_meshtastic_relay_data_path: "{{ matrix_meshtastic_relay_base_path }}/data"
matrix_meshtastic_relay_logs_path: "{{ matrix_meshtastic_relay_base_path }}/logs"
matrix_meshtastic_relay_container_network: ""
matrix_meshtastic_relay_container_additional_networks: "{{ matrix_meshtastic_relay_container_additional_networks_auto + matrix_meshtastic_relay_container_additional_networks_custom }}"
matrix_meshtastic_relay_container_additional_networks_auto: []
matrix_meshtastic_relay_container_additional_networks_custom: []
# A list of extra arguments to pass to the container
matrix_meshtastic_relay_container_extra_arguments: []
# List of systemd services that matrix-meshtastic-relay.service depends on.
matrix_meshtastic_relay_systemd_required_services_list: "{{ matrix_meshtastic_relay_systemd_required_services_list_default + matrix_meshtastic_relay_systemd_required_services_list_auto + matrix_meshtastic_relay_systemd_required_services_list_custom }}"
matrix_meshtastic_relay_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
matrix_meshtastic_relay_systemd_required_services_list_auto: []
matrix_meshtastic_relay_systemd_required_services_list_custom: []
# List of systemd services that matrix-meshtastic-relay.service wants
matrix_meshtastic_relay_systemd_wanted_services_list: []
# Hostname of the Matrix homeserver the bot connects to.
matrix_meshtastic_relay_matrix_host: ""
# URL of the Matrix homeserver the bot connects to.
matrix_meshtastic_relay_matrix_homeserver_url: "https://{{ matrix_meshtastic_relay_matrix_host }}"
# Fully-qualified Matrix ID of the bot user.
matrix_meshtastic_relay_matrix_bot_user_id: "@meshtasticbot:{{ matrix_meshtastic_relay_matrix_host }}"
# Password for the bot's Matrix account.
# On first startup, mmrelay uses this to log in and persist credentials (including E2EE
# material) under `{{ matrix_meshtastic_relay_data_path }}`. After that, the password
# can (and should) be cleared from configuration.
matrix_meshtastic_relay_matrix_bot_password: ""
# Controls whether End-to-End Encryption is enabled.
# Requires password-based login on first start so that mmrelay can create `credentials.json`.
matrix_meshtastic_relay_e2ee_enabled: true
# Connection type to the Meshtastic device. One of: "tcp", "serial", "ble".
matrix_meshtastic_relay_connection_type: ""
# For `tcp` connection type: hostname/IP of the Meshtastic device to connect to.
matrix_meshtastic_relay_tcp_host: "meshtastic.local"
# For `serial` connection type: path of the serial device to connect to.
# This device is passed through to the container. The host must have it available.
matrix_meshtastic_relay_serial_port: "/dev/ttyUSB0"
# For `ble` connection type: BLE MAC address of the Meshtastic device to connect to.
# BLE requires `--network=host` and a DBus bind-mount (see the systemd service template).
matrix_meshtastic_relay_ble_address: "AA:BB:CC:DD:EE:FF"
# Display name of the Meshtastic network.
matrix_meshtastic_relay_meshnet_name: "MediumFast"
# Whether relaying from Matrix to Meshtastic is enabled.
matrix_meshtastic_relay_meshtastic_broadcast_enabled: true
# Matrix rooms to bridge to Meshtastic channels.
# Each entry should have an `id` (Matrix room alias or room ID) and a `meshtastic_channel`.
matrix_meshtastic_relay_matrix_rooms_list:
- id: "#meshtastic:{{ matrix_meshtastic_relay_matrix_host }}"
meshtastic_channel: "0"
# Whether plugins should only respond when the bot is explicitly mentioned.
matrix_meshtastic_relay_plugin_global_require_bot_mention: true
# Enabled built-in ("core") plugins.
# See: https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki/Core-Plugins
matrix_meshtastic_relay_plugins_ping_enabled: true
matrix_meshtastic_relay_plugins_health_enabled: true
matrix_meshtastic_relay_plugins_weather_enabled: true
matrix_meshtastic_relay_plugins_weather_units: metric
matrix_meshtastic_relay_plugins_telemetry_enabled: true
matrix_meshtastic_relay_plugins_map_enabled: true
matrix_meshtastic_relay_plugins_nodes_enabled: true
# Default configuration passed to the bridge via config.yaml.
# See `../templates/config.yaml.j2` for what's rendered.
# Use `matrix_meshtastic_relay_configuration_extension_yaml` to override
# specific values or add/remove keys without having to maintain a full copy here.
matrix_meshtastic_relay_configuration_default:
matrix:
homeserver: "{{ matrix_meshtastic_relay_matrix_homeserver_url }}"
password: "{{ matrix_meshtastic_relay_matrix_bot_password }}"
bot_user_id: "{{ matrix_meshtastic_relay_matrix_bot_user_id }}"
e2ee:
enabled: "{{ matrix_meshtastic_relay_e2ee_enabled }}"
store_path: /app/data/store
matrix_rooms: "{{ matrix_meshtastic_relay_matrix_rooms_list }}"
meshtastic: "{{ matrix_meshtastic_relay_meshtastic_configuration }}"
logging:
level: info
log_to_file: false
database:
path: /app/data/meshtastic.sqlite
enable_wal: true
busy_timeout_ms: 5000
pragmas:
synchronous: NORMAL
temp_store: MEMORY
msg_map:
msgs_to_keep: 500
wipe_on_restart: true
plugins:
require_bot_mention: "{{ matrix_meshtastic_relay_plugin_global_require_bot_mention }}"
ping:
active: "{{ matrix_meshtastic_relay_plugins_ping_enabled }}"
health:
active: "{{ matrix_meshtastic_relay_plugins_health_enabled }}"
weather:
active: "{{ matrix_meshtastic_relay_plugins_weather_enabled }}"
units: "{{ matrix_meshtastic_relay_plugins_weather_units }}"
telemetry:
active: "{{ matrix_meshtastic_relay_plugins_telemetry_enabled }}"
map:
active: "{{ matrix_meshtastic_relay_plugins_map_enabled }}"
nodes:
active: "{{ matrix_meshtastic_relay_plugins_nodes_enabled }}"
# Connection-type-specific `meshtastic` configuration block used by
# `matrix_meshtastic_relay_configuration_default`.
matrix_meshtastic_relay_meshtastic_configuration: |
{{
(
{'connection_type': 'tcp', 'host': matrix_meshtastic_relay_tcp_host}
if matrix_meshtastic_relay_connection_type == 'tcp' else
(
{'connection_type': 'serial', 'serial_port': matrix_meshtastic_relay_serial_port}
if matrix_meshtastic_relay_connection_type == 'serial' else
(
{'connection_type': 'ble', 'ble_address': matrix_meshtastic_relay_ble_address}
if matrix_meshtastic_relay_connection_type == 'ble' else {}
)
)
) | combine({
'meshnet_name': matrix_meshtastic_relay_meshnet_name,
'broadcast_enabled': matrix_meshtastic_relay_meshtastic_broadcast_enabled,
'message_interactions': {
'reactions': false,
'replies': false,
},
})
}}
# Holds additional configuration values that get merged into the default
# configuration (see `matrix_meshtastic_relay_configuration_default`).
#
# If you need something more special, you can take full control by changing
# `matrix_meshtastic_relay_configuration` directly.
matrix_meshtastic_relay_configuration_extension_yaml: |
# Your custom YAML configuration goes here.
# This configuration extends the default starting configuration (`matrix_meshtastic_relay_configuration_default`).
#
# You can override individual variables from the default configuration, or introduce new ones.
#
# If you need something more special, you can take full control by
# redefining `matrix_meshtastic_relay_configuration` directly.
matrix_meshtastic_relay_configuration_extension: "{{ matrix_meshtastic_relay_configuration_extension_yaml | from_yaml if matrix_meshtastic_relay_configuration_extension_yaml | from_yaml is mapping else {} }}"
# Holds the final configuration rendered to `config.yaml`.
# Normally, you don't need to change this variable — use
# `matrix_meshtastic_relay_configuration_extension_yaml` instead.
matrix_meshtastic_relay_configuration: "{{ matrix_meshtastic_relay_configuration_default | combine(matrix_meshtastic_relay_configuration_extension, recursive=True) }}"
# matrix_meshtastic_relay_restart_necessary controls whether the service
# will be restarted (when true) or merely started (when false) by the
# systemd service manager role (when conditional restart is enabled).
#
# This value is automatically computed during installation based on whether
# any configuration files, the systemd service file, or the container image changed.
# The default of `false` means "no restart needed" — appropriate when the role's
# installation tasks haven't run (e.g., due to --tags skipping them).
matrix_meshtastic_relay_restart_necessary: false

25
roles/custom/matrix-bridge-meshtastic-relay/tasks/main.yml Normal file
View File

@@ -0,0 +1,25 @@
# SPDX-FileCopyrightText: 2025 - 2026 luschmar
# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
- tags:
- setup-all
- setup-meshtastic-relay
- install-all
- install-meshtastic-relay
block:
- when: matrix_meshtastic_relay_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
- when: matrix_meshtastic_relay_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
- tags:
- setup-all
- setup-meshtastic-relay
block:
- when: not matrix_meshtastic_relay_enabled | bool
ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"

63
roles/custom/matrix-bridge-meshtastic-relay/tasks/setup_install.yml Normal file
View File

@@ -0,0 +1,63 @@
# SPDX-FileCopyrightText: 2025 - 2026 luschmar
# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
- name: Ensure matrix-meshtastic-relay image is pulled
community.docker.docker_image:
name: "{{ matrix_meshtastic_relay_container_image }}"
source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
force_source: "{{ matrix_meshtastic_relay_container_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_meshtastic_relay_container_image_force_pull }}"
register: matrix_meshtastic_relay_container_image_pull_result
retries: "{{ devture_playbook_help_container_retries_count }}"
delay: "{{ devture_playbook_help_container_retries_delay }}"
until: matrix_meshtastic_relay_container_image_pull_result is not failed
- name: Ensure matrix-meshtastic-relay paths exist
ansible.builtin.file:
path: "{{ item }}"
state: directory
mode: '0750'
owner: "{{ matrix_user_name }}"
group: "{{ matrix_group_name }}"
with_items:
- "{{ matrix_meshtastic_relay_base_path }}"
- "{{ matrix_meshtastic_relay_config_path }}"
- "{{ matrix_meshtastic_relay_data_path }}"
- "{{ matrix_meshtastic_relay_logs_path }}"
- name: Ensure matrix-meshtastic-relay config.yaml is installed
ansible.builtin.copy:
content: "{{ matrix_meshtastic_relay_configuration | to_nice_yaml(indent=2, width=999999) }}"
dest: "{{ matrix_meshtastic_relay_config_path }}/config.yaml"
mode: '0600'
owner: "{{ matrix_user_name }}"
group: "{{ matrix_group_name }}"
register: matrix_meshtastic_relay_config_result
- name: Ensure matrix-meshtastic-relay container network is created
community.general.docker_network:
enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
name: "{{ matrix_meshtastic_relay_container_network }}"
driver: bridge
driver_options: "{{ devture_systemd_docker_base_container_networks_driver_options }}"
when: "matrix_meshtastic_relay_connection_type != 'ble'"
- name: Ensure matrix-meshtastic-relay.service installed
ansible.builtin.template:
src: "{{ role_path }}/templates/systemd/matrix-meshtastic-relay.service.j2"
dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-meshtastic-relay.service"
mode: '0644'
register: matrix_meshtastic_relay_systemd_service_result
- name: Determine whether matrix-meshtastic-relay needs a restart
ansible.builtin.set_fact:
matrix_meshtastic_relay_restart_necessary: >-
{{
matrix_meshtastic_relay_config_result.changed | default(false)
or matrix_meshtastic_relay_systemd_service_result.changed | default(false)
or matrix_meshtastic_relay_container_image_pull_result.changed | default(false)
}}

25
roles/custom/matrix-bridge-meshtastic-relay/tasks/setup_uninstall.yml Normal file
View File

@@ -0,0 +1,25 @@
# SPDX-FileCopyrightText: 2025 - 2026 luschmar
# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
- name: Check existence of matrix-meshtastic-relay service
ansible.builtin.stat:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-meshtastic-relay.service"
register: matrix_meshtastic_relay_service_stat
- when: matrix_meshtastic_relay_service_stat.stat.exists | bool
block:
- name: Ensure matrix-meshtastic-relay is stopped
ansible.builtin.service:
name: matrix-meshtastic-relay
state: stopped
enabled: false
daemon_reload: true
- name: Ensure matrix-meshtastic-relay.service doesn't exist
ansible.builtin.file:
path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-meshtastic-relay.service"
state: absent

23
roles/custom/matrix-bridge-meshtastic-relay/tasks/validate_config.yml Normal file
View File

@@ -0,0 +1,23 @@
# SPDX-FileCopyrightText: 2025 - 2026 luschmar
# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
#
# SPDX-License-Identifier: AGPL-3.0-or-later
---
- name: Fail if required matrix-meshtastic-relay settings not defined
ansible.builtin.fail:
msg: >-
You need to define a required configuration setting (`{{ item.name }}`).
when: "item.when | bool and lookup('vars', item.name, default='') | string | length == 0"
with_items:
- {'name': 'matrix_meshtastic_relay_matrix_host', when: true}
- {'name': 'matrix_meshtastic_relay_matrix_bot_password', when: true}
- {'name': 'matrix_meshtastic_relay_connection_type', when: true}
- name: Fail if matrix_meshtastic_relay_connection_type is invalid
ansible.builtin.fail:
msg: >-
`matrix_meshtastic_relay_connection_type` must be one of: `tcp`, `serial`, `ble`.
Got: `{{ matrix_meshtastic_relay_connection_type }}`.
when: "matrix_meshtastic_relay_connection_type not in ['tcp', 'serial', 'ble']"

59
roles/custom/matrix-bridge-meshtastic-relay/templates/systemd/matrix-meshtastic-relay.service.j2 Normal file
View File

@@ -0,0 +1,59 @@
#jinja2: lstrip_blocks: True
[Unit]
Description=Matrix <-> Meshtastic bridge
{% for service in matrix_meshtastic_relay_systemd_required_services_list %}
Requires={{ service }}
After={{ service }}
{% endfor %}
{% for service in matrix_meshtastic_relay_systemd_wanted_services_list %}
Wants={{ service }}
{% endfor %}
DefaultDependencies=no
[Service]
Type=simple
Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
ExecStartPre=-{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-meshtastic-relay
ExecStartPre=-{{ devture_systemd_docker_base_host_command_docker }} rm matrix-meshtastic-relay
ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
--rm \
--name=matrix-meshtastic-relay \
--log-driver=none \
--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
--cap-drop=ALL \
--read-only \
--tmpfs=/tmp:rw,noexec,nosuid,size=50m \
--tmpfs=/.cache:rw,noexec,nosuid,size=50m \
--mount type=bind,src={{ matrix_meshtastic_relay_config_path }}/config.yaml,dst=/app/config.yaml,ro \
--mount type=bind,src={{ matrix_meshtastic_relay_data_path }},dst=/app/data \
--mount type=bind,src={{ matrix_meshtastic_relay_logs_path }},dst=/app/logs \
{% if matrix_meshtastic_relay_connection_type == 'ble' %}
--network=host \
--security-opt apparmor=unconfined \
--mount type=bind,src=/var/run/dbus,dst=/var/run/dbus,ro \
{% else %}
--network={{ matrix_meshtastic_relay_container_network }} \
{% endif %}
{% if matrix_meshtastic_relay_connection_type == 'serial' %}
--device={{ matrix_meshtastic_relay_serial_port }} \
{% endif %}
{% for arg in matrix_meshtastic_relay_container_extra_arguments %}
{{ arg }} \
{% endfor %}
{{ matrix_meshtastic_relay_container_image }}
{% for network in matrix_meshtastic_relay_container_additional_networks %}
ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-meshtastic-relay
{% endfor %}
ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-meshtastic-relay
ExecStop=-{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-meshtastic-relay
ExecStop=-{{ devture_systemd_docker_base_host_command_docker }} rm matrix-meshtastic-relay
Restart=always
RestartSec=30
SyslogIdentifier=matrix-meshtastic-relay
[Install]
WantedBy=multi-user.target

4
roles/custom/matrix-bridge-meshtastic-relay/templates/systemd/matrix-meshtastic-relay.service.j2.license Normal file
View File

@@ -0,0 +1,4 @@
SPDX-FileCopyrightText: 2025 - 2026 luschmar
SPDX-FileCopyrightText: 2026 Slavi Pantaleev
SPDX-License-Identifier: AGPL-3.0-or-later