asset_sync 0.2.12 → 0.3.0

data/README.md

@@ -30,45 +30,107 @@ Add the gem to your Gemfile
 gem "asset_sync"
 ```
 
-> The following steps are now optional as of version **0.1.7** there is a built-in initializer [lib/engine.rb](https://github.com/rumblelabs/asset_sync/blob/master/lib/asset_sync/engine.rb)
+If you want, you can put it within your **:assets** group in your Gemfile.
 
-Generate the rake task and config file
-
-    rails g asset_sync:install
-
-If you would like to use a YAML file for configuration instead of the default (Rails Initializer) then 
-
-    rails g asset_sync:install --use-yml
+``` ruby
+group :assets do
+  gem 'sass-rails',   '~> 3.2.3'
+  gem 'coffee-rails', '~> 3.2.1'
+  gem 'uglifier', '>= 1.0.3'
+  gem "asset_sync"
+end
+```
 
-The default *provider* is `AWS` but you can pick which one you need.
+This is good practice when pre-compiling your assets as it will reduce load time and server memory in production. The only caveat being, you may not be able to use a custom initializer, without perhaps wrapping it with.
 
-    rails g asset_sync:install --provider=Rackspace
-    rails g asset_sync:install --provider=AWS
+``` ruby
+defined?(AssetSync) do
+...
+end
+```
 
 ## Configuration
 
+### Rails
+
 Configure __config/environments/production.rb__ to use Amazon
 S3 as the asset host and ensure precompiling is enabled.
 
+
 ``` ruby
-# config/environments/production.rb
-config.action_controller.asset_host = Proc.new do |source, request|
-  request.ssl? ? "https://#{ENV['FOG_DIRECTORY']}.s3.amazonaws.com" : "http://#{ENV['FOG_DIRECTORY']}.s3.amazonaws.com"
+  #config/environments/production.rb
+  config.action_controller.asset_host = Proc.new do |source, request|
+    request.ssl? ? "https://#{ENV['FOG_DIRECTORY']}.s3.amazonaws.com" : "http://#{ENV['FOG_DIRECTORY']}.s3.amazonaws.com"
 end
 ```
 
-We support two methods of configuration.
+Also, ensure the following are defined (in production.rb or application.rb)
+
+* **config.assets.digest** is set to **true**.
+* **config.assets.enabled** is set to **true**.
 
+### AssetSync
+
+**AssetSync** supports the following methods of configuration.
+
+* [Built-in Initializer](/rumblelabs/asset_sync/blob/master/lib/asset_sync/engine.rb) (configured through environment variables)
 * Rails Initializer
 * A YAML config file
 
-Using an **Initializer** is the default method and is best used with **environment** variables. It's the recommended approach for deployments on Heroku.
 
-Using a **YAML** config file is a traditional strategy for Capistrano deployments. If you are using [Moonshine](https://github.com/railsmachine/moonshine) (which we would recommend) then it is best used with [shared configuration files](https://github.com/railsmachine/moonshine/wiki/Shared-Configuration-Files).
+Using the **Built-in Initializer** is the default method and is supposed to be used with **environment** variables. It's the recommended approach for deployments on Heroku.
+
+If you need more control over configuration you will want to use a **custom rails initializer**.
+
+Configuration using a **YAML** file (a common strategy for Capistrano deployments) is also suppored.
+
+The recommend way to configure **asset_sync** is by using **environment variables** however it's up to you, it will work fine if you hard code them too. The main reason is that then your access keys are not checked into version control.
+
+### Built-in Initializer (Environment Variables)
+
+The Built-in Initializer will configure **AssetSync** based on the contents of your environment variables.
+
+Add your configuration details to **heroku**
+
+``` bash
+heroku config:add AWS_ACCESS_KEY_ID=xxxx
+heroku config:add AWS_SECRET_ACCESS_KEY=xxxx
+heroku config:add FOG_DIRECTORY=xxxx
+heroku config:add FOG_PROVIDER=AWS
+# and optionally:
+heroku config:add FOG_REGION=eu-west-1
+heroku config:add ASSET_SYNC_GZIP_COMPRESSION=true
+heroku config:add ASSET_SYNC_MANIFEST=true
+heroku config:add ASSET_SYNC_EXISTING_REMOTE_FILES=keep
+```
+
+Or add to a traditional unix system
+
+``` bash
+export AWS_ACCESS_KEY_ID=xxxx
+export AWS_SECRET_ACCESS_KEY=xxxx
+export FOG_DIRECTORY=xxxx
+```
+
+Rackspace configuration is also supported
+
+``` bash
+heroku config:add RACKSPACE_USERNAME=xxxx
+heroku config:add RACKSPACE_API_KEY=xxxx
+heroku config:add FOG_DIRECTORY=xxxx
+heroku config:add FOG_PROVIDER=Rackspace
+```
+
+The Built-in Initializer also sets the AssetSync default for **existing_remote_files** to **keep**.
 
-The recommend way to configure **asset_sync** is by using environment variables however it's up to you, it will work fine if you hard code them too. The main reason is that then your access keys are not checked into version control.
+### Custom Rails Initializer (config/initializers/asset_sync.rb)
 
-### Initializer (config/initializers/asset_sync.rb)
+If you want to enable some of the advanced configuration options you will want to create your own initializer.
+
+Run the included Rake task to generate a starting point.
+
+    rails g asset_sync:install --provider=Rackspace
+    rails g asset_sync:install --provider=AWS
 
 The generator will create a Rails initializer at `config/initializers/asset_sync.rb`.
 
@@ -97,10 +159,14 @@ AssetSync.configure do |config|
 end
 ```
 
-
 ### YAML (config/asset_sync.yml)
 
-If you used the `--use-yml` flag, the generator will create a YAML file at `config/asset_sync.yml`.
+Run the included Rake task to generate a starting point.
+
+    rails g asset_sync:install --use-yml --provider=Rackspace
+    rails g asset_sync:install --use-yml --provider=AWS
+
+The generator will create a YAML file at `config/asset_sync.yml`.
 
 ``` yaml
 defaults: &defaults
@@ -128,35 +194,31 @@ production:
   <<: *defaults
 ```
 
-### Environment Variables
+### Available Configuration Options
 
-Add your Amazon S3 configuration details to **heroku**
+All AssetSync configuration can be modified directly using environment variables with the **Built-in initializer**. e.g.
 
-    heroku config:add AWS_ACCESS_KEY_ID=xxxx
-    heroku config:add AWS_SECRET_ACCESS_KEY=xxxx
-    heroku config:add FOG_DIRECTORY=xxxx
+```ruby
+AssetSync.config.fog_provider == ENV['FOG_PROVIDER']
+```
 
-Or add to a traditional unix system
+Simply **upcase** the ruby attribute names to get the equivalent environment variable to set. The only exception to that rule are the internal **AssetSync** config variables, they must be prepended with `ASSET_SYNC_*` e.g.
 
-``` bash
-export AWS_ACCESS_KEY_ID=xxxx
-export AWS_SECRET_ACCESS_KEY=xxxx
-export FOG_DIRECTORY=xxxx
+```ruby
+AssetSync.config.gzip_compression == ENV['ASSET_SYNC_GZIP_COMPRESSION']
 ```
 
-### Available Configuration Options
+#### AssetSync (optional)
 
-#### AssetSync
+* **existing_remote_files**: (`'keep', 'delete'`) what to do with previously precompiled files. **default:** `'keep'`
+* **gzip\_compression**: (`true, false`) when enabled, will automatically replace files that have a gzip compressed equivalent with the compressed version. **default:** `'false'`
+* **manifest**: (`true, false`) when enabled, will use the `manifest.yml` generated by Rails to get the list of local files to upload. **experimental**. **default:** `'false'`
 
-* **existing_remote_files**: what to do with previously precompiled files, options are **keep** or **delete**
-* **gzip\_compression**: when enabled, will automatically replace files that have a gzip compressed equivalent with the compressed version.
-* **manifest**: when enabled, will use the `manifest.yml` generated by Rails to get the list of local files to upload. **experimental**
-
-#### Required (Fog)
+#### Fog (Required)
 * **fog\_provider**: your storage provider *AWS* (S3) or *Rackspace* (Cloud Files)
 * **fog\_directory**: your bucket name
 
-#### Optional
+#### Fog (Optional)
 
 * **fog\_region**: the region your storage bucket is in e.g. *eu-west-1*
 
@@ -170,21 +232,19 @@ export FOG_DIRECTORY=xxxx
 * **rackspace\_username**: your Rackspace username
 * **rackspace\_api\_key**: your Rackspace API Key.
 
-#### Rackspace Optional
+#### Rackspace (Optional)
 
 * **rackspace\_auth\_url**: Rackspace auth URL, for Rackspace London use: lon.auth.api.rackspacecloud.com
 
 ## Amazon S3 Multiple Region Support
 
-If you are using anything other than the US buckets with S3 then you'll want to set the **region**. For example with an EU bucket you could set the following with YAML.
+If you are using anything other than the US buckets with S3 then you'll want to set the **region**. For example with an EU bucket you could set the following environment variable.
 
-``` yaml
-production:
-  # ...
-  aws_region: 'eu-west-1'
+``` bash
+heroku config:add FOG_REGION=eu-west-1
 ```
 
-Or via the initializer
+Or via a custom initializer
 
 ``` ruby
 AssetSync.configure do |config|
@@ -193,27 +253,46 @@ AssetSync.configure do |config|
 end
 ```
 
+Or via YAML
+
+``` yaml
+production:
+  # ...
+  aws_region: 'eu-west-1'
+```
+
+
 ## Automatic gzip compression
 
 With the `gzip_compression` option enabled, when uploading your assets. If a file has a gzip compressed equivalent we will replace that asset with the compressed version and sets the correct headers for S3 to serve it. For example, if you have a file **master.css** and it was compressed to **master.css.gz** we will upload the **.gz** file to S3 in place of the uncompressed file.
 
 If the compressed file is actually larger than the uncompressed file we will ignore this rule and upload the standard uncompressed version.
 
-## Heroku
+## Fail Silently
+
+With the `fail_silently` option enabled, when running `rake assets:precompile` AssetSync will never throw an error due to missing configuration variables.
 
-With Rails 3.1 on the Heroku cedar stack, the deployment process automatically runs `rake assets:precompile`. If you are using **ENV** variable style configuration. Due to the methods with which Heroku compile slugs, there will be an error raised by asset_sync as the environment is not available. This causes heroku to install the `rails31_enable_runtime_asset_compilation` plugin which is not necessary when using **asset_sync** and also massively slows down the first incoming requests to your app.
+With the new **user_env_compile** feature of Heroku (see above), this is no longer required or recommended. Yet was added for the following reasons:
 
-To prevent this part of the deploy from failing (asset_sync raising a config error), but carry on as normal set `fail_silently` to true in your configuration and ensure to run `heroku run rake assets:precompile` after deploy.
+> With Rails 3.1 on the Heroku cedar stack, the deployment process automatically runs `rake assets:precompile`. If you are using **ENV** variable style configuration. Due to the methods with which Heroku compile slugs, there will be an error raised by asset\_sync as the environment is not available. This causes heroku to install the `rails31_enable_runtime_asset_compilation` plugin which is not necessary when using **asset_sync** and also massively slows down the first incoming requests to your app.
+
+> To prevent this part of the deploy from failing (asset_sync raising a config error), but carry on as normal set `fail_silently` to true in your configuration and ensure to run `heroku run rake assets:precompile` after deploy.
 
 ## Rake Task
 
-A rake task is included in asset\_sync to enhance the rails precompile task by automatically running after it:
+A rake task is included within the **asset_sync** gem to enhance the rails precompile task by automatically running after it.
 
 ``` ruby
-# asset_sync/lib/tasks/asset_sync.rake
-Rake::Task["assets:precompile"].enhance do
-  AssetSync.sync
-end
+  # asset_sync/lib/tasks/asset_sync.rake
+  if Rake::Task.task_defined?("assets:precompile:nondigest")
+    Rake::Task["assets:precompile:nondigest"].enhance do
+      AssetSync.sync
+    end
+  else
+    Rake::Task["assets:precompile"].enhance do
+      AssetSync.sync
+    end
+  end
 ```
 
 ## Todo
@@ -221,10 +300,11 @@ end
 1. Add some before and after filters for deleting and uploading
 2. Support more cloud storage providers
 3. Better test coverage
+4. Add rake tasks to clean old assets from a bucket
 
 ## Credits
 
-Have borrowed ideas from:
+Inspired by:
 
  - [https://github.com/moocode/asset_id](https://github.com/moocode/asset_id)
  - [https://gist.github.com/1053855](https://gist.github.com/1053855)

data/asset_sync.gemspec

@@ -6,7 +6,7 @@ require "asset_sync/version"
 Gem::Specification.new do |s|
   s.name        = "asset_sync"
   s.version     = AssetSync::VERSION
-  s.date        = "2012-03-04"
+  s.date        = "2012-03-07"
   s.platform    = Gem::Platform::RUBY 
   s.authors     = ["Simon Hamilton", "David Rice", "Phil McClure"]
   s.email       = ["shamilton@rumblelabs.com", "me@davidjrice.co.uk", "pmcclure@rumblelabs.com"]

data/lib/asset_sync/engine.rb

@@ -21,7 +21,9 @@ class Engine < Rails::Engine
 
         config.rackspace_username = ENV['RACKSPACE_USERNAME']
         config.rackspace_api_key = ENV['RACKSPACE_API_KEY']
-        config.existing_remote_files = "keep"
+        config.existing_remote_files = ENV['ASSET_SYNC_EXISTING_REMOTE_FILES'] || "keep"
+        config.gzip_compression = ENV['ASSET_SYNC_GZIP_COMPRESSION'] == 'true'
+        config.manifest = ENV['ASSET_SYNC_MANIFEST'] == 'true'
       end
     end
 

data/lib/asset_sync/version.rb

@@ -1,3 +1,3 @@
 module AssetSync
-  VERSION = "0.2.12"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asset_sync
 version: !ruby/object:Gem::Version
-  version: 0.2.12
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -11,11 +11,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-04 00:00:00.000000000Z
+date: 2012-03-07 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fog
-  requirement: &70142731459580 !ruby/object:Gem::Requirement
+  requirement: &70330270051360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70142731459580
+  version_requirements: *70330270051360
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &70142731459160 !ruby/object:Gem::Requirement
+  requirement: &70330270050940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70142731459160
+  version_requirements: *70330270050940
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70142731458740 !ruby/object:Gem::Requirement
+  requirement: &70330270050520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -45,10 +45,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70142731458740
+  version_requirements: *70330270050520
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70142731458320 !ruby/object:Gem::Requirement
+  requirement: &70330270050100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -56,10 +56,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70142731458320
+  version_requirements: *70330270050100
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70142731457900 !ruby/object:Gem::Requirement
+  requirement: &70330270049680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -67,7 +67,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70142731457900
+  version_requirements: *70330270049680
 description: After you run assets:precompile your compiled assets will be synchronised
   with your S3 bucket.
 email: