Skip to content
(unsupported) Beta: Monkeypatch caching to write #{path}.html files so url rewrites can be used to serve cached content
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Static Caching

A Radiant Extension to do static file caching.

Then Apache (et. al.) can be used to serve the pages without hitting the ruby app at all.


  • Place in the vendor/extensions/static_caching

  • Install “tricycle-rack-contrib” gem (hosted at

Radiant Setup

If your static cache dir differs from “#{RAILS_ROOT}/public/radiant-cache”, set the STATIC_CACHE_DIR ruby variable in “config/initializers/static_caching.rb”

Apache Setup

Cache Location

The location needs to be accessible to Apache. The simplest solution is to put the entity cache in a location already accessible to Apache, such as: /path/to/radiant/public/radiant-cache

Alternatively you can make the default location accessible you need to add a section like the following to your apache configuration:

<Directory "/path/to/radiant/cache/entity">
  Order allow,deny
  Allow from all

Rewrite Rules

You need some apache config along the lines of this (note that /radiant-cache here matches /public/radiant-cache in “Cache Location” above - if these don't agree Radiant will write a cache, but Apache will not use it):

# This is only needed if not already present in you config/virtual host
RewriteEngine On

# Rewrite /path/to/page to cache/path/to/page if it exists (for paths already containing an extension
# or no extension)
RewriteCond %{QUERY_STRING} ^$
RewriteCond %{DOCUMENT_ROOT}/radiant-cache%{REQUEST_URI} -f
RewriteRule . /radiant-cache%{REQUEST_URI} [P,L]

# Rewrite /path/to/page/? (with or without trailing slash) to
# cache/path/to/page.{whitelisted extension} if it exists
RewriteCond %{QUERY_STRING} ^$
RewriteCond %{REQUEST_URI} ^(.+)/?$
RewriteCond %{DOCUMENT_ROOT}/radiant-cache%1.(html|css|txt|js|csv|xml|pdf|xhtml) -f
  # %1 is match from last RewriteCond
RewriteRule ^(.+)/?$ /radiant-cache$1.%1 [P,L]

# Rewrite /path/to/page/? (with or without trailing slash) (or /) to
# cache/path/to/page/index.html if it exists
RewriteCond %{QUERY_STRING} ^$
RewriteCond %{REQUEST_URI} ^(.*)/?$
RewriteCond %{DOCUMENT_ROOT}/radiant-cache%1/index.html -f
RewriteRule ^(.*)/?$ /radiant-cache$1/index.html [proxy,last]

If using Passenger

If you're using passenger and don't want it to spawn a Rails process just to serve cached content you need to add RailsAutoDetect off to the vhost defining your app and setup another vhost to be the passenger application server. You can do this by binding the passenger vhost to a loopback address and proxying the requests

*OSX Note*: OS X only treats as loopback, to add a host run sudo ifconfig lo0 alias up

# In the externally accessible vhost
RailsAutoDetect off
RewriteRule .{REQUEST_URI} [P,QSA]

And in the other vhost:

  DocumentRoot /path/to/app
  # usual setup


  • Add proper caching of GET|HEAD with query string

  • Cache “(application|text)/javascript”

  • Make only cache on success error codes 2XX

Something went wrong with that request. Please try again.