Add support for matrix-reminder-bot

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

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
 

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).

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)

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

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) }}"

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

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

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"

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"

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

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

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