Metadata-Version: 1.1
Name: community-mailbot
Version: 0.1.0
Summary: Friendly mail forwarding bot for community.lsst.org
Home-page: https://github.com/lsst-sqre/community_mailbot
Author: Jonathan Sick
Author-email: jsick@lsst.org
License: MIT
Description: =================
        community_mailbot
        =================
        
        The ``community_mailbot`` is a friendly bot that tells subscribers to LSST DM's legacy Mailman email lists about things happening on `community.lsst.org <http://community.lsst.org>`_.
        
        The bot likes to be awakened regularly by ``cron``; each time it will ask the Discourse server about latest messages in different categories that the bot tracks (you can set this with a simple ``config.json`` file).
        If there is are new topics, ``community_mailbot`` will send an email to the appropriate email lists using its buddy, `Mandrill <http://mandrillapp.com>`_.
        Before the bot goes back to sleep, it keeps note of all the topics it's emailed already in a simple JSON cache file.
        
        Installation
        ------------
        
        Create a virtual environment running Python 3.5, then:
        
        .. code-block:: bash
        
           pip install git+https://github.com/lsst-sqre/community_mailbot.git@tickets/DM-3690
        
        Running the community mailbot
        -----------------------------
        
        Keys to the Kingdom
        ~~~~~~~~~~~~~~~~~~~
        
        You'll need to get API keys from community.lsst.org and Mandrill.
        Set them to the following environment variables:
        
        * ``$MANDRILL_KEY`` (note, use the API key for the ``community_mailbot`` subaccount)
        * ``$DISCOURSE_KEY`` (the Discourse key should correspond to a user with sufficient permissions)
        * ``$DISCOURSE_USER``
        
        Optionally set ``$COMMUNITY_MAILBOT_CACHE`` to the location where you want the Mailbot to keep track of its topics it has forwarded.
        
        Setup Topic → Email Mapping
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        To setup how Discourse categories are mapped to recipient email addresses, you need to know the integer IDs for each relevant category.
        To get these, run the included script:
        
        .. code-block:: bash
        
           discourse_categories
        
        If you set the aforementioned environment variables, you won't need to provide any arguments to the script.
        
        Next, create a ``config.json`` file.
        It's a simple hash structure; each key-value pair is the Discourse category ID and a list of email recipients for that category.
        The general format is:
        
        .. code-block:: json
        
           {
               "<id>": [{"email": "<email address>",
                         "name": "<recipient name>",
                         "type": "to"}],
           }
        
        The structure of the ``dict`` in the value matches the `Mandrill send-template API`_.
        The ``"type"`` field should typically be ``"to"``, but could also be ``"cc"`` or ``"bcc"``.
        
        .. _`Mandrill send-template API`: https://mandrillapp.com/api/docs/messages.python.html#method-send-template
        
        Note that since the recipient information for each category is a ``list``, you can have multiple recipients.
        
        Pre-cache old topics
        ~~~~~~~~~~~~~~~~~~~~
        
        Before having the bot send emails, you'll want it to know about and ignore older messages.
        To warm up the cache, we'll run the ``forward_discourse`` script with the ``--cache-only`` option.
        
        .. code-block:: bash
        
           forward_discourse config.json --cache-only
        
        Note that ``forward_discourse`` can configure itself with the environment variables you've already setup.
        Run ``forward_discourse --help`` for the full set of options.
        
        Set up a cron schedule
        ~~~~~~~~~~~~~~~~~~~~~~
        
        The bot works best when it regularly monitors a Discourse site for new topics.
        ``cron`` is a great way to set this up.
        
        It's useful to create a shell script to contain all of the script arguments.
        For example, create a script called ``run_mailbot.sh``:
        
        .. code-block:: bash
        
           #!/bin/bash
           source /home/ec2-user/.bash_profile
           source activate community_mailbot
           forward_discourse /home/ec2-user/config.json
        
           echo "$(date) Ran forward_discourse"
        
        This script sets up up the shell environment, loads a Python environment, and then runs the mailbot.
        
        Then instruct ``cron`` to run this script every 10 minutes
        
        First, open the ``crontab`` in your terminal
        
        .. code-block:: bash
        
           crontab -e
        
        And add a line for the bot
        
        .. code-block:: bash
        
            */10 * * * * /home/ec2-user/run_mailbot.sh
        
        Then sit back and watch the email flow.
        
        Development
        -----------
        
        To develop on the ``community_mailbot``, you'll need to clone the repository and install a development copy (preferably in a ``virtualenv``):
        
        .. code-block:: bash
        
           git clone https://github.com/lsst-sqre/community_mailbot.git
           cd community_mailbot
           python setup.py develop
        
        To run the test suite:
        
        .. code-block:: bash
        
            python -m unittest discover -s community_mailbot/tests
        
        
        Rough Spots
        -----------
        
        The ``community_mailbot`` is meant to be fairly general and usable for any Discourse installation.
        
        *However*, beware that the Mandrill email template information is current hard-coded.
        Ideally this would be user-configurable.
        
        
        License
        -------
        
        Copyright 2015 AURA/LSST.
        
        MIT licensed; see ``LICENSE`` file.
        
Keywords: astronomy discourse email
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3.5
