From 78b1ef9a5f9764f9ef54727b0fe81724a1c60d2a Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Mon, 20 Jul 2020 14:13:08 +0300 Subject: [PATCH] Add support for matrix-reminder-bot --- CHANGELOG.md | 9 ++ README.md | 4 + ...guring-playbook-bot-matrix-reminder-bot.md | 59 +++++++++++++ docs/configuring-playbook.md | 5 ++ group_vars/matrix_servers | 17 ++++ .../defaults/main.yml | 64 ++++++++++++++ .../tasks/init.yml | 3 + .../tasks/main.yml | 14 +++ .../tasks/setup.yml | 88 +++++++++++++++++++ .../tasks/validate_config.yml | 10 +++ .../templates/config.yaml.j2 | 50 +++++++++++ .../matrix-bot-matrix-reminder-bot.service.j2 | 40 +++++++++ setup.yml | 1 + 13 files changed, 364 insertions(+) create mode 100644 docs/configuring-playbook-bot-matrix-reminder-bot.md create mode 100644 roles/matrix-bot-matrix-reminder-bot/defaults/main.yml create mode 100644 roles/matrix-bot-matrix-reminder-bot/tasks/init.yml create mode 100644 roles/matrix-bot-matrix-reminder-bot/tasks/main.yml create mode 100644 roles/matrix-bot-matrix-reminder-bot/tasks/setup.yml create mode 100644 roles/matrix-bot-matrix-reminder-bot/tasks/validate_config.yml create mode 100644 roles/matrix-bot-matrix-reminder-bot/templates/config.yaml.j2 create mode 100644 roles/matrix-bot-matrix-reminder-bot/templates/systemd/matrix-bot-matrix-reminder-bot.service.j2 diff --git a/CHANGELOG.md b/CHANGELOG.md index c70dde258..cdc9de1e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ +# 2020-02-20 + +## matrix-reminder-bot support + +The playbook can now help you set up [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot). + +See our [Setting up matrix-reminder-bot](docs/configuring-playbook-bot-matrix-reminder-bot.md) documentation to get started. + + # 2020-07-17 ## (Compatibility Break) Riot is now Element diff --git a/README.md b/README.md index 78a4f83ae..2cfbc6f22 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,8 @@ Using this playbook, you can get the following services configured on your serve - (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform +- (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms + Basically, this playbook aims to get you up-and-running with all the basic necessities around Matrix, without you having to do anything else. **Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need. @@ -180,6 +182,8 @@ This playbook sets up your server using the following Docker images: - [jitsi/jvb](https://hub.docker.com/r/jitsi/jvb) - the [Jitsi](https://jitsi.org/) Video Bridge component (optional) +- [anoa/matrix-reminder-bot](https://hub.docker.com/r/anoa/matrix-reminder-bot) - the [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) bot for one-off & recurring reminders and alarms (optional) + ## Deficiencies diff --git a/docs/configuring-playbook-bot-matrix-reminder-bot.md b/docs/configuring-playbook-bot-matrix-reminder-bot.md new file mode 100644 index 000000000..cb519defb --- /dev/null +++ b/docs/configuring-playbook-bot-matrix-reminder-bot.md @@ -0,0 +1,59 @@ +# Setting up matrix-reminder-bot (optional) + +The playbook can install and configure [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for you. + +It's a bot you can schedule one-off & recurring reminders and alarms with. + +See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage) to learn what it does and why it might be useful to you. + + +## Registering the bot user + +By default, the playbook will set up the bot with a username like this: `@bot.matrix-reminder-bot:DOMAIN`. + +(to a different username, adjust the `matrix_bot_matrix_reminder_bot_matrix_user_id_localpart` variable). + +You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md): + +``` +ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.matrix-reminder-bot password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user +``` + +Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`. + + +## Adjusting the playbook configuration + +Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: + +```yaml +matrix_bot_matrix_reminder_bot_enabled: true + +# Adjust this to whatever password you chose when registering the bot user +matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT + +# Adjust this to your timezone +matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London +``` + + +## Installing + +After configuring the playbook, run the [installation](installing.md) command again: + +``` +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + + +## Usage + +To use the bot, start a chat with `@bot.matrix-reminder-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain). + +You can also add the bot to any existing Matrix room (`/invite @bot.matrix-reminder-bot:DOMAIN`). + +Basic usage is like this: `!remindme in 2 minutes; This is a test` + +Send `!help commands` to the room to see the bot's help menu for additional commands. + +You can also refer to the upstream [Usage documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage). diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 82b3fe61e..06657c704 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -112,3 +112,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Setting up Email2Matrix](configuring-playbook-email2matrix.md) (optional) - [Setting up Matrix SMS bridging](configuring-playbook-matrix-bridge-sms.md) (optional) + + +### Bots + +- [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) (optional) diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index f1a773f59..5820b6b9f 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -516,6 +516,23 @@ matrix_mx_puppet_steam_login_shared_secret: "{{ matrix_synapse_ext_password_prov # ###################################################################### + +###################################################################### +# +# matrix-bot-matrix-reminder-bot +# +###################################################################### + +# We don't enable bots by default. +matrix_bot_matrix_reminder_bot_enabled: false + +###################################################################### +# +# /matrix-bot-matrix-reminder-bot +# +###################################################################### + + ###################################################################### # # matrix-corporal diff --git a/roles/matrix-bot-matrix-reminder-bot/defaults/main.yml b/roles/matrix-bot-matrix-reminder-bot/defaults/main.yml new file mode 100644 index 000000000..92b53c451 --- /dev/null +++ b/roles/matrix-bot-matrix-reminder-bot/defaults/main.yml @@ -0,0 +1,64 @@ +# matrix-reminder-bot is a bot for one-off and recurring reminders +# See: https://github.com/anoadragon453/matrix-reminder-bot + +matrix_bot_matrix_reminder_bot_enabled: true + +matrix_bot_matrix_reminder_bot_docker_image: "anoa/matrix-reminder-bot:release-0.1.0" +matrix_bot_matrix_reminder_bot_docker_image_force_pull: "{{ matrix_bot_matrix_reminder_bot_docker_image.endswith(':latest') }}" + +matrix_bot_matrix_reminder_bot_base_path: "{{ matrix_base_data_path }}/matrix-reminder-bot" +matrix_bot_matrix_reminder_bot_config_path: "{{ matrix_bot_matrix_reminder_bot_base_path }}/config" +matrix_bot_matrix_reminder_bot_data_path: "{{ matrix_bot_matrix_reminder_bot_base_path }}/data" +matrix_bot_matrix_reminder_bot_data_store_path: "{{ matrix_bot_matrix_reminder_bot_data_path }}/store" + +# A list of extra arguments to pass to the container +matrix_bot_matrix_reminder_bot_container_extra_arguments: [] + +# List of systemd services that matrix-bot-matrix-reminder-bot.service depends on +matrix_bot_matrix_reminder_bot_systemd_required_services_list: ['docker.service'] + +# List of systemd services that matrix-bot-matrix-reminder-bot.service wants +matrix_bot_matrix_reminder_bot_systemd_wanted_services_list: [] + + +# The bot's username. This user needs to be created manually beforehand. +# Also see `matrix_bot_matrix_reminder_bot_user_password`. +matrix_bot_matrix_reminder_bot_matrix_user_id_localpart: "bot.matrix-reminder-bot" + +matrix_bot_matrix_reminder_bot_matrix_user_id: '@{{ matrix_bot_matrix_reminder_bot_matrix_user_id_localpart }}:{{ matrix_domain }}' + +# The password that the bot uses to authenticate. +matrix_bot_matrix_reminder_bot_matrix_user_password: '' + +matrix_bot_matrix_reminder_bot_matrix_homeserver_url: '{{ matrix_homeserver_url }}' + +# The timezone to use when creating reminders. +# Examples: 'Europe/London', 'Etc/UTC' +matrix_bot_matrix_reminder_bot_reminders_timezone: '' + +# Default configuration template which covers the generic use case. +# You can customize it by controlling the various variables inside it. +# +# For a more advanced customization, you can extend the default (see `matrix_bot_matrix_reminder_bot_configuration_extension_yaml`) +# or completely replace this variable with your own template. +matrix_bot_matrix_reminder_bot_configuration_yaml: "{{ lookup('template', 'templates/config.yaml.j2') }}" + +matrix_bot_matrix_reminder_bot_configuration_extension_yaml: | + # Your custom YAML configuration goes here. + # This configuration extends the default starting configuration (`matrix_bot_matrix_reminder_bot_configuration_yaml`). + # + # 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 + # completely redefining `matrix_bot_matrix_reminder_bot_configuration_yaml`. + # + # Example configuration extension follows: + # + # matrix: + # device_name: My-Reminder-Bot + +matrix_bot_matrix_reminder_bot_configuration_extension: "{{ matrix_bot_matrix_reminder_bot_configuration_extension_yaml|from_yaml if matrix_bot_matrix_reminder_bot_configuration_extension_yaml|from_yaml is mapping else {} }}" + +# Holds the final configuration (a combination of the default and its extension). +# You most likely don't need to touch this variable. Instead, see `matrix_bot_matrix_reminder_bot_configuration_yaml`. +matrix_bot_matrix_reminder_bot_configuration: "{{ matrix_bot_matrix_reminder_bot_configuration_yaml|from_yaml|combine(matrix_bot_matrix_reminder_bot_configuration_extension, recursive=True) }}" diff --git a/roles/matrix-bot-matrix-reminder-bot/tasks/init.yml b/roles/matrix-bot-matrix-reminder-bot/tasks/init.yml new file mode 100644 index 000000000..9bc471de0 --- /dev/null +++ b/roles/matrix-bot-matrix-reminder-bot/tasks/init.yml @@ -0,0 +1,3 @@ +- set_fact: + matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-bot-matrix-reminder-bot'] }}" + when: matrix_bot_matrix_reminder_bot_enabled|bool diff --git a/roles/matrix-bot-matrix-reminder-bot/tasks/main.yml b/roles/matrix-bot-matrix-reminder-bot/tasks/main.yml new file mode 100644 index 000000000..ade3d1911 --- /dev/null +++ b/roles/matrix-bot-matrix-reminder-bot/tasks/main.yml @@ -0,0 +1,14 @@ +- import_tasks: "{{ role_path }}/tasks/init.yml" + tags: + - always + +- import_tasks: "{{ role_path }}/tasks/validate_config.yml" + when: "run_setup|bool and matrix_bot_matrix_reminder_bot_enabled|bool" + tags: + - setup-all + - setup-bot-matrix-reminder-bot + +- import_tasks: "{{ role_path }}/tasks/setup.yml" + tags: + - setup-all + - setup-bot-matrix-reminder-bot diff --git a/roles/matrix-bot-matrix-reminder-bot/tasks/setup.yml b/roles/matrix-bot-matrix-reminder-bot/tasks/setup.yml new file mode 100644 index 000000000..bc211e310 --- /dev/null +++ b/roles/matrix-bot-matrix-reminder-bot/tasks/setup.yml @@ -0,0 +1,88 @@ +--- + +# +# Tasks related to setting up matrix-reminder-bot +# + +- name: Ensure matrix-reminder-bot paths exist + file: + path: "{{ item.path }}" + state: directory + mode: 0750 + owner: "{{ matrix_user_username }}" + group: "{{ matrix_user_groupname }}" + with_items: + - { path: "{{ matrix_bot_matrix_reminder_bot_config_path }}", when: true } + - { path: "{{ matrix_bot_matrix_reminder_bot_data_path }}", when: true } + - { path: "{{ matrix_bot_matrix_reminder_bot_data_store_path }}", when: true } + when: matrix_bot_matrix_reminder_bot_enabled|bool and item.when + +- name: Ensure matrix-reminder-bot image is pulled + docker_image: + name: "{{ matrix_bot_matrix_reminder_bot_docker_image }}" + source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}" + force_source: "{{ matrix_bot_matrix_reminder_bot_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_bot_matrix_reminder_bot_docker_image_force_pull }}" + when: matrix_bot_matrix_reminder_bot_enabled|bool + +- name: Ensure matrix-reminder-bot config installed + copy: + content: "{{ matrix_bot_matrix_reminder_bot_configuration|to_nice_yaml }}" + dest: "{{ matrix_bot_matrix_reminder_bot_config_path }}/config.yaml" + mode: 0644 + owner: "{{ matrix_user_username }}" + group: "{{ matrix_user_groupname }}" + when: matrix_bot_matrix_reminder_bot_enabled|bool + +- name: Ensure matrix-matrix-reminder-bot.service installed + template: + src: "{{ role_path }}/templates/systemd/matrix-bot-matrix-reminder-bot.service.j2" + dest: "{{ matrix_systemd_path }}/matrix-bot-matrix-reminder-bot.service" + mode: 0644 + register: matrix_bot_matrix_reminder_bot_systemd_service_result + when: matrix_bot_matrix_reminder_bot_enabled|bool + +- name: Ensure systemd reloaded after matrix-matrix-reminder-bot.service installation + service: + daemon_reload: yes + when: "matrix_bot_matrix_reminder_bot_enabled|bool and matrix_bot_matrix_reminder_bot_systemd_service_result.changed" + +# +# Tasks related to getting rid of matrix-reminder-bot (if it was previously enabled) +# + +- name: Check existence of matrix-matrix-reminder-bot service + stat: + path: "{{ matrix_systemd_path }}/matrix-matrix-reminder-bot.service" + register: matrix_bot_matrix_reminder_bot_service_stat + +- name: Ensure matrix-matrix-reminder-bot is stopped + service: + name: matrix-matrix-reminder-bot + state: stopped + daemon_reload: yes + register: stopping_result + when: "not matrix_bot_matrix_reminder_bot_enabled|bool and matrix_bot_matrix_reminder_bot_service_stat.stat.exists" + +- name: Ensure matrix-matrix-reminder-bot.service doesn't exist + file: + path: "{{ matrix_systemd_path }}/matrix-matrix-reminder-bot.service" + state: absent + when: "not matrix_bot_matrix_reminder_bot_enabled|bool and matrix_bot_matrix_reminder_bot_service_stat.stat.exists" + +- name: Ensure systemd reloaded after matrix-matrix-reminder-bot.service removal + service: + daemon_reload: yes + when: "not matrix_bot_matrix_reminder_bot_enabled|bool and matrix_bot_matrix_reminder_bot_service_stat.stat.exists" + +- name: Ensure Matrix matrix-reminder-bot paths don't exist + file: + path: "{{ matrix_bot_matrix_reminder_bot_base_path }}" + state: absent + when: "not matrix_bot_matrix_reminder_bot_enabled|bool" + +- name: Ensure matrix-reminder-bot Docker image doesn't exist + docker_image: + name: "{{ matrix_bot_matrix_reminder_bot_docker_image }}" + state: absent + when: "not matrix_bot_matrix_reminder_bot_enabled|bool" diff --git a/roles/matrix-bot-matrix-reminder-bot/tasks/validate_config.yml b/roles/matrix-bot-matrix-reminder-bot/tasks/validate_config.yml new file mode 100644 index 000000000..983e7166a --- /dev/null +++ b/roles/matrix-bot-matrix-reminder-bot/tasks/validate_config.yml @@ -0,0 +1,10 @@ +--- + +- name: Fail if required settings not defined + fail: + msg: >- + You need to define a required configuration setting (`{{ item }}`). + when: "vars[item] == ''" + with_items: + - "matrix_bot_matrix_reminder_bot_matrix_user_password" + - "matrix_bot_matrix_reminder_bot_reminders_timezone" diff --git a/roles/matrix-bot-matrix-reminder-bot/templates/config.yaml.j2 b/roles/matrix-bot-matrix-reminder-bot/templates/config.yaml.j2 new file mode 100644 index 000000000..e5ba56517 --- /dev/null +++ b/roles/matrix-bot-matrix-reminder-bot/templates/config.yaml.j2 @@ -0,0 +1,50 @@ +# The string to prefix bot commands with +command_prefix: "!" + +# Options for connecting to the bot's Matrix account +matrix: + # The Matrix User ID of the bot account + user_id: {{ matrix_bot_matrix_reminder_bot_matrix_user_id|to_json }} + # Matrix account password + user_password: {{ matrix_bot_matrix_reminder_bot_matrix_user_password|to_json }} + # The public URL at which the homeserver's Client-Server API can be accessed + homeserver_url: {{ matrix_bot_matrix_reminder_bot_matrix_homeserver_url }} + # The device ID that is a **non pre-existing** device + # If this device ID already exists, messages will be dropped silently in + # encrypted rooms + device_id: REMINDER + # What to name the logged in device + device_name: Reminder Bot + +storage: + # The database connection string + # For SQLite3, this would look like: + # database: "sqlite://bot.db" + # For Postgres, this would look like: + # database: "postgres://username:password@localhost/dbname?sslmode=disable" + #database: "postgres://matrix-reminder-bot:remindme@localhost/matrix-reminder-bot?sslmode=disable" + database: "sqlite:///data/bot.db" + # The path to a directory for internal bot storage + # containing encryption keys, sync tokens, etc. + store_path: "/data/store" + +reminders: + # Uncomment to set a default timezone that will be used when creating reminders. + # If not set, UTC will be used + timezone: {{ matrix_bot_matrix_reminder_bot_reminders_timezone }} + +# Logging setup +logging: + # Logging level + # Allowed levels are 'INFO', 'WARNING', 'ERROR', 'DEBUG' where DEBUG is most verbose + level: INFO + # Configure logging to a file + file_logging: + # Whether logging to a file is enabled + enabled: false + # The path to the file to log to. May be relative or absolute + filepath: /data/bot.log + # Configure logging to the console (stdout/stderr) + console_logging: + # Whether console logging is enabled + enabled: true diff --git a/roles/matrix-bot-matrix-reminder-bot/templates/systemd/matrix-bot-matrix-reminder-bot.service.j2 b/roles/matrix-bot-matrix-reminder-bot/templates/systemd/matrix-bot-matrix-reminder-bot.service.j2 new file mode 100644 index 000000000..4220e6cc7 --- /dev/null +++ b/roles/matrix-bot-matrix-reminder-bot/templates/systemd/matrix-bot-matrix-reminder-bot.service.j2 @@ -0,0 +1,40 @@ +#jinja2: lstrip_blocks: "True" +[Unit] +Description=matrix-reminder-bot +{% for service in matrix_bot_matrix_reminder_bot_systemd_required_services_list %} +Requires={{ service }} +After={{ service }} +{% endfor %} +{% for service in matrix_bot_matrix_reminder_bot_systemd_wanted_services_list %} +Wants={{ service }} +{% endfor %} + +[Service] +Type=simple +ExecStartPre=-{{ matrix_host_command_docker }} kill matrix-bot-matrix-reminder-bot +ExecStartPre=-{{ matrix_host_command_docker }} rm matrix-bot-matrix-reminder-bot + +ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-bot-matrix-reminder-bot \ + --log-driver=none \ + --user={{ matrix_user_uid }}:{{ matrix_user_gid }} \ + --cap-drop=ALL \ + --read-only \ + --network={{ matrix_docker_network }} \ + -e 'TZ={{ matrix_bot_matrix_reminder_bot_reminders_timezone }}' \ + -v {{ matrix_bot_matrix_reminder_bot_config_path }}:/config:ro \ + -v {{ matrix_bot_matrix_reminder_bot_data_path }}:/data:rw \ + --entrypoint=/bin/sh \ + {% for arg in matrix_bot_matrix_reminder_bot_container_extra_arguments %} + {{ arg }} \ + {% endfor %} + {{ matrix_bot_matrix_reminder_bot_docker_image }} \ + -c "matrix-reminder-bot /config/config.yaml" + +ExecStop=-{{ matrix_host_command_docker }} kill matrix-bot-matrix-reminder-bot +ExecStop=-{{ matrix_host_command_docker }} rm matrix-bot-matrix-reminder-bot +Restart=always +RestartSec=30 +SyslogIdentifier=matrix-bot-matrix-reminder-bot + +[Install] +WantedBy=multi-user.target diff --git a/setup.yml b/setup.yml index 965fb3c9c..ea5212a67 100755 --- a/setup.yml +++ b/setup.yml @@ -23,6 +23,7 @@ - matrix-bridge-mx-puppet-twitter - matrix-bridge-mx-puppet-instagram - matrix-bridge-sms + - matrix-bot-matrix-reminder-bot - matrix-synapse - matrix-client-element - matrix-jitsi