# Matrix Reminder Bot <a href="https://matrix.to/#/#matrix-reminder-bot:matrix.org"><img src="https://img.shields.io/matrix/matrix-reminder-bot:matrix.org?color=blue&label=Join%20the%20Matrix%20Room&server_fqdn=matrix-client.matrix.org" /></a> <a href="https://hub.docker.com/r/anoa/matrix-reminder-bot/"><img src="https://img.shields.io/docker/v/anoa/matrix-reminder-bot?label=Docker%20Hub&sort=semver" /></a>
A short bot written with [nio-template](https://github.com/anoadragon453/nio-template).
## Features
* Set reminders
* Have the bot remind you or the whole room
* Reminders persist between bot restarts
* Alarms - persistent notifications for a reminder until silenced
* Supports end-to-end encrypted rooms
## Install
matrix-reminder-bot requires
[matrix-nio](https://github.com/matrix-org/matrix-nio), which supports
participation in end-to-end encryption rooms! To do so, it makes use of the
[libolm](https://gitlab.matrix.org/matrix-org/olm) C library. This library
must be installed to allow for end-to-end encryption functionality, and
unfortunately it is *also* required for functional message polling, so it is
practically a hard required for this program.
Unfortunately, installation of this library can be non-trivial on some
platforms. However, with the power of docker, dependencies can be handled with
little fuss, and it is thus the recommended method of installing
`matrix-reminder-bot`. Native installation instructions are also provided, but
be aware that they are more complex.
### Docker
**Recommended.** Follow the docker [installation instructions](docker/README.md#setup).
### Native installation
#### Install libolm
You can install [libolm](https://gitlab.matrix.org/matrix-org/olm) from source,
or alternatively, check your system's package manager. Version `3.0.0` or
greater is required.
**(Optional) postgres development headers**
By default, matrix-reminder-bot uses SQLite as its storage backend. This is
fine for a few hundred users, but if you plan to support a much higher volume
of requests, you may consider using Postgres as a database backend instead.
If you want to use postgres as a database backend, you'll need to install
postgres development headers:
Debian/Ubuntu:
```
sudo apt install libpq-dev libpq5
```
Arch:
```
sudo pacman -S postgresql-libs
```
#### Install Python dependencies
Create and activate a Python 3 virtual environment:
```
virtualenv -p python3 env
source env/bin/activate
```
Install python dependencies:
```
pip install matrix-reminder-bot
```
(Optional) If you want to use postgres as a database backend, use the following
command to install postgres dependencies alongside those that are necessary:
```
pip install "matrix-reminder-bot[postgres]"
```
## Configuration
Copy the sample configuration file to a new `config.yaml` file.
```
cp sample.config.yaml config.yaml
```
Edit the config file. The `matrix` section must be modified at least.
#### (Optional) Set up a Postgres database
Create a postgres user and database for matrix-reminder-bot:
```
sudo -u postgresql psql createuser matrix-reminder-bot -W # prompts for a password
sudo -u postgresql psql createdb -O matrix-reminder-bot matrix-reminder-bot
```
Edit the `storage.database` config option, replacing the `sqlite://...` string with `postgres://...`. The syntax is:
```
database: "postgres://username:password@localhost/dbname?sslmode=disable"
```
See also the comments in `sample.config.yaml`.
## Running
### Docker
Refer to the docker [run instructions](docker/README.md#running).
### Native installation
Make sure to source your python environment if you haven't already:
```
source env/bin/activate
```
Then simply run the bot with:
```
matrix-reminder-bot
```
By default, the bot will run with the config file at `./config.yaml`. However, an
alternative relative or absolute filepath can be specified after the command:
```
matrix-reminder-bot other-config.yaml
```
## Usage
Invite the bot to a room and it should accept the invite and join.
### Setting a reminder
Have the bot ping you in the room about something:
```
!remindme <time>; <reminder text>
```
* `<time>` is a time that can be expressed in natural language. Examples
include "tomorrow at noon", "on thursday at 5pm", "in 1 week", etc.
* `<reminder text>` is the text that the bot will remind you with.
Have the bot ping you and everyone else in the room about something
(assuming the bot has permissions to do so):
```
!remindroom <time>; <reminder text>
```
### Recurring reminders
To create a recurring reminder, put `every` followed by a length of
time, then the time that the reminder should first go off, and then
the reminder text:
```
!remindme every 1w; tuesday; take out the trash
```
```
!remindroom every 5m; 1m; you are loved
```
### Cron-style reminders
If you need more complicated functionality for your reminder's
timing, you can make use of cron tabs. You can read a guide on
cron tabs [here](https://www.adminschoice.com/crontab-quick-reference).
In short they allow you to execute more complicated, recurring
reminders, such as those that should only fire during weekdays.
```
!remindme cron * 9 * * mon-fri; time for the daily stand up
```
The above reminder would fire each weekday at 9:00am.
```
!remindme cron 0/30 9-18 * * mon,wed,fri; take a short break
```
The above reminder would fire every 30 minutes after 9:00am,
until 6:30pm, and only on Monday, Wednesday and Friday.
### List upcoming reminders
```
!listreminders
```
This will output a list of reminders and when they will fire next:
```
sometime Do the dishes (every 1d)
sometime Take out the trash
sometime Send email to Grandma
```
### Cancel a reminder
```
!cancelreminder <reminder text>
```
### Setting an alarm
Alarms are the same as a reminder, but they will repeat every 5 minutes
after firing until they are silenced.
Creating an alarm is the same syntax as creating a reminder, besides a
different command:
```
!alarmme <time>; <reminder text>
```
```
!alarmroom every <recurring time>; <start time>; <reminder text>
```
### Silencing an alarm
An alarm can be silenced with the following command:
```
!silence <reminder text>
```
## Development
Please see [CONTRIBUTING.md](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/anoadragon453/matrix-reminder-bot",
"name": "matrix-reminder-bot",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/5f/49/4940f43ed52f2038a886ee53c10d1b343458eda7cad1b33f6379c3739648/matrix-reminder-bot-0.3.0.tar.gz",
"platform": null,
"description": "# Matrix Reminder Bot <a href=\"https://matrix.to/#/#matrix-reminder-bot:matrix.org\"><img src=\"https://img.shields.io/matrix/matrix-reminder-bot:matrix.org?color=blue&label=Join%20the%20Matrix%20Room&server_fqdn=matrix-client.matrix.org\" /></a> <a href=\"https://hub.docker.com/r/anoa/matrix-reminder-bot/\"><img src=\"https://img.shields.io/docker/v/anoa/matrix-reminder-bot?label=Docker%20Hub&sort=semver\" /></a>\n\n\n\nA short bot written with [nio-template](https://github.com/anoadragon453/nio-template).\n\n## Features\n\n* Set reminders\n* Have the bot remind you or the whole room\n* Reminders persist between bot restarts\n* Alarms - persistent notifications for a reminder until silenced\n* Supports end-to-end encrypted rooms\n\n## Install\n\nmatrix-reminder-bot requires\n[matrix-nio](https://github.com/matrix-org/matrix-nio), which supports\nparticipation in end-to-end encryption rooms! To do so, it makes use of the\n[libolm](https://gitlab.matrix.org/matrix-org/olm) C library. This library\nmust be installed to allow for end-to-end encryption functionality, and\nunfortunately it is *also* required for functional message polling, so it is\npractically a hard required for this program.\n\nUnfortunately, installation of this library can be non-trivial on some\nplatforms. However, with the power of docker, dependencies can be handled with\nlittle fuss, and it is thus the recommended method of installing\n`matrix-reminder-bot`. Native installation instructions are also provided, but\nbe aware that they are more complex.\n\n### Docker\n\n**Recommended.** Follow the docker [installation instructions](docker/README.md#setup).\n\n### Native installation\n\n#### Install libolm\n\nYou can install [libolm](https://gitlab.matrix.org/matrix-org/olm) from source,\nor alternatively, check your system's package manager. Version `3.0.0` or\ngreater is required.\n\n**(Optional) postgres development headers**\n\nBy default, matrix-reminder-bot uses SQLite as its storage backend. This is\nfine for a few hundred users, but if you plan to support a much higher volume\nof requests, you may consider using Postgres as a database backend instead.\n\nIf you want to use postgres as a database backend, you'll need to install\npostgres development headers:\n\nDebian/Ubuntu:\n\n```\nsudo apt install libpq-dev libpq5\n```\n\nArch:\n\n```\nsudo pacman -S postgresql-libs\n```\n\n#### Install Python dependencies\n\nCreate and activate a Python 3 virtual environment:\n\n```\nvirtualenv -p python3 env\nsource env/bin/activate\n```\n\nInstall python dependencies:\n\n```\npip install matrix-reminder-bot\n```\n\n(Optional) If you want to use postgres as a database backend, use the following\ncommand to install postgres dependencies alongside those that are necessary:\n\n```\npip install \"matrix-reminder-bot[postgres]\"\n```\n\n## Configuration\n\nCopy the sample configuration file to a new `config.yaml` file.\n\n```\ncp sample.config.yaml config.yaml\n```\n\nEdit the config file. The `matrix` section must be modified at least.\n\n#### (Optional) Set up a Postgres database\n\nCreate a postgres user and database for matrix-reminder-bot:\n\n```\nsudo -u postgresql psql createuser matrix-reminder-bot -W # prompts for a password\nsudo -u postgresql psql createdb -O matrix-reminder-bot matrix-reminder-bot\n```\n\nEdit the `storage.database` config option, replacing the `sqlite://...` string with `postgres://...`. The syntax is:\n\n```\ndatabase: \"postgres://username:password@localhost/dbname?sslmode=disable\"\n```\n\nSee also the comments in `sample.config.yaml`.\n\n## Running\n\n### Docker\n\nRefer to the docker [run instructions](docker/README.md#running).\n\n### Native installation\n\nMake sure to source your python environment if you haven't already:\n\n```\nsource env/bin/activate\n```\n\nThen simply run the bot with:\n\n```\nmatrix-reminder-bot\n```\n\nBy default, the bot will run with the config file at `./config.yaml`. However, an\nalternative relative or absolute filepath can be specified after the command:\n\n```\nmatrix-reminder-bot other-config.yaml\n```\n\n## Usage\n\nInvite the bot to a room and it should accept the invite and join.\n\n### Setting a reminder\n\nHave the bot ping you in the room about something:\n\n```\n!remindme <time>; <reminder text>\n```\n\n* `<time>` is a time that can be expressed in natural language. Examples\n include \"tomorrow at noon\", \"on thursday at 5pm\", \"in 1 week\", etc.\n* `<reminder text>` is the text that the bot will remind you with.\n\nHave the bot ping you and everyone else in the room about something\n(assuming the bot has permissions to do so):\n\n```\n!remindroom <time>; <reminder text>\n```\n\n### Recurring reminders\n\nTo create a recurring reminder, put `every` followed by a length of\ntime, then the time that the reminder should first go off, and then\nthe reminder text:\n\n```\n!remindme every 1w; tuesday; take out the trash\n```\n\n```\n!remindroom every 5m; 1m; you are loved\n```\n\n### Cron-style reminders\n\nIf you need more complicated functionality for your reminder's\ntiming, you can make use of cron tabs. You can read a guide on\ncron tabs [here](https://www.adminschoice.com/crontab-quick-reference).\n\nIn short they allow you to execute more complicated, recurring\nreminders, such as those that should only fire during weekdays.\n\n```\n!remindme cron * 9 * * mon-fri; time for the daily stand up\n```\n\nThe above reminder would fire each weekday at 9:00am.\n\n```\n!remindme cron 0/30 9-18 * * mon,wed,fri; take a short break\n```\n\nThe above reminder would fire every 30 minutes after 9:00am,\nuntil 6:30pm, and only on Monday, Wednesday and Friday.\n\n### List upcoming reminders\n\n```\n!listreminders\n```\n\nThis will output a list of reminders and when they will fire next:\n\n```\nsometime Do the dishes (every 1d)\nsometime Take out the trash\nsometime Send email to Grandma\n```\n\n### Cancel a reminder\n\n```\n!cancelreminder <reminder text>\n```\n\n### Setting an alarm\n\nAlarms are the same as a reminder, but they will repeat every 5 minutes\nafter firing until they are silenced.\n\nCreating an alarm is the same syntax as creating a reminder, besides a\ndifferent command:\n\n```\n!alarmme <time>; <reminder text>\n```\n\n```\n!alarmroom every <recurring time>; <start time>; <reminder text>\n```\n\n### Silencing an alarm\n\nAn alarm can be silenced with the following command:\n\n```\n!silence <reminder text>\n```\n\n## Development\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "",
"summary": "A matrix bot to remind you about things!",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/anoadragon453/matrix-reminder-bot"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e49bc40896be406ef58b61e15c198729fb1884ee27d9c58b26383df3c1936d33",
"md5": "e4f9d2e39450c78368d571ad0e2a9037",
"sha256": "a89adcfe53cf195ab3ceaabb59a72d09e0ae3133f84d12efda39352b0d457d9a"
},
"downloads": -1,
"filename": "matrix_reminder_bot-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4f9d2e39450c78368d571ad0e2a9037",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28709,
"upload_time": "2024-01-07T18:45:58",
"upload_time_iso_8601": "2024-01-07T18:45:58.972163Z",
"url": "https://files.pythonhosted.org/packages/e4/9b/c40896be406ef58b61e15c198729fb1884ee27d9c58b26383df3c1936d33/matrix_reminder_bot-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5f494940f43ed52f2038a886ee53c10d1b343458eda7cad1b33f6379c3739648",
"md5": "d6f344d2e5e19aa4bb647d77537621c4",
"sha256": "dd6e730a6947ece70ebb57df24ea935b745e7e3a000b70f84a9beb63801cb99a"
},
"downloads": -1,
"filename": "matrix-reminder-bot-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "d6f344d2e5e19aa4bb647d77537621c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 27802,
"upload_time": "2024-01-07T18:46:00",
"upload_time_iso_8601": "2024-01-07T18:46:00.632121Z",
"url": "https://files.pythonhosted.org/packages/5f/49/4940f43ed52f2038a886ee53c10d1b343458eda7cad1b33f6379c3739648/matrix-reminder-bot-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-07 18:46:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anoadragon453",
"github_project": "matrix-reminder-bot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "matrix-reminder-bot"
}
JSON
