adamburmister/morning_glory

h1. Morning Glory

Morning Glory is comprised of a rake task and helper methods that manages the deployment of static assets into an Amazon CloudFront CDN's S3 Bucket, improving the performance of static assets on your Rails web applications.

NOTE: You will require an Amazon Web Services (AWS) account in order to use this gem. Specially: S3 for storing the files you wish to distribute, and CloudFront for CDN distribution of those files.

h2. What does it do?

Morning Glory provides an easy way to deploy Ruby on Rails application assets to the Amazon CloudFront CDN.

It solves a number of common issues with S3/CloudFront. For instance, CloudFront won't automatically expire old assets stored on edge nodes when you redeploy new assets (the Cloudfront expiry time is 24 hours minimum). To fix this Morning Glory will automatically namespace asset releases for you, then update all references to those renamed assets within your stylesheets ensuring there are no broken asset links.

It also provides a helper method to rewrite all standard Rails asset helper generated URLs to your CloudFront CDN distributions, as well as handling switching between HTTP and HTTPS.

Morning Glory was also built with SASS (Syntactically Awesome Stylesheets) in mind. If you use Sass for your stylesheets they will automatically be built before deployment to the CDN. See http://sass-lang.com/ for more information on Sass.s

h2. What it doesn't do

Morning Glory cannot configure your CloudFront distributions for you automatically. You will manually have to login to your AWS Management Console account, "https://console.aws.amazon.com/cloudfront/home":https://console.aws.amazon.com/cloudfront/home, and set up a distribution pointing to an S3 Bucket.

h2. Installation

script/plugin install git://github.com/adamburmister/morning_glory.git

h2. Usage

Morning Glory provides it's functionality via rake tasks. You'll need to specify the target rails environment configuration you want to deploy for by using the @RAILS_ENV={env}@ parameter (for example, @RAILS_ENV=production@).

rake morning_glory:cloudfront:deploy RAILS_ENV={YOUR_TARGET_ENVIRONMENT}

h2. Configuration

h3. The Morning Glory configuration file, @config/morning_glory.yml@

You can specify a configuration section for every rails environment (production, staging, testing, development). This section can have the following properties defined:

--- 
production: 
  enabled: true                     # Is MorningGlory enabled for this environment?
  bucket: cdn.production.foo.com    # The bucket to deploy your assets into
  s3_logging_enabled: true          # Log the deployment to S3
  revision: "20100317134627"        # The revision prefix. This timestamp automatically generateed on deployment
  delete_prev_rev: true             # Delete the previous asset release (save on S3 storage space)

h3. The Amazon S3 authentication keys configuration file, @config/s3.yml@

This file provides the access credentials for your Amazon AWS S3 account. You can configure keys for all your environments (production, staging, testing, development).

---
production:
  access_key_id: YOUR_ACCESS_KEY
  secret_access_key: YOUR_SECRET_ACCESS_KEY

h3. Set up an asset_host

For each environment that you'd like to utilise the CloudFront CDN for you'll need to define the asset_host within the @config/environments/{ENVIRONMENT}.rb@ configuration file.

As of June 2010 AWS supports HTTPS requests on the CloudFront CDN, so you no longer have to worry about switching servers. (Yay!)

h4. Example config/environments/production.rb @asset_host@ snippet:

Here we're targeting a CNAME domain with HTTP support.

ActionController::Base.asset_host = Proc.new { |source, request|
  if request.ssl?
    "#{request.protocol}#{request.host_with_port}"
  else
    "#{request.protocol}assets.example.com"
  end
}

h3. Why do we have to use a revision-number/namespace/timestamp?

Once an asset has been deployed to the Amazon Cloudfront edge servers it cannot be modified - the version exists until it expires (minimum of 24 hours).

To get around this we need to prefix the asset path with a revision of some sort - in MorningGlory's case we use a timestamp. That way you can deploy many times during a 24 hour period and always have your latest revision available on your web site.

h2. Dependencies

h3. AWS S3

Required for uploading the assets to the Amazon Web Services S3 buckets. See "http://amazon.rubyforge.org/":http://amazon.rubyforge.org/ for more documentation on installation.

h2. About the name

Perhaps not what you'd expect; a "Morning Glory":http://en.wikipedia.org/wiki/Morning_Glory_cloud is a rare cloud formation observed by glider pilots in Australia (see my side project, "YourFlightLog.com for flight-logging software for paraglider and hang-glider pilots":http://www.yourflightlog.com, from which the Morning Glory plugin was originally extracted).

adamburmister / morning_glory

readme