Cellphone System Installation And Maintaince

usage guide

Status

Todo:

• str, eq (and weak_eq) should be standardized. they're probably broken wrt inheritance for asker.

General Cellphone System Installation

Check out the cellphone prototype code from the TAM repository

svn co http://www.thoughtandmemory.org/repo/huginmunin/trunk/cellphone/prototype cellphone_src

There are three parts to the code:

1. Main program: Python program for parsing incoming messages (Query objects) and sending replies (Response objects). Delegates actual work to the Information System.

2. Test suite that tests both the core request handler, as well as the incoming mail parser.

3. Optional files for routing mail to the main python script. Other email-to-script or SMS-to-script mechanisms are fine. Please contribute back to this repo if possible :-) email us

Install Python Program

The python application's main is in request_handler.py. It takes an email message from standard input.

You may need to modify the database settings and url variables at the top of request_handler.py.

The script writes logs to ./smsDebug.log, ./smsInfo.log and ./smsError.log. Logging settings may be modified in logging.conf

The meat of the python program lives in the Information System's request handler.

Test Suite

The unit_tests are in the prototype directory.

#!/python
python unit_tests.py

....
----------------------------------------------------------------------
Ran 4 tests in 0.426s

OK

Install Mail Routing w/postfix and procmail

1. You'll need to be running a computer that can receive mail. Specifically, you'll need to use postfix and procmail with a non-virtual user. These instructions assume a *nix OS.

On unix, postfix files are in

/etc/postfix

Check that the user can successfully receive mail.

2. Put the .forward file (or a soft link to it) in the user's home directory. You may need to modify the path to procmail. Type 'which procmail' at the prompt to determine the correct path to procmail.

3. Put the .procmailrc file directly in the user's home directory. Sometimes a soft link worked, but other times the mail logs reported 'suspicious .procmailrc file' and did not pipe mail through. All the other files may be soft links.

.procmailrc sets environment variables for the subprocesses, including the python script. This is another reason why a copy rather than a soft link might be more appropriate for .procmailrc.

Modify the USER environment variable to the name of the user receiving mail. You'd think $USER would work, but alas. ($USER is used in the .forward file, but in a non-critical part, so who knows if it actually works there)

4. Put the rc.query file in the home directory (soft link is fine).

rc.query takes all email messages that are not from a mail daemon and pipes them into request_handler.py.

5. Finally, put the *.py files in the home directory (soft link is fine).

You may need to modify the database settings and url variables at the top of request_handler.py.

Debugging Tips

The server likely logs the receiving and sending of mail in

    /var/log/mail.log
    /var/log/mail.err

Depending on your postfix setup, mail should then be logged in

    /var/spool/mail/<username>
    /home/user/<username>/mbox

Procmail has its own log, which is specified in .procmailrc. If you don't change the defaults this will end up in

    /home/user/<username>/maillog

Install Mail Routing w/gmail

Google's gmail has an API. libgmail is a python binding for this api.

One thought is to run a background python process on the server that continually grabs email from a gmail account and then sends it to request_handler.py.

import libgmail

ga = libgmail.GmailAccount("google@gmail.com", "mymailismypass")
ga.login()
folder = ga.getMessagesByFolder('inbox')

for thread in folder:
  print thread.id, len(thread), thread.subject
  for msg in thread:
    print "  ", msg.id, msg.number, msg.subject
    print msg.source

TAM Cellphone System Setup

The TAM server has two checkouts of the prototype folder:

    /var/sites/cellphone_production

and

    /var/sites/cellphone_staging

These locations are readable by anyone. In cellphone_staging, the database_settings variable is set to /var/sites/hm_staging; in cellphone_production, the database_settings variable is set to /var/sites/hm_demo.

There are currently three users, and thus email recipients, that pipe mail to these locations via soft links in their home directories (/home/<username>/). query has soft links to the files in cellphone_staging; score and cocoa have soft links to the files in cellphone_production.

All users have copies of .procmailrc rather than soft links. Each user modifies the USER environment variable in their local .procmailrc to point to their username.

The advantage of this setup is that there can be multiple email accounts using the same code. This is easier to maintain, and necessary since we keep changing the production email (munin->cocoa->score).

Once a testing framework is in place that can reproduce email input to the python without actually requiring a mail server, it will be easier for developers to work locally.

The desired code flow is as follows:

1. A developer works out of their own local copy, either on their personal machine or on the TAM server. Before checking in she makes sure the code compiles and passes unit test suite. There may one day be release notes to add to; certainly the commit message should say something useful.
2. After checking it in she updates /var/sites/staging. Staging should never be worked out of, so the only diff should be the username in .procmailrc and the database settings variable in request_handler.py. She verifies that sending mail to query works.
3. If the code is release ready, she updates /var/sites/production. Production should never be worked out of. We don't yet have a good local environment setup, so production may need to maintain a diff on the username and database settings variable.