cheaptoad

= CHEAPTOAD

• http://noahgibbs.github.com/cheaptoad

== INSTALL:

sudo gem install cheaptoad

== USE:

In the app you want to catch hoptoad notices:

• Make your app use the gem:
  • In Rails 2.3.X: Add "config.gem 'cheaptoad'" to environment.rb.
  • In Rails 3: Add "gem 'cheaptoad'" to your Gemfile
• Run "./script generate cheaptoad_migration" in your app
• Run "rake db:migrate" to create the notices table
• Start your app, and you're catching notices!

In the app you want to send hoptoad notices:

• Install and configure hoptoad like usual (see hoptoad_notifier)
• In initializers/hoptoad.rb, add: config.host = 'my-app-hostname.mydomain.com' config.port = 4321 # Whatever your app port is
• Start your app, and errors will now go to your cheaptoad-ified app

== DESCRIPTION:

CheapToad is a simple server plugin for the Hoptoad notifier. Make an app receive and store errors from any app in just a couple of lines!

Hoptoad (hoptoadapp.com) is a commercial application and hosting service, run by thoughtbot. For larger or more important apps, you'll want your error logging handled by a reliable, professional service, such as thoughtbot and Hoptoad. For small, simple and experimental apps, why pay money?

== WHY CHEAPTOAD?

With CheapToad and Heroku, you can get mostly-reliable remote error logging for nothing. When and if your app grows larger, you can change two lines in config/initializers/hoptoad.rb and switch to Hoptoad for extra reliability.

Hoptoad has a far better interface, and is free for the first project and first two users (up to a given rate of errors received). But CheapToad could still be the right choice if you:

• have a lot of projects and don't want to spend money
• don't want to let anybody else store your error data
• have a lot of people to collaborate with, but not that many errors yet
• feel bad about making a new Hoptoad account for each of your projects just to scam service for free (this is me)
• need a lot of control over your old error notices -- if cleaning them up after a while is Not Okay for some reason, for instance
• don't mind hosting for yourself and/or have a hosting solution you like
• just like running your own stuff, and like to get your hands dirty (also me)

By the way, I'm not affiliated with thoughtbot. This is all reverse engineered from the Hoptoad notifier and somebody's RedMine plugin for Hoptoad. Thoughtbot is aware of CheapToad's existence, but I'm not an employee or anything.

Also, if you like CheapToad for your experimental projects, consider upgrading a project or two to Hoptoad, or getting your employer to do the same. I don't get a cut, but if I/we are costing them money overall then they have less incentive to keep giving us code to use. If we act like the farm team for their stuff and occasionally upgrade, they have more incentive to keep writing things like the hoptoad_notifier for us to bend to our own purposes.

== FEATURES:

• Very simple installation
• Very simple configuration
• Keeps your error notices around to browse later
• 100% free for any number of projects
• Maintains records of old error notices forever
• RSS feed of error notices for each project

== PROBLEMS:

• Very simple
• Not very configurable
• You have to run your own server, or use something like Heroku
• 100% Unsecured -- like Hoptoad, we rely on API key uniqueness for security. Unlike Hoptoad, we suggest using fairly guessable API keys.
• All of these problems can be summed up as "not industrial strength"

== SYNOPSIS:

Make a new Rails app, or choose an existing one. Install the cheaptoad plugin, and configure as mentioned above. Now that app can receive Hoptoad errors!

In any and all apps that you want to send errors to your app, you'll need to create a file called config/initializers/hoptoad.rb, just as you always would when using Hoptoad. Here's an example config file:

HoptoadNotifier.configure do |config| config.api_key = 'My Project Name' config.host = 'my-cheaptoad-catcher.heroku.com' config.port = 80 # or whatever port number

All standard Hoptoad filters are supported

config.filter_parameters << "MY_SECRET_KEY"

end

Note that the host and port are for the app that will receive Hoptoad errors. That's the app you added 'config.gem "cheaptoad"' to.

== REQUIREMENTS:

You'll need a Rails app, which will be your CheapToad server. It can do whatever else you like, but its notices controller will be used for CheapToad stuff.

You will not need a Hoptoad API key. That's kind of the point of this project. Instead of using a big hexadecimal string as your API key, I recommend you use a simple string like "My Blog" or "Secret Project X". That API key will be used by CheapToad as your project name.

== RESKINNING:

By default, CheapToad has a built-in set of HTML and RSS files to give a very simple list of your errors. If you'd rather use your own, it's probably easiest to just build your own notices_controller.rb file and appropriate view files to go with it. You can look at the ones in the CheapToad gem to do it -- they're very simple. Then, add your own new HTML, CSS and whatnot to pretty it up.

We're considering adding the ability to put in your own CSS file without changing the HTML, just to make the output less stark. If you care about this feature and would use it, contact me and let me know!

== COMPATIBILITY:

CheapToad is compatible with the HopToad protocol v1. v2 compatibility is in the works, and may work as you read this.

== CREDITS:

Written by Noah Gibbs, with updates by Silas Baronda

== LICENSE:

(The MIT License)

Copyright (c) 2009-2010 Noah Gibbs

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.