The Cookbook: Jekyll

GitHub Pages are an amazing way to host Jekyll pages, but in some cases, you might be interested in running your Jekyll page on a different host (like Azure Web Apps, Heroku, AWS). In this Cookbook let's setup a DevOps Build Pipeline that takes commits, run smoke screen testing, and actually deploying.

Getting started with Jekyll

Ideally with Jekyll, you want a compile script (obviously in bash) that traverses to an out/ directory. For sake of this example, you can call the bash script anything but I'm going to call it jekyll.sh. Your project may require something different, for example npm build or something to that extent.

When creating the file tree/structure, let's make sure the out/ directory contains almost or essentially everything you want deployed to gh-pages. In a case like this, you will 95% of the time have a index.html file.

Check this script into your project. Now this is just an example, now let's say the script just reads (remember, your script might just read npm build:

Using Bash

#!/bin/bash/env sh 

# only let the script proceed when started not by a pull request (PR)

if [ $TRAVIS_PULL_REQUEST == "true" ]; then # you can make this more strict via "==="
  echo "this is a PR, exiting now"
  exit 0
fi

# enable error reporting to the console & log that into a file entitled "log.txt" 

set -e

# build site with jekyll, by default to `_site' folder

bundle exec jekyll build

# find ./_site -name "*.html" -exec bundle exec htmlbeautifier {} \;

bundle exec htmlproof ./_site --disable-external --check-html --verbose

# cleanup using `rm -rf`

rm -rf ../Montana.github.io.master

Travis and adding Travis to your project

We assume you have one, but if not get a Travis account at https://travis-ci.com/. Turn on Travis for the repo in question, using the Travis GUI.

Encrypted credentials

If you read the Cookbook Series: Encryption, you can most likely skip over this, but if you haven't - when you deploy using Travis, ideally you want to deploy gh-pages without checking in the necessary credentials to your repo, this can be done using encryption.

Next up, you'll want to generate a SSH key. The advice I always give is to never reuse SSH keys. To generate a new SSH key, you'll want to open a terminal and run:

ssh-keygen -t rsa -b 4096 -C "[e-mail]" # in my case "ssh-keygen -t rsa -b 4096 -C "[e-mail]"

You'll be prompted to do a few things, one thing you want to remember is you do not want to include a password, just press enter when prompted, then follow the next prompt and continue. You'll now want to add the deploy key to your repo, and remember do not reuse SSH keys. You can do this via:

https://github.com/<github_username>/<your_repo>/settings/keys # add the deploy key to your repo

Now it's time to encrypt the key that was generated using the Travis CLI client. So now let's demonstrate on how we would add your deploy key to your specified repo.

Adding your encrypted vars

First, let's open an editor so we can view the dpl key, so let's run:

cat github_deploy_key.pub

You can also use touch, so instead of cat, it would be:

touch github_deploy_key.pub

Now that you have the key, make sure the proper repo is conditioned:

https://github.com/<github_username>/<your_repo>/settings/keys # add the deploy key to your repo

Now let's use Travis again from the CLI again to login:

travis login --org --auto

You'll then want to run:

travis encrypt-file 'github_deploy_key' 

Make sure you add your PUBLIC key as well:

git add 'github_deploy_key.enc'

The bash script I've coded below automates the above process essentially, I did this to make it a bit easier on the Travis CI user, for the sake of time lets say this bash script I created is called dpl_key:

#!/bin/bash/env sh 

set -e

if [ -z "$GITHUB_TOKEN" ]; then
  echo ""
  echo "GITHUB_TOKEN environment variable is missing"
  echo ""
  echo "Travis dpl_key generator" 
  echo ""
  echo "This generates a public/private dpl_key, add the public key as a deploy key
  with write access to the origin remote github repo, encrypt the private key as
  github_deploy_key.enc and add the configuration necessary to use it in your .travis.yml file"
  echo ""
  echo "Give it a shot:"
  echo ""
  echo "  GITHUB_TOKEN=\`cat ~/secret/GITHUB_TOKEN\` ./generate_travis_deploy_key"
  echo ""
  echo "where ~/secret/GITHUB_TOKEN is a file containing a github token with write access to the current repository : (origin)"
  echo ""
  echo "You must have the Travis executable installed on your system and available in the PATH"
  echo ""
  exit
fi

url="$(git config --get remote.origin.url)"
reponame="$(echo $url | cut -d/ -f2 | cut -d. -f1)"

# generate a new private and public key

ssh-keygen -t rsa -b 4096 -f github_deploy_key -N '' -C $url -q 1>/dev/null

pubkey="$(cat github_deploy_key.pub)"

# add the PUBLIC key to the github repository as a deploy key with write access

curl https://github.com/<github_username>/<your_repo>/settings/keys -H "Authorization: token $GITHUB_TOKEN" --data @- << EOF
{
  "title": "travis deploy key",
  "key": "$pubkey",
  "read_only": false
}
EOF

# use travis to encrypt the private key as github_deploy_key.enc and remove the private key

travis encrypt-file github_deploy_key --add --no-interactive -w /tmp/github_deploy_key -f --pro
git add github_deploy_key.enc

# cleaning

rm github_deploy_key
rm github_deploy_key.pub

# bash script by montana mendy

.travis.yml

So, this is a .travis.yml file I've created, as you can see if you use my config it will automate the deployment for you, if you'd like to deploy manually, then just remove the line:

language: generic # this doesn't install any environment at all 

before_install:
- bash chmod +x ./dpl_key.sh # will give proper permissions via chmod to both scripts 
- bash chmod +x ./jekyll.sh

branches:
  only:
  - master

before_deploy:
- openssl aes-256-cbc -K $encrypted_0a644212b3ae3_key -iv $encrypted_0a644212b3ae3_key -in deploy_key.enc -out deploy_key -d


deploy:
  provider: pages
  local_dir: out
  deploy_key: deploy_key
  edge:
    branch: master

Now you should have 3 files, the ones we have talked about, jekyll.sh, deploy_key.enc and your .travis.yml. Make sure you've logged into Travis, let Travis know about the repo via syncing, once you push to GitHub it will compile and deploy your source, either using my bash script or doing it step by step.

Conclusion

I hope you learned some niche ways on deploying source while using Travis, until next time!