Shack

A Rack middleware that will add a unique identifier (sha) to the application. It will set a custom header (X-Shack-Sha) containing the sha and will automagically insert a small banner in the HTML.

Shack in action

This way you can always be certain which version of your app is currently running, especially handy in staging environments. If you don't supply a sha nothing will happen (so for example if you use an ENV variable containing the sha and don't set it in production, no one will be any wiser).

Installation

For a rack app:

require "shack"

app = Rack::Builder.new do
  use Shack::Middleware, ENV["SHA"]
  run -> (env) { [200, {"Content-Type" => "text/html", ["<html><body>KAAAHN</body></html>"]]
end

Rack::Server.start app: app

If your rack app happens to be a Rails app:

Add shack to your Gemfile, and specify how to get the hash in an initializer (config/initializers/shack.rb)

Shack::Middleware.configure do |shack|
    shack.sha = File.open("BUILD_NUMBER").read.strip
end

And since it's Rails, it can also be done automagically if a file called REVISION is found in the root of your project. No initializer required. Note: by default it won't show the banner in production environments, because that just feels wrong.

Configuration

You can either set the sha directly:

Shack::Middleware.configure do |shack|
    shack.sha = File.open("REVISION").read.strip
    shack.hide_stamp = true # this will hide the banner
end

Or you can set the string to show in the HTML banner (with {{sha}} being a special variable which will be replaced with the sha):

Shack::Middleware.configure do |shack|
  shack.sha = File.open("REVISION").read.strip
  shack.content = "#{Rails.env} - <a href="https://github.com/shack/commit/{{sha}}>{{sha}}</a>"
end

There is also a {{short_sha}} substition available, which returns the first 8 chars of the set sha.

How do I set the sha?

Either write it to a REVISION file on deploy (Capistrano used to this by default, now you can add a task, in mina I'm waiting on this pull request), or set an ENV variable containing the sha.

Now you can set the sha in the configure block.

Signed gem

shack is cryptographically signed. To be sure the gem you install hasn’t been tampered with:

Download certificate https://raw.github.com/pjaspers/shack/certs/pjaspers.pem
Add gem cert –add pjaspers.pem
gem install shack -P HighSecurity

I don't use Rubies

For the PHP-inclined, here is a PHP version by @tinydroptest2.

Contributing

Fork it ( https://github.com/pjaspers/shack/fork )
Create a new Pull Request
Technology.