February 22nd 2011

Setting up your custom Hoptoad Notifier endpoint for free using Errbit on Heroku

The Errbit app is an open source Rails 3 app that is API-compatible with Thoughtbot's Hoptoad Notifier and thus allows you to roll your own exception tracking service for free on Heroku. Let's see how to set this up.

You may have various reasons to roll your own exception tracker. Be it the need for customization (either visual or functional), security concerns or simply the price-tag of commercial exception trackers.

For me, it's mostly the security concerns. Hoptoad only offers SSL for plans starting at $15/month, and thus plenty of people send their application errors across the world in plain text - including environment configuration like S3- and mail credentials.

Of course, relying on your own error service gives you adminstrative overhead which you might not want. It's up to you to decide what suits you better - this article is only here to explain how you can set up the great Errbit app on Heroku with SSL enabled for free in a matter of minutes.

If you're curious what this might look like, check out the screenshots in the Errbit announcement post here.

Cloning and configuring Errbit

Let's start out with cloning the Errbit repo and copying over the two required config files:

git clone https://github.com/jdpace/errbit.git
cd errbit
cp config/config.example.yml config/config.yml
cp config/mongoid.example.yml config/mongoid.yml

Now, open up config/config.yml, set the host for your app to your (supposed) Heroku url and specify a from-email address:

host: YOUR_APP_NAME.heroku.com
email_from: noreply@example.com

Accordingly, open up config/mongoid.yml to set up the database connection in production to use the MONGOHQ_URL environment variable set by Heroku after adding the MongoHQ addon:

production:
  uri: <%= ENV['MONGOHQ_URL'] %>

Finally, let's add those files to git and commit the new configuration:

git add -f config/config.yml config/mongoid.yml
git commit -m "Heroku configs"

Heroku setup

Of course, you should have the heroku gem installed and set up for this to work.

Still inside your local errbit clone, create the app and add the MongoHQ and Sendgrid addons to get the required MongoDB and mail delivery capabilities, then, deploy Errbit and seed the database:

heroku create YOUR_APP_NAME
heroku addons:add mongohq:free
heroku addons:add sendgrid:free
git push heroku master 
heroku rake db:seed

After seeding the database, you should see a notification holding your initial credentials. You should visit your fresh Errbit install to verify everything works fine and to change the credentials and your user name right away.

Enforcing the use of SSL

As I said before, I'm no fan of exception data delivered over the net unencrypted. Luckily, Heroku offers free SSL on subdomain apps (foo.heroku.com) using their heroku.com wildcard certificate. Enable it by running:

heroku addons:add ssl:piggyback

Now, let's enforce the usage of SSL even when users arrive at the app via plain HTTP instead of HTTPS by installing the middleware Rack SSL Enforcer gem into Errbit.

Open up the Gemfile and add:

gem 'rack-ssl-enforcer', :group => :production

Then, open up config/application.rb and tell Rails to use the middleware:

config.middleware.use Rack::SslEnforcer, :except => /^\/deploys/

The except clause for the deploy API is neccessary since obviously Hoptoad does not report deployments via SSL even when secure connections are configured in the Notifier. You can remove this if you can do without Deployment tracking.

As a final step, update your Bundle, commit and push:

bundle
git commit -am "Rack SSL Enforcer"
git push heroku

Configuring the Notifier in your application

Finally, it's time to wire up your (supposedly ;) existing Rails app with your custom exception tracker.

Go back to the Errbit web interface and add an app. It will give you instructions on how to set things up. Basically, for a Rails 3 application, you need to add gem 'hoptoad_notifier' to your Gemfile, then create config/initializers/errbit.rb.

The configuration suggested by Errbit does not reflect our desired usage of secure SSL connections properly, though, so you'll have to add the config.secure = true option to make things work, as shown below. The port config can be omitted, it will default to 443 when using secure connections.

config/initializers/errbit.rb:

HoptoadNotifier.configure do |config|
   config.api_key = 'ABCDEF'
   config.host    = 'YOUR_APP_NAME.heroku.com'
   config.secure  = true
end

After a final bundle, you should be able to track exceptions using hoptoad_notifier and Errbit. Test-fire it with:

rake hoptoad:test

You can also track deployments via rake, for example from a git hook - check to the documentation of Hoptoad Notifier for further information.

Test fire a deployment notification with:

rake hoptoad:deploy TO=production REVISION=1234 REPOSITORY=origin USER=colszowka

And that's all I can say.

Written by Christoph Olszowka
blog comments powered by Disqus