A middleman deploy tool for invalidating resources cached on common Content Delivery Networks (CDNs).

• Cache invalidation of files on:
  • CloudFlare
  • MaxCDN
  • Fastly
  • Amazon CloudFront
  • Rackspace CloudFiles
• Select files for invalidation with regex.
• Automatically invalidate after build.
• Manually trigger invalidation with a single command on specific files.
• Invalidating files only when they've changed if you're using middleman-s3_sync.

Add this to your Gemfile:

gem "middleman-cdn"

Then run:

bundle install

Edit your middleman config.rb and add the following. Specify either one or more CDN configurations.

activate :cdn do |cdn|
  cdn.cloudflare = {
    client_api_key: '...',          # default ENV['CLOUDFLARE_CLIENT_API_KEY']
    email: 'you@example.com',       # default ENV['CLOUDFLARE_EMAIL']
    zone: 'example.com',
    base_urls: [
      'http://example.com',
      'https://example.com',
    ]
  }
  cdn.maxcdn = {
    alias: "...",                   # default ENV['MAXCDN_ALIAS']
    consumer_key: "...",            # default ENV['MAXCDN_CONSUMER_KEY']
    consumer_secret: "...",         # default ENV['MAXCDN_CONSUMER_SECRET']
    zone_id: "...",
  }
  cdn.fastly = {
    api_key: '...',                 # default ENV['FASTLY_API_KEY']
    base_urls: [
      'http://www.example.com',
      'https://www.example.com'
    ],
  }
  cdn.cloudfront = {
    access_key_id: '...',           # default ENV['AWS_ACCESS_KEY_ID']
    secret_access_key: '...',       # default ENV['AWS_SECRET_ACCESS_KEY']
    distribution_id: '...'
  }
  cdn.rackspace = {
    username: "...",                # default ENV['RACKSPACE_USERNAME']
    api_key: "...",                 # default ENV['RACKSPACE_API_KEY']
    region: "DFW",                  # DFW, SYD, IAD, ORD, HKG, etc
    container: "...",
    notification_email: "you@example.com" # optional
  }
  cdn.filter            = /\.html/i # default /.*/
  cdn.after_build       = true      # default is false
end

The filter parameter defines which files in your middleman build directory will be invalidated on the CDN. It must be a regular expression (use rubular to test your regex).

Examples:

It's better to always invalidate only the files you need. If you're using middleman's asset pipeline to generate fingerprinted CSS, JS and images, then you should never need to invalidate them.

Note: Directories containing index.html files are automatically included when their respective index.html is included in the filter. Both the slashed and non-slashed version of the directory are invalidated. e.g. The file /blog/index.html will also invalidate /blog/ and /blog.

Alternatively: If you're using middleman-s3_sync you can hook middleman-cdn into it's build process. See the instructions here.

The cloudflare parameter contains the information specific to your CloudFlare account and which zone (domain) files should be invalidated for. CloudFlare invalidation works off URLs not filenames, and you must provide a list of base urls to ensure we invalidate every URL that your files might be accessed at.

CloudFlare invalidations often take a few seconds.

The maxcdn parameter contains the information specific to your MaxCDN account. Your alias can be found on the API tab of your MaxCDN account page, and you'll need to create an application in your MaxCDN account which will provide you with API keys. The extension works by invalidating files in pull zones. Make sure you add your website as a pull zone.

MaxCDN invalidations often take a few seconds.

The fastly parameter contains the information specific to your Fastly account. Fastly invalidation works off URLs not filenames, and you must provide a list of base urls to ensure we invalidate every URL that your files might be at.

Fastly invalidations often take a few seconds.

The cloudfront parameter contains the information specific to your AWS CloudFront account and which distribution files should be invalidated for.

CloudFront invalidations take up to 15 minutes. You can monitor the progress of the invalidation in your AWS Console.

The rackspace parameter contains the information specific to your Rackspace account. The extension works by invalidating files stored at the edge on Rackspace's CDN (Akaimi) that mirrors Rackspace's CloudFiles. If you specify a notification email, you will receive an email from Akaimi when the invalidation has been completed.

Note:

1. At the time of writing Rackspace allows 25 files to be invalidated per day.
2. This extension will only invalidate files on the CDN and will not synchronise or upload files to CloudFiles. Use middleman-sync to do that.

Instead of storing your CDN credentials in config.rb where they may be public on github, store them in environment variables, or execute on the commandline as. Any parameters with a default of ENV[...] (see above) can be stored as environment variables or provided on the commandline like this example.

CLOUDFLARE_CLIENT_API_KEY= CLOUDFLARE_EMAIL= bundle exec middleman invalidate

Set after_build to true and the cache will be invalidated after build:

bundle exec middleman build

Or, invalidate manually using:

bundle exec middleman cdn

Or, invalidate specific files manually:

bundle exec middleman cdn [file] [file] ...

If you're using middleman-s3_sync you can hook middleman-cdn into it's build process, to invalidate only the files that s3_sync uploads. Add the following to your config.rb:

after_s3_sync do |files_by_status|
  cdn_invalidate(files_by_status[:updated])
end

Also, make sure to remove cdn.after_build = true from your config, if it was there previously, so the invalidation is not run twice.

I'm using middleman-cdn on my personal website leighmcculloch.com which is on github if you want to checkout how I deploy. It's configuration has all of the above CDNs in use for demonstration. I primarily use CloudFlare, and unlike the other CDNs, CloudFlare doesn't default to caching HTML. To make the most of CloudFlare, configure a PageRule that looks like this to tell CloudFlare to cache everything.

Middleman CDN is a fork off Middleman CloudFront and I used it as the base for building this extension. The code was well structured and easy to understand. It was easy to break out the CloudFront specific logic and to add support for CloudFlare and the other CDNs. My gratitude goes to @andrusha and @manuelmeurer for their work on Middleman CloudFront.

Thanks to @manuelmeurer for helping port this gem for Middleman v4 and numerous other valuable contributions.

Thanks to @b4k3r for the Cloudflare gem that made invalidating CloudFlare files a breeze.

Thanks to @geemus and the many contributors to the fog gem that made invalidating CloudFront easy.

Official gems from Fastly and MaxCDN are used for interacting with their services.

It's becoming increasingly common for static websites to be hosted across multiple CDNs. jsDelivr is a well known promoter of this strategy and it's a strategy I want my toolset (middleman) to support for my next side project.

I've created this extension so that it can grow to support the CDNs we (you and me) are using.