= growl-atom

A script to monitor Atom feeds and create Growl notitifcations for new entries

== Prerequisites

• Mac OS X, obviously Growl is a Mac app!
• Growl See: http://growl.info
• Incoming connections and remote application registration enabled in Growl
• The growlnoftify application installed See: http://growl.info/extras.php#growlnotify
• Ruby 1.8+, installed by default on Leopard

== Installation

=== Install the growl-atom gem

Run the following if you haven't already:

gem sources -a http://gemcutter.org

Install the gem:

sudo gem install growl-atom

=== Install a local config and LaunchAgent

This will install a config and LaunchAgent for the current user. The config file lists all Atom feeds to monitor and the OS X LaunchAgent will run the script at timed intervals.

growl-atom install

=== Add feeds to your config file

The install command will generate an example config file in ~/.growl-atom/config You can add feeds and config options to this file. This is a YAML file.

---

global:

feeds:
 - name: Gmail
   url: https://mail.google.com/mail/feed/atom/
   auth_user: your_gmail_username
   auth_pass: your_gmail_password
   image: ~/.growl-atom/icons/gmail.png
   title: author/email
   message: title
   sticky: false

=== Test the config

Once you've added new feeds to the config you can test it by running:

growl-atom check

This is the same command that will be run periodically by the LaunchAgent. Any errors should show up here, if you are experiencing errors when the LaunchAgent is running then check log messages in /Applications/Utilities/Console

== Using growl-atom behind a web proxy

If your internet connection lives behind a proxy you can configure growl-atom to make all connections through this. Add the following to the global config or on a per feed basis.

global:
 proxy_host: your.proxy
 proxy_port: 80
 proxy_user: username (if req.)
 proxy_pass: password (if req.)  

== Using growl-atom with HTTP authentication

If you feed requires http athentication you can provide the username and password in the config file

feeds:
 - name: Feed requiring authentication
   url: https://protectedhost.com/feed/atom/
   auth_user: your_username
   auth_pass: your_password

== Using growl-atom with client certs

You can use growl-atom to access feeds requiring a client SSL certificate. You need to provide a .pem file with the key and cert included. If you have exported your cert from your browser it may be in a .p12 format, you can convert it to a .pem with the following command:

openssl pkcs12 -in /path/to/your/cert.p12 -nodes -out ~/.growl-atom/certs/cert.pem

You can provide the path to the pem file in the growl-atom config:

feeds:
 - name: Feed needing Cert 
   url: https://protectedhost.com/feed/atom/
   cert: ~/.growl-atom/certs/cert.pem

== Clearing the caches

growl-atom works by caching the Atom entry ID's of all messages it has alrady notified you of. It can sometimes be usefule to clear these caches, especially when debugging.

growl-atom clear-caches

== Uninstalling

Uninstalling is simple enough, first uninstall the config, caches and LaunchAgent from the local user's profile

growl-atom uninstall

Then uninstall the gem

sudo gem uninstall growl-atom -a

== License:

(GPLv3)

Copyright (C) 2009 Matt Haynes

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/