docs/INSTALL
author Andy Chung <andy@mozillamessaging.com>
Tue, 13 Jul 2010 12:01:59 -0700
changeset 1787 42b1a25c3061
parent 1725 c02ab4cf34a8
permissions -rw-r--r--
trying a click out of box technique for closing conversations, also trying out some collapsed view stuff
 ***** BEGIN LICENSE BLOCK *****
 Version: MPL 1.1

 The contents of this file are subject to the Mozilla Public License Version
 1.1 (the "License"); you may not use this file except in compliance with
 the License. You may obtain a copy of the License at
 http://www.mozilla.org/MPL/

 Software distributed under the License is distributed on an "AS IS" basis,
 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 for the specific language governing rights and limitations under the
 License.

 The Original Code is Raindrop.

 The Initial Developer of the Original Code is
 Mozilla Messaging, Inc..
 Portions created by the Initial Developer are Copyright (C) 2009
 the Initial Developer. All Rights Reserved.

 Contributor(s):


See http://wiki.mozilla.org/Raindrop/Install for the latest and most
up-to-date installation documentation.

Late Breaking News/Known Problems
=================================

* You may see warnings regarding timeout or "too many connection" errors from
  your IMAP server.  These errors can generally be ignored as raindrop should
  recover correctly from such errors.


Installation Steps
==================

couchdb
-------

Install couchdb, version 0.11 or later.  0.10 and earlier will not work.  See:
  http://couchdb.apache.org/downloads.html for most platforms.
  http://wiki.apache.org/couchdb/Windows_binary_installer for Windows.
  http://janl.github.com/couchdbx for a pre-built binary for Macs.

When building couchdb from source, it can be run without installing via a 
'dev' install:
  cd couchdb; ./bootstrap && ./configure && make && make dev
  ./utils/run

raindrop
--------

Install Python 2.5 or 2.6 (note that Python 3 is not yet supported).

Execute the 'check-raindrop.py' script in the server/python directory.  
This should check all dependencies and let you know what you are missing, 
then check your couchdb for certain configuration requirements.

If you are brave, try executing 'check-raindrop.py --configure' (prefixing
that command with 'sudo ' on some platforms).  This will attempt to 
automatically install all dependencies necessary and configure couchdb.

If you are less brave, run it without the --configure option, then manually
resolve any dependency or configuration issues it reports, then repeat until
no problems are found.

A summary of the dependencies are: setuptools, Skype4Py, twitter, simplejson 
and feedparser.

Running Raindrop
================

After check-raindrop.py reports everything is in order, the next step is to
set up the accounts to use with raindrop, then have raindrop fetch the
messages:

Manually configure raindrop
---------------------------

These steps should become less necessary as time moves forward (it will be
possible in the future to do this work through a web interface), but for now,
you need to set up the accounts you want to use in raindrop via a .raindrop
file:

configure raindrop:
  * edit ~/.raindrop

  * if your 'local' couchdb isn't on localhost, add a section along the lines
    of:
        [couch-local]
        host=hostname
        port=port

  Add one new section per account; note the "account-" prefix is important
  when defining accounts:

  * Add gmail accounts along the lines of
        [account-gmail-username]
        proto=imap
        kind=gmail
        username=username@gmail.com
        password=topsecret
        ssl=True

  * Add twitter accounts along the lines of
        [account-twitter-username]
        proto=twitter
        kind=twitter
        username=username
        password=topsecret

  * Add imap accounts along the lines of
        [account-imap-username]
        proto=imap
        kind=imap
        host=imap.example.com
        port=993
        username=username
        password=topsecret
        ssl=True

  * Add skype accounts along the lines of
        [account-skype-username]
        proto=skype
        kind=skype
        username=username
        password=topsecret

Note the use of passwords in this file and that we recognize this is evil; we
now support OAuth for services which support it - currently twitter and 
gmail IMAP - but the problem remains for most IMAP servers out there.  
Raindrop only stores this information on the file-system and it is never 
exposed via couchdb, so even if people can get to your couchdb installation 
via HTTP, they should be unable to obtain your credentials.

Please see http://wiki.mozilla.org/Raindrop/Security for our current thoughts
on this.

Once you are done with .raindrop, then go to the command line, to the
raindrop/server/python directory and run the following command:

  % run-raindrop.py sync-messages --max-age=5days 

It will take a few minutes for run-raindrop to complete. The above command
gets the last 5 days of messages for each account configured above. If you
have a huge amount of mail and would like to restrict things even more, the
--folder option may be of use - execute 'run-raindrop.py --help' for more
details.

Once the above command finishes (or even while it is running - the messages
should start appearing fairly quickly), then open your favorite Firefox or
WebKit-based browser and go to:

http://127.0.0.1:5984/raindrop/inflow/index.html

You should see some of your messages displayed.  If you are viewing messages
while raindrop is still synchronizing, currently you must manually refresh the
page to see these new items.

Note that the raindrop back-end must be running for 'outgoing' actions (such
as sending an SMTP message, adjusting the 'seen' state of an IMAP message) to
be operated on.  If you execute:

  % run-raindrop.py process --continuous

The back-end will sit there waiting for new items to be written to the
database and process them, including requests to send SMTP etc.  You must
terminate this process with Ctrl+C.

There are many issues with the UI and how messages are processed, but
hopefully you now have a feel for how raindrop works.

Manually controlling raindrop
-----------------------------

The 'run-raindrop.py' script is capable of fetching messages, re-running 
extensions, etc.  Although we are moving this functionality to a couchdb
external so it can be controlled by the front-end (see the couch-raindrop.py
script), the techniques described below are still the current best-practices.

When run-raindrop.py is executed, it always checks to see if the accounts
and other documents required by raindrop (eg, the front-end applications)
are up to date, then performs the requested operation, then terminates.  If 
no operation is requested a web-browser pointing at raindrop will be opened.
This means you can edit any of the files in the 'schema', 'client' or 
'couch_doc' directories, then see those changes reflected in the front-end 
when run-raindrop is next started.  We don't detect the changes while we
are running though, only at startup.

Get messages from all accounts:

  % run-raindrop.py sync-messages --max-age=2days --folder=inbox

Both --max-age and --folder are optional - see --help for details.  Reload the
front-end applications to see the messages as they arrive.

Unprocessing:

To delete all the intermediate messages in the DB, execute:

  % run-raindrop.py unprocess

The next time you execute a 'process' command, all your messages will
be reprocessed.

Error handling:

If there is an error during a 'process' operation (ie, an exception in the
converter), we will write an 'error document' and continue processing the
work queue.  We don't make a very loud noise at the end when this happens -
you need to notice it in the log output as it is running.  At any time you
can execute:

  % run-raindrop.py retry-errors

To re-process those messages - but this will generally result in exactly the
same error unless the converter has been fixed to deal with the condition
causing the error.  Alternatively, execute 'unprocess' to force reprocessing
of all messages, not only those which previously caused an error.

  See --help for more.

Testing Raindrop
----------------

Test everything using the test suite

  % ./test-raindrop.py