The Cookbook: Jekyll
Tags: news, feature, infrastructure, community
Published: 2021-01-25 08:24:54

---
title: "The Cookbook: Jekyll"
created_at: Friday 22 Jan 2021 15:00:00 EDT
author: Montana Mendy
layout: post
permalink: 2021-01-22-jekyll
category: news
excerpt_separator: <!-- more --> 
tags:
  - news
  - feature
  - infrastructure
  - community
---

![Header](https://dev-to-uploads.s3.amazonaws.com/i/x44n0xl7zbu324as5cef.png)

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. 

<!-- more --> 

# 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 

```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](https://docs.travis-ci.com/user/encrypting-files/).

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:

```bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" # in my case "ssh-keygen -t rsa -b 4096 -C "montana@travis-ci.org"
```
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: 

```bash
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:

```bash
cat github_deploy_key.pub
```

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

```bash
touch github_deploy_key.pub
```
Now that you have the key, make sure the proper repo is conditioned: 

```bash
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: 

```bash
travis login --org --auto
```

You'll then want to run: 

```bash
travis encrypt-file 'github_deploy_key' 
```
Make sure you add your `PUBLIC` key as well: 

```bash
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`: 

```bash
#!/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:

```yaml
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!