This add-on is operated by Meta42 Labs, LLC

Dead Simple Page Caching


Last Updated: 06 December 2013

Table of Contents

Cachely is an add-on for providing simple page caching.

Adding page caching to your application is incredibly important. Slow pages mean higher bounce rates and ultimately less customers and less money for you. If you’re pages take over 1 second to render Cachely can help. Cachely can render your pages for you, along with your original status code and headers, in just milliseconds.

Unlike other caching solutions, such as Rack::Cache, Cachely also helps with managing your cached pages. See which pages have been cached and what the HTML for those pages looks like. Expire your cached pages using Regular Expressions. All this and more is just waiting for you. Page caching has never been easier and more powerful.

Cachely is accessible via an API and has supported client libraries for Ruby on Rails/Rack-based applications. Further clients are coming.

Provisioning the add-on

Cachely can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add cachely:developer
-----> Adding cachely to sharp-mountain-4005... done, v18 (free)

Once Cachely has been added a CACHELY_URL setting will be available in the app configuration and will contain the URL and API Key needed to access the Cachely service. This can be confirmed using the heroku config:get command.

$ heroku config:get CACHELY_URL

After installing Cachely the application should be configured to fully integrate with the add-on.

Using with Rails 3.x

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Cachely client library.

gem 'rack-cachely'

Update application dependencies with bundler.

$ bundle install

Set up the Rack::Cachely middleware in the appropriate environment:

# config/environments/production.rb

# Make sure to remove Rack::Cache if you are using it:
config.middleware.delete "Rack::Cache"
# Add the Rack::Cachely middleware:
config.middleware.use Rack::Cachely
# Turn on caching:
config.action_controller.perform_caching = true

Finally you just need to tell Cachely which actions should be cached and how long they should be cached for. This can be done using the Cache-Control header:

before_filter do
  headers['Cache-Control'] = 'public; max-age=86400'

Only GET responses, with a status of 200-299, that have a public Cache-Control header will be eligible for caching. The max-age section of the header tells Cachely how long to store the page for.

Development environment

When developing locally it is best to turn off the integration with Cachely to minimize dependencies on remote services. The easiest way to do this is to only turn on the service in the environment files for Heroku, and not your development.rb file.

Deploy changes

Deploy the Cachely configuration to Heroku:

$ git add config/environments/production.rb
$ git commit -a -m "Adding cachely config"
$ git push heroku master
-----> Heroku receiving push
-----> Launching... done, v3 deployed to Heroku

 * [new branch]      master -> master

To determine if the service is working correctly navigate to a page that should be cached. Refresh the page a few times. If you view the page headers you should see several X-Cachely headers. If you see those headers then you know that Cachely is in place and doing it’s job.


For more information on the features available within the Cachely dashboard please see the docs at

The Cachely dashboard allows you to see which pages have been cached, when they expire, what their HTML looks like, the ability to remove the pages from the cache, and much more.

Cachely Dashboard

The dashboard can be accessed via the CLI:

$ heroku addons:open cachely
Opening cachely for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Cachely from the Add-ons menu.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade cachely:newplan
-----> Upgrading cachely:newplan to sharp-mountain-4005... done, v18 ($/mo)
       Your plan has been updated to: cachely:newplan

Removing the add-on

Cachely can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove cachely
-----> Removing cachely from sharp-mountain-4005... done, v20 (free)


All Cachely support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at