Rails Asset Pipeline on Heroku
Last updated December 15, 2020
Table of Contents
Rails applications running on Heroku can have the asset pipeline compiled locally, at deploy-time, or at run time. For new users, we recommend reading Getting Started with Ruby on Heroku before proceeding further.
Heroku recommends using the asset pipeline with a CDN to increase end user experience and decrease load on your Heroku app.
The Rails 4 Asset Pipeline
If you are using Rails 4 and the asset pipeline it is recommended to familiarize yourself with the document below. Much of the behavior between Rails 3 and Rails 4 is similar. Once finished please read the Rails 4 Asset Pipeline on Heroku which covers the differences between the two experiences.
The Rails 3 Asset Pipeline
The Rails asset pipeline provides an
assets:precompile rake task to allow assets to be compiled and cached up front rather than compiled every time the app boots.
There are two ways you can use the asset pipeline on Heroku.
- Compiling assets locally.
- Compiling assets during slug compilation.
Compiling assets locally
public/assets/manifest.yml is detected in your app, Heroku will assume you are handling asset compilation yourself and will not attempt to compile your assets. Rails 4 uses a file called
public/assets/manifest-<md5 hash>.json instead. More recent versions use
public/assets/.sprockets-manifest-<md5 hash>.json (note the dot
. indicating it may be hidden by default on your machine). On all versions you can generate this file by running
$ rake assets:precompile locally and checking the resultant files into Git.
To compile your assets locally, run the
assets:precompile task locally on your app. Make sure to use the
production environment so that the production version of your assets are generated.
RAILS_ENV=production bundle exec rake assets:precompile
public/assets directory will be created. Inside this directory you’ll find a
manifest.yml which includes the md5sums of the compiled assets in Rails 3. In Rails 4 the file will be
manifest-<md5 hash>.json. Adding
public/assets to your git repository will make it available to Heroku.
git add public/assets git commit -m "vendor compiled assets"
Now when pushing, the output should show that your locally compiled assets were detected:
-----> Preparing Rails asset pipeline Detected manifest.yml, assuming assets were compiled locally
Compiling assets during slug compilation
If you have not compiled assets locally, we will attempt to run the
assets:precompile task during slug compilation. Your push output will show:
-----> Preparing Rails asset pipeline Running: rake assets:precompile
Please see the Troubleshooting section below on explanations of how the rake task works during our slug compilation process.
assets:precompile task fails, the output will be displayed and the build will exit.
Caching of static assets can be implemented in-application using the Rack::Cache middleware or in a more distributed fashion with a CDN. Serving assets from your application does require dyno-resources so please consider an appropriate asset caching strategy for your needs.
Failures in the assets:precompile task
In Rails 3.x, you can prevent initializing your application and connecting to the database by ensuring that the following line is in your
config.assets.initialize_on_precompile = false
Do not forget to commit to git after changing this setting.
Before you can compile your assets on Heroku, you’ll need to be able to compile them locally, run this command to debug your assets:
$ RAILS_ENV=production bundle exec rake assets:precompile
This should complete with no errors. Do NOT check in the assets into git after running this command.
If you were previously using
therubyracer-heroku, these gems are no longer required and strongly discouraged as these gems use a very large amount of memory.
A version of Node is installed by the Ruby buildpack that will be used to compile your assets.
If you need to compile assets at runtime, you must add
$ heroku config PATH => vendor/bundle/ruby/1.9.1/bin:/usr/local/bin:/usr/bin:/bin
If your PATH variable does not include
bin on its own, update it by running:
$ heroku config:set PATH=bin:vendor/bundle/ruby/1.9.1/bin:/usr/local/bin:/usr/bin:/bin Adding config vars: PATH => vendor/bundle/ru...usr/bin:/bin:bin Restarting app... done, v7.
No debug output at all
If you see no debug output and your
asset:precompile task is not run, ensure that
rake is in your
Gemfile and properly committed.
Compile Set to True in Production
If you have enabled your application to
config.assets.compile = true in production, your application might be very slow. This was best described in a stack overflow post:
When you have compile on, this is what happens: Every request for a file in /assets is passed to Sprockets. On the first request for each and every asset it is compiled and cached in whatever Rails is using for cache (usually the filesystem). On subsequent requests Sprockets receives the request and has to look up the fingerprinted filename, check that the file (image) or files(css and js) that make up the asset were not modified, and then if there is a cached version serve that.
This setting is also known to cause other run-time instabilities and is generally not recommended. Instead we recommend either precompiling all of your assets on deploy (which is the default) or if that is not possible compiling assets locally.