My website is constantly undergoing changes. I'm constantly finding things I want to do better, cleaner, simpler. This post details my change from hosting my site on Amazon Web Services to GitHub Pages using Jekyll.
The Problem
I felt the need to move my website from Amazon Web Services (AWS) to something else for a while now for a number of reasons. First, my AWS server is costing me $15/mo and I'm not using it for anything other than hosting my website. At first I tried to convince myself I needed it. After all it was a comprehensive Ubuntu server not just some hosting site I can upload code to. This meant I could host multiple websites all running dynamic web applications, run other webservices, and just have an all around more capable environment. After all, my site was written in PHP and I needed to be able to execute dynamic code, which brings me to the second problem.
I had a dynamic website that ultimately just delivered static content. It was written in PHP, but the most dynamic feature was the copyright statement in the footer automatically keeping the year up-to-date. I just wanted a site where I can include a brief statement about me, share my resume and portfolio, and blog about cool projects I'm working on or interesting topics. Which brings me to GitHub Pages and Jekyll.
The Solution
I had already setup a GitHub Pages project about 6 months ago to start blogging (Clearly, I've used it so much so far). I had my domain (joshkaplan.org) pointing to my AWS instance and blog.joshkaplan.org pointing to GitHub pages and just a link on my homepage pointing to the blog. Not the most elegant way to handle that.
So I decided I'd move the whole website to GitHub pages. I bought a new, cleaner (shorter) domain name (jkpl.io) and found a Jekyll template I liked to start with.
The Process
I started a few weeks ago with the Halve template I found on jekyllthemes.org. I began going through the source code, figuring out how the layout was being generated, and beginning to make my own modifications. I started to tweak the layout, specifically the blog posts themselves. I didn't like that an image took up half the page; it left too little room for content. So I changed the 50-50 page split to 35-65 and broke the template on mobile platforms.
A Note on Web Design and Debugging
- Design for mobile first. It's a lot easier to make something render nicely on phones, then make sure it works on a larger screen than the other way around.
- Get Familiar with Developer Tools. Chrome and Firefox both have a pretty comprehensive set of developer tools. You can inspect the HTML DOM, make style and layout changes on the fly, debug or execute JavaScript, watch network requests and view timing metrics, and a lot more.
A quick Google search for CSS/SASS media queries helped me resolve that one pretty quickly. Once I was more or less happy with the layout it was time to put it all on GitHub pages. I was already using GitHub pages for my blog, so I had to replace my current repo with all the new stuff. I did that, but visiting josh-kaplan.github.io was still redirecting me to blog.joshkaplan.org. Okay, so I removed the CNAME file and made sure there was no special domain name in the repo settings. It took over and hour for the redirect to finally update. I think this was just a matter of GitHub taking time to update the CNAME record. The only real solution there is to take a break and come back later hoping it works.
GitHub Pages, CNAME Debugging, and Interesting Behavior
I noticed that while my root domain (josh-kaplan.github.io) was redirecting, I could directly access some of the subdirectories in the project tree. Visiting josh-kaplan.github.io/posts revealed a list of my posts (with some messed up or missing CSS).
Eventually, the old CNAME record was removed and I was able to test my new content, then add the new CNAME record. I ran into a couple problems I wanted to cover in a little bit of detail:
Problem #1 - Mixed Content
The first big (not that big) problem I ran into was missing CSS. I started
the debugging process by opening Chrome's developer tools and opening up the
network tab. From there you can view all the page requests when you visit a
page. So I refreshed the page and the request for the main.css file appeared
in red and said something about 'blocked/mixed content'.
I mention this issue, because mixed content is something I've run into a few times before. It presents some interesting security topics to be aware of and it's ultimately a very quick fix.
What's causing it? - GitHub pages uses HTTPS by default. Some of the
links in the template (in this case, the link to main.css) began with HTTP.
The page was requested securely via HTTPS, but it links to insecure content.
Why is it a problem? - Mixed content compromises the security of the entire page. Insecure resources can be subject to man-in-the-middle attacks where than content can be viewed or modified. In the case of our CSS file, the damage wouldn't be overwhelming, though it might cause a few headaches. The implications of this same issue with a JavaScript resource can ultimately do a lot more damage to users: an attacker could alter the content of your page, steal user information such as passwords, and more. Google and cio.gov have some really good explanations of what mixed content is and some of the impacts it has.
How to Fix It - GitHub provides a good explanation on how to resolve the issue, but it simply comes down to this: if you're using HTTPS on the site, make sure all resources are also loaded over HTTPS. There are two ways to handle this.
- Make sure all resources explicitly use HTTPS not HTTP.
- Use
//when loading resources. This will load resources with whatever protocol the requesting page was loaded with. This post by Paul Irish explains this in more detail.
Problem #2 - CNAME Records and GitHub Pages
The other major problem I ran into was setting up the CNAME record now that this is my entire site not just a subdomain. First, I bought my domain name through Gandi and it wasn't sure how to do this on their site (I've used Google domains for past domain names). This post by Daniel Spector walked me through the process pretty quickly. After that, I just had to wait for Gandi to update the CNAME record. I called it quits for night and jkpl.io was up the next morning.
The Cleanup
The final thing to do is to remove my AWS instance and redirect my orginal URL joshkaplan.org to my new site.