= DNS settings for GitHub pages
chalda <ondrej.chaloupka@proton.me>
1.0, 2017-05-06

:icons: font
:toc: macro

:page-template: post
:page-draft: false
:page-slug: dns-settings-of-github-pages
:page-category: devops
:page-tags: GitHub, DNS
:page-description: How to setup DNS to work with GitHub pages.
:page-socialImage:


toc::[]


== 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
https://help.github.com/articles/using-a-custom-domain-with-github-pages/[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 https://help.github.com/articles/custom-domain-redirects-for-github-pages-sites/[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 icon:smile-o[]

After spending some time with help of https://help.github.com/articles/troubleshooting-custom-domains/[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.