middleman-aws

Simple set of middleman rake tasks to build and deploy to AWS using s3_sync and cloudfront invalidation.

Installation and Configuration

Step 1: Add this gem to the Gemfile

gem 'middleman-aws'

Step 2: Require this gem in the Rakefile

require 'middleman-aws'

# Even though already required by the middleman-aws gem, it appears middleman does not
#   pick up transitive dependency extensions early enough  to avoid the
#   "== Unknown Extension:" error.  Add these to your main project
#   (I wish this was unnecessary but don't know how to work around it)
gem 'middleman-s3_sync'
gem 'middleman-cloudfront'

Step 3: AWS credentials

Option 1 - secrets file

e.g. ~/.aws/acme.yml

This should contain the access and secret keys generated from the selected IAM user. This is the only file that will need to reside outside the repository. acme is equivalent to the directory name for your project. Don't worry, validation will make sure you have the path right.

access_key_id: XXXXXX
secret_access_key: XXXXXX

Option 2 - ENV variables

If you don't create secrets file, then environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY will be used.

Option 3 - IAM

If a secrets file is not present (option 1), there are no ENV variables (option 2), then request to AWS will fail (unless middleman-aws is used on EC2 instance with correct IAM role, then AWS will take care of authorising requests).

Step 4: Add the necessary s3_sync and Cloudfront sections to your config

This is a sample of how a common config is setup with variables extracted:

# Configuration variables specific to each project
#------------------------------------------------------------------------
AWS_BUCKET                      = 'acme.alienfast.com'
AWS_CLOUDFRONT_DISTRIBUTION_ID  = 'xxxxxx'

# Variables: Sent in on CLI by rake task via ENV
#------------------------------------------------------------------------
AWS_ACCESS_KEY                  = ENV['AWS_ACCESS_KEY']
AWS_SECRET                      = ENV['AWS_SECRET']

# https://github.com/fredjean/middleman-s3_sync
activate :s3_sync do |s3_sync|
  s3_sync.bucket                     = AWS_BUCKET # The name of the S3 bucket you are targeting. This is globally unique.
  s3_sync.aws_access_key_id          = AWS_ACCESS_KEY
  s3_sync.aws_secret_access_key      = AWS_SECRET
  s3_sync.delete                     = false # We delete stray files by default.
end

# https://github.com/andrusha/middleman-cloudfront
activate :cloudfront do |cf|
  cf.access_key_id                    = AWS_ACCESS_KEY
  cf.secret_access_key                = AWS_SECRET
  cf.distribution_id                  = AWS_CLOUDFRONT_DISTRIBUTION_ID
  # cf.filter = /\.html$/i
end

Usage

Run the desired rake task. It's as simple as rake mm:publish in one step, or you can choose to do things one step at a time. See the available rake tasks below or run rake -T

Available Rake Tasks

rake mm:build        # Compile all files in the build directory
rake mm:clobber      # Remove all files in the build direcory
rake mm:deploy       # Deploy to S3 and invalidate Cloudfront after a Git commit/push
rake mm:preview      # Run the preview server at http://localhost:4567
rake mm:publish      # One step clobber, build, deploy
rake mm:show_config  # Show config

Real World Sample

If you are just getting started with middleman and want to get a quick jumpstart on your Gemfile and congfig.rb, check out the source in the samples directory for a set of commonly used configurations/gems/extensions.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request