twoifbysea
send notifications about events with ease
About
twoifbysea is a server that receives messaging requests from clients. The goals for the project are:
- Rapid development for clients, abstracting the annoying details of messaging away
- Supporting a variety of messaging channels
Installation
To install PyPI dependencies, run:
$ pip install -r /path/to/twoifbysea/requirements.txt
Troubleshooting pycrypto installation
If you see an error message such as:
blake2/blake2module.c:1:20: fatal error: Python.h: No such file or directory
#include <Python.h>
^
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
----------------------------------------
Cleaning up...
Command /usr/bin/python -c "import setuptools,
tokenize;__file__='/tmp/pip-build-Br8maE/blake2/setup.py';exec(compile(getattr(tokenize,
'open', open)(__file__).read().replace('\r\n', '\n'), __file__,
'exec'))" install --record /tmp/pip-EL6ID6-record/install-record.txt
--single-version-externally-managed --compile failed with error code 1
in /tmp/pip-build-Br8maE/blake2
This may indicate that you are lacking important source code files for Python-based development. This can be rectified for some Linux distributions by running:
$ apt-get update && apt-get install python-dev
Usage
Clients must connect to the server using a supported connection mechanism; currently, only HTTP is supported. (Please create a GitHub issue to request additional connectors.) Once started, the server can then service client requests to send notifications. The notification script must be scheduled as a cron job to clear the queue.
Starting the webserver
Currently the only connector available for the server is via HTTP. The webserver that receives and processes notification requests can be started as follows:
$ cd /path/to/twoifbysea/master ; make start
Scheduling the notification daemon
Notification requests by clients are added to a queue and will be sent when the notify.py script is run. To regularly empty the queue, this script should be run as a cron job. The notify.py script takes no arguments and will find the queue database file on its own using the appdir Python module.
Ex.:
Send queued notifications every 5 minutes:
5 * * * * /path/to/twoifbysea/master/twoifbysea/notify.py
Client examples
See the examples/ directory for general and Python-specific examples of connecting to the notification server.
Logs
Check the twoifbysea.log file for error messages, such as those concerning missing environment variables for notification credentials. The location of this log file is determined by the (appdirs)[https://pypi.python.org/pypi/appdirs/1.4.3] Python module:
MacOS: ~/Library/Application Support/twoifbysea/twoifbysea.log
Windows (non-roaming profiles): C:\Documents and Settings<User>\Application Data\Local Settings\atlas\twoifbysea\twoifbysea.log
Windows (roaming profiles): C:\Documents and Settings<User>\Application Data\atlas\twoifbysea\twoifbysea.log
Linux: ~/.local/share/twoifbysea/twoifbysea.log
Project cleaning
To delete the notification database (primarily for development purposes), use:
$ cd /path/to/twoifbysea/master/twoifbysea ; make clean
Supported communication channels
- Email (unencrypted, GMail only)
- Telegram bot (unencrypted)
Important TODOs
- Add support for daily digest messages
- Add negative notifications (e.g. "no new messages for app-x today, all is good")
- Allow Python clients to initiate delivery of some or all types of messages without running a listening server
- Implement generic email accounts apart from GMail (need to figure out some spam filtering stuff)
- Add new communication channels, such as PGP-encrypted emails, Slack channels, etc.
- Refactor to minimize client footprint
- Create packaged installer for server