An adventure in servers & code

Create a jekyll blog & host it on amazon s3

October 05, 2014

What is Jekyll?

Jekyll is a bloging framework that was popularized by GitHub Pages. What makes it unique is that it generates static HTML files from markdown which means you don't need a crazy web-server to run it, all you need is something that can serve HTML & CSS.

That means Uber fast load times, static files can't really crash or fail, and there is no dealing with complex server side software which breaks (well I manage to break it) all the time.

Cool, why host on S3?

You can host it on any server you want, simply generate the static files and drag and drop them to your el-cheapo $4.99/mo server, use github pages, or even Heroku.

S3 for me was the cheapest and I know my site will always be available, I can use route 53 for my DNS & Cloudfront as a CDN, and get of those low latency, high data transfer speeds that come with it.


Jekyll Setup

First Install Jekyll, you'll need Ruby to install the gem.

$ gem install jekyll

Next we'll be creating a new jekyll site, this will generate all the files necessary to run your blog locally, make sure you're in the place you want to create it, for me it's ~/daniel.whyte/work

$ mkdir work
$ cd work
$ jekyll new my-awesome-site

Jekyll generated a number of files within ~/my-awesome-site, you can edit and style these files until your heart is content. It's important to note, files prefixed with _ will not be included in the final build, as they denote being partials.

Here's a quick rundown on what you just created:

_config.yml  #Settings, set things such as your site's title & your email
_includes    #Partial files, such as header & footer
_layouts     #Page layouts for your homepage & your blog posts
_posts       #This is where you write all your blog posts
_sass        #SASS partial files
about.md     #Turns into about.html
css          #SASS files in here will compile to CSS
feed.xml     #XML Feed is auto generated
index.html   #Your index document

Next we'll navigate to our new site, and run jekyll serve, which will start a local http server and track any changes to the files and update the generated web page on the fly.

$ cd my-awesome-site
~/my-awesome-site $ jekyll serve

Jekyll Command

Now if we navigate to http://localhost:4000 in your favorite web browser, You should see the image below, if so, congrats, you've setup your Jekyll Site, and it's working as intended.

Jekyll Started


Setup S3 Bucket

Amazon have a pretty good Documentation around setting up an s3 bucket for use with a website follow the steps, and take note of your s3 bucket name.

Setting Policy

If you don't set your bucket policy, then when you run your build script, and everything get's uploaded to your s3 bucket, when you try to visit your new shiny website, you're going to get a 403, meaning 'everyone' accessing your website via the buckets public URL do not have the permission to read your super sweet blog, this policy gives 'everyone' those read permissions.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AddPerm",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::danielwhyte.com/*"
    }
  ]
}

Installing S3 Website

s3_website is a tool that allows you to upload websites to amazon s3 via the command line, and it supports Jekyll.

s3 website needs both Ruby and Java to run. (S3 website is partly written in Scala, hence the need for Java.) If you try setting it up and it requires you to update java, it will let you know.

So first, let's install s3 website:

$ gem install s3_website

Setup AWS credentials

Next, you'll want to setup your AWS credentials.

  1. Create an AWS Account or login
  2. Open the AWS IAM console
  3. Create a new user, be sure to take note of the access Key ID & Secret Access Key.
  4. Assign full permissions to the S3 and CloudFront services

s3_website

Now we run s3_website cfg create this will create 3_website.yml which we store our access keys and target bucket along with a bunch of other things you may want to configure.

$ s3_website cfg create
#open s3_website.yml in your favorite editor
$ subl s3_website.yml

Now you want to copy & paste those keys that you took note of back when you created the new user, along with the bucket you created earlier.

# Contents of s3_website.yml
s3_id: access Key ID
s3_secret: Secret Access Key
s3_bucket: danielwhyte.com

Creating A build Script

create a new file caled deploy.sh and copy & paste the following:

echo "Building blog"
jekyll build
echo "Deploying blog to s3"
s3_website push

now when you want to deploy a new build of your website you can just run:

$ sh deploy.sh

Here's what it should look like:

s3_website


I hope this is of some help, Jekyll is a pretty powerful tool, and if you like to write in markdown it's perfect. If you're still unsure about some things or having some problems, leave a comment and perhaps I can be of some help.

Writen by Danielwhyte

Daniel is a UX & UI Designer focucused on building better software for iOS & Mac in Melbourne, Australia