author Andy Chung <>
Wed, 09 Jun 2010 12:35:10 -0700
changeset 1771 71d667333774e6a08558eff9e5615df9721210cb
parent 1725 c02ab4cf34a8eabfa466ceaf20aa153b887a645c
permissions -rw-r--r--
couple changes to inflow

 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

 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

 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.


See 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


Install couchdb, version 0.11 or later.  0.10 and earlier will not work.  See: for most platforms. for Windows. 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


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

Execute the '' 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 ' --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 reports everything is in order, the next step is to
set up the accounts to use with raindrop, then have raindrop fetch the

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

configure raindrop:
  * edit ~/.raindrop

  * if your 'local' couchdb isn't on localhost, add a section along the lines

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

  * Add gmail accounts along the lines of

  * Add twitter accounts along the lines of

  * Add imap accounts along the lines of

  * Add skype accounts along the lines of

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 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:

  % 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 ' --help' for more

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:

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:

  % 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 '' 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
script), the techniques described below are still the current best-practices.

When 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:

  % 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.


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

  % 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:

  % 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

  % ./