DNS settings for GitHub pages

Github pages

When setting a blog on GitHub pages I found a bit hard for me to understand what should be set for DNS to run it on my custom domain.

There is quite good introductory for the process in documentation but still I was quite confused at the start. Unknown terms and fact that I’m not familiar with DNS. I mean I haven’t seen it from my college times.

I wanted the following setup

https://github.com/ochaloup/ochaloup.github.io being pointed from domain http://chalda.cz
https://github.com/ochaloup/blog.chalda.cz being pointed from domain http://blog.chalda.cz
www variants points to variant without www (http://www.chalda.cz to http://chalda.cz)

War of terminology

user pages - regards of DNS settings it’s the same thing as organization pages just for a user. A user (me) have only one user personal pages. You can create one when creating GitHub repository <username>.github.io. In my case it’s https://github.com/ochaloup/ochaloup.github.io. Then any static web page content is available at http://ochaloup.github.io.
project pages - project is my blog at https://github.com/ochaloup/blog.chalda.cz. By default is available at http://ochaloup.github.io/blog.chalda.cz.
apex domain - is equal to a term root domain - meaning domain without www or blog. In my case the wording apex domain means chalda.cz

Repository settings

For a GitHub repository being availble on GitHub Pages (meaning under .github.io) you need to set it up. Go by tab Settings at your repository and scroll down to section GitHub Pages. There you change None to a branch that should represent the content of the GitHub Pages.

When you want to use custom domain you need to define what will be at box Custom domain. In my case I want to have the blog available under http://blog.chalda.cz then I set there blog.chalda.cz. My user page should be available under http://chalda.cz then I set there chalda.cz. Now when you do so GitHub starts with automatic recirection to the custom domain. In my case it means that going to http://ochaloup.github.io will automatically redirect to https://chalda.cz.

When you define something into Custom domain box then GitHub automatically creates a file named CNAME with only one line consisting the specified Custom domain. Changing or creating content of the CNAME file has the same result as setting that in the box under Settings tab.

DNS settings

First (probably obvious but…) observation was that changes in settings are propagated really in terms of hours, not sooner [smile o]

After spending some time with help of GitHub documentation and some blog posts similar to this one I got the following settings started to work.

Note	Documentation recommends using `ALIAS` DNS record for apex domain settings than `A` record but `ALIAS` is not available in DNS settings of my provider. I just took a `cz` domain from first offer came from Google search at http://domena.cz.

https://github.com/ochaloup/ochaloup.github.io has custom domain set as chalda.cz
https://github.com/ochaloup/blog.chalda.cz has custom domain set as blog.chalda.cz
DNS settings

@ IN SOA ns1.ignum.com. hostmaster.ignum.cz. 2017020502 10800 3600 604800 3600
@ IN A 192.30.252.153
@ IN A 192.30.252.154
blog IN CNAME ochaloup.github.io.
www IN CNAME ochaloup.github.io.
@ IN NS ns1.ignum.com.
@ IN NS ns2.ignum.com.
@ IN TXT "v=spf1 include:_spf.ignum.cz ~all"
_autodiscover._tcp IN SRV 0 0 443 nmrdiscover.ignum.cz.

For more information on SOA, NS and TXT record check some DNS documentation. Here briefly what I understood - SOA is compulsory, defines who is responsible for domain, NS is required by my provider here and defines where name servers for this domains are, TXT serves information about the server (e.g. dns account info).

Now the A records are needed for apex domain chalda.cz redirection works. It points to GitHub DNS servers diretly. The blog (for redirect to project page) uses CNAME record and points to my github.io. Finally www CNAME record serves to get available my user page at domain http://chalda.cz and http://www.chalda.cz. (TODO: here does not work or what?)

Tools to help

When I start to play with setup I found out two tools helpful.

command dig - dig chalda.cz. With a more consense output dig chalda.cz +nostats +nocomments +nocmd
Chrome developer tools (Ctrl+Shift+I) - got to tab Network, enable checkbox Preserve log and go to e.g. http://ochaloup.github.io. You can see in headers that you were redirected to http://chalda.cz by 301 Moved Permanently. If you do some changes then info that the page was moved permanently is remembered in browser cache and browser then directly shows you the http://chalda.cz without consultation with DNS server (301 Moved Permanently (from disk cache)). To workaround that clear the Chrome’s cache - go to chrome://net-internals, click a small down pointing arrow in right corner and choose Tools → Clear cache from drop down menu.