[guides] add local precompilation section

1 files changed, 36 insertions, 1 deletions

diff --git a/guides/source/asset_pipeline.textile b/guides/source/asset_pipeline.textile
index 010154f1d1..59f106acb2 100644
--- a/guides/source/asset_pipeline.textile
+++ b/guides/source/asset_pipeline.textile
@@ -396,7 +396,7 @@ Rails comes bundled with a rake task to compile the asset manifests and other fi
 
 Compiled assets are written to the location specified in +config.assets.prefix+. By default, this is the +public/assets+ directory.
 
-You can call this task on the server during deployment to create compiled versions of your assets directly on the server. If you do not have write access to your production file system, you can call this task locally and then deploy the compiled assets.
+You can call this task on the server during deployment to create compiled versions of your assets directly on the server. See the next section for information on compiling locally.
 
 The rake task is:
 
@@ -516,6 +516,41 @@ If you're compiling nginx with Phusion Passenger you'll need to pass that option
 
 A robust configuration for Apache is possible but tricky; please Google around. (Or help update this Guide if you have a good example configuration for Apache.)
 
+h4. Local Precompilation
+
+There are several reasons why you might precompile your assets locally. Among them are:
+
+* You may not have write access to your production file system.
+* You may be deploying to more than one server, and want to avoid the duplication of work.
+* You may be doing frequent deploys that do not include asset changes.
+
+Local compilation allows you to commit the compiled files into source control, and deploy as normal.
+
+There are two caveats:
+
+* You must not run the Capistrano deployment task.
+* You must change the following two application configuration settings.
+
+In development.rb place the following line:
+
+<erb>
+config.assets.prefix = "/dev-assets"
+</erb>
+
+You will also need this in application.rb:
+
+<erb>
+config.assets.initialize_on_precompile = false
+</erb>
+
+The +prefix+ change makes rails use a different URL for serving assets in development mode, and so pass all requests to Sprockets. Production is still set to +/assets+. Without this changes the application would serve the precompiled assets in development, and you would not see any local changes until you next compiled assets.
+
+The +initialize_on_precompile+ change tell the precompile task to run without invoking Rails.
+
+You will also need to ensure that any compressors or minifers are available on you development system.
+
+In practice, this will allow you to precompile locally, have those files in your working tree, and commit those files to source control when needed. Development mode will work as expected.
+
 h4. Live Compilation
 
 In some circumstances you may wish to use live compilation. In this mode all requests for assets in the pipeline are handled by Sprockets directly.