Jekyll on Amazon S3 part 1

X @urre
This is a post written originally back in 2015. While some principles and techniques may work, a lot of things is dated.


A little post about deploying a Jekyll site to Amazon S3. Assumes that you already have a Jekyll site working.

You will need:

Install Jekyll Assets

Jekyll Assets is great, it lets you do this:

  • Write Sass, Coffescript, Erb…
  • Create dependancies between assets
  • Concatinate, minify with your tools of choice (Uglify for example)
  • Asset fingerprinting
  • Gzipped versions of your assets
  • Native support for custom vendors
  • Autoprefixer support
  • And moore…

In this example i’m going to use finger printing, which means that app.css will use app-908e25f4bf641868d8683022a5b62f54.css. For all other things i will use Gulp instead.

Use RubyGems and Bundler

Create a Gemfile in your root folder, and add:

source ''
gem 'jekyll-assets'

RubyGems Bundler

Install gems

Install by running bundle install

To use jekyll-assets, create a new file called _plugins/ext.rb. Add the following:

require 'jekyll-assets'

Configure Jekyll Assets

In your config file, add this YAML and don’t forget to match your own paths.

debug: false
  - _assets/js
  - _assets/scss

Now when you include your assets, use this tags instead:

    {% stylesheet app %}
    {% javascript app %}


Nothing special here, just the ordinary Jekyll buid process

jekyll build

or, for watching changes:

jekyll serve --watch

Setup deploy settings for Amazon S3

S3 is perfect for storing static assets and static websites. There are a couple of command line tools available out there, in this example i’m going to use s3_website.

Add gem 's3_website' to your Gemfile and install by running bundle install.

API keys

You will find your AWS API Keys in IAM - Identity and Access Management. Look under Users -> Security Credentials.

Never version control your API Keys. Create a .env file in your repo and update your ignore patterns in .gitignore. Add:


Create s3_website.yml in the root folder. This file is going to grab the keys from .env.

s3_id: <%= ENV['AWS_ACCESS_KEY_ID'] %>
s3_secret: <%= ENV['AWS_SECRET_ACCESS_KEY'] %>
s3_bucket: <%= ENV['S3_BUCKET_NAME'] %>

Create AWS user

  1. Go to AWS console -> IAM - Identity and Access Management
  2. Create a user with permissions to S3 and Cloudfront.

Create bucket and turn on static hosting

  1. Create a new bucket in your region of choice
  2. Turn on static hosting. Open up Static website hosting under Permissions and check “Enable Website Hosting”. Add index.html as Index Document

Configure Bucket permissions

  1. Give the user/users access to your bucket by clicking the Permissions tab and “Add more permissions”. Choose “Authenticated Users” and check “List” and “Upload/Delete”.
  2. Click “Add Bucket Policy” on the “Permissions tab again

Paste this:

  "Version": "2008-10-17",
  "Statement": [
      "Sid": "Allow Public Access to All Objects",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::BUCKET_NAME/*"

Remember to replace BUCKET_NAME with your bucket


Test your configuration by running:

s3_website push --dry-run

If everything works:

s3_website push


Your Jekyll powered website is now live on your bucket endpoint. Ex:

Next steps

  • Cloudfront…
  • Custom domain

Next step?

Read Part 2