imap-feeder

= imap-feeder

imap-feeder tracks your favorite RSS and Atom feeds and stores new entries on your IMAP server, so you can read them with your favorite mail reader or even a webmail client.

== Prerequisites

To use this software, you'll need a system to run the script in a certain interval and a compatible IMAP account.

=== Dependencies

imap-feeder needs the following gems, if they are not already present on your system, they'll get installed:

• actionmailer
• hpricot
• htmlentities
• tidy
• simple-rss

The tidy gem doesn't contain libtidy, you need to install it separately using your package manager. Depending on your system, this can be done like:

• Gentoo: emerge app-text/htmltidy
• Debian: aptitude install libtidy-ruby

=== Compatible IMAP Servers

I use imap-feeder with Courier-IMAP and Dovecot. Other IMAP servers should work as well, but I haven't tested them. If you can run it successfully with another server, please drop me a note so I can update this README.

== Installation

You may get the latest stable version from Rubyforge:

$ gem install imap-feeder

To run imap-feeder, you'll need a configuration file, another one to hold a list of all your feeds' urls and a temporary file to hold state information about the processed feeds.

I personally put them all in a hidden directory in my home:

$ mkdir ~/.imap-feeder && cd !$

Now we need a list of all the urls of the blogs you want imap-feeder to check. Run imap-feeder -n to create an empty file or with the name of an OPML file as argument. For example, the following creates the "feeds.yml" file with all the feeds from "feeds.opml" and uses the "feeds" folder as root in your inbox to store them all. Each feed will get its own folder under the "feeds" root. (If you just want to evaluate imap-feeder, I'd recommend to operate it on a dedicated mailbox, so you can easily get rid of it afterwards if you don't like it.)

$ imap-feeder -n feeds.opml -r feeds

If you omit the name of an opml-file, you'll get a sample file with two feeds in it and you can simply add your feeds by hand.

Please edit the settings.rb-file now accordingly to the instructions in it. You have to change at least the imap connection strings and likely the BASEDIR constant too.

You can now run imap-feeder -c feeds.yml to check the configuration. After that, we can run imap-feeder with the settings.rb file as argument.

$ imap-feeder ~/.imap-feeder/settings.rb

I recommend to use absolute paths to avoid trouble. If everything works, the script should generate some folders on your IMAP server and fetch the first round of feeds. If you are happy with the results, you can run the script regularly, for example using cron.

== Check Configuration

Imap feeder can check your feeds file for validity with regards to IMAP folder names and connectivity to the webservers. Use the -c FEEDS_FILE option to run the check and watch the output for errors and warnings.

== Troubleshooting

This section hopefully helps dealing with common problems that you might encounter.

=== Already running

If you're getting an error about imap-feeder "already running", this means that imap-feeder either really is still running or it crashed during the last run and couldn't clean up properly. In the last case, just remove the running_instance file and rerun it.

=== OPML file

The OPML import is not very well tested, it should certainly work with Akregator's OPML files. If it doesn't work for you, don't hesitate to contact me and send me your OPML file.

=== Crashes

If imap-feeder crashes with a stacktrace, take a look at the log file for more information. You might also want to raise the log level, see the settings file for instructions.

== Comments

Thank you for using imap-feeder and don't forget to drop me an email if you have feature requests or bugs to report.