Setting up a Website with GitHub and AWS

18 November 2014

In this post I’ll explain how this site was set up using GitHub for content hosting and revision control as well as AWS (Amazon Web Services) for DNS. I also use Google Apps for Work to manage email, calendar and documents with my flouret.com domain.

I’m posting this as a reference for myself but feel free to adapt to your own situation.

Update: As of August 16, 2017, this site is no longer hosted by GitHub. Instead, the static files produced by Jekyll are hosted in an Amazon S3 bucket.

Rationale

You may be wondering why GitHub, AWS and Google Apps. The main goal is to have a reliable website with minimal cost. I also want to have full control of the data and do not want by site to be stored in a remote SQL database like some CMS systems do. I want to see my files.

Reliability

AWS Route 53 offers a 100% uptime guarantee in their SLA. Amazon is one of the major cloud providers in the Internet and it is extremely reliable. I have previously tried Dyn and No-IP.com as DNS providers and they also have 100% uptime SLAs.

Google Apps offers a 99.9% availability guarantee in their SLA. Google is also one of the major players in the Internet and are also very reliable. Using Google Apps would give my domain email the same or similar reliability as Gmail.

GitHub doesn’t offer a SLA with uptime guarantees but it is a large commercial website and it is probably more reliable than a website hosted on a single server in some unknown data centre. Other alternatives would include hosting directly on AWS, however, I like using git as a revision control system.

Flexibility and Ease of Use

AWS Route 53 is extremely flexible. It allows full control of DNS with all the necessary record types. However, it requires deep understanding of how the Domain Name System works in order to configure it properly. Other alternatives like No-IP.com are much easier to configure but they trade flexibility for ease of use. Also, see price.

The setup in GitHub Pages is also pretty simple but requires using and understanding git obviously. git is not the easiest revision control system to use but it is very, very powerful. In other words, it is the best.

Cost

Content

Cost is one of the major concerns and that makes GitHub an excellent choice as it is free. Although you can pay to make repositories private but I don’t mind having my repositories as public.

DNS

AWS Charges a nominal fee of $0.5 per zone (e.g. flouret.com) and charges based on number of queries as $0.4 per million queries per month. With the expectation of having less than one million queries per month this would total at approximately $0.9/month.

Other services like No-IP.com and Dyn are actually more expensive since the charge an annual fee of about $25.

Google Apps

The biggest cost is Google Apps at $5/user/month. While expensive, it is quite competitive with other alternatives considering it includes all of Google Apps.

The Bottom Line

Service	Cost Per Month	Yearly Cost
GitHub	Free	Free
AWS Route53	$0.5/zone + $0.4/million queries ~ $0.9 per month	~$11
Domain Name	$1 (charged annually)	$12
Google Apps	$5/user	$60
Total	~$7/month	~$84

Setup

GitHub

Create a repository named <username>.github.io which in my case is jpflouret.github.io.
Set the variable $GITHUBUSER to use the scripts below
```
  export GITHUBUSER=jpflouret
```

Initialize the repository and set the remote. Use ssh so that you don’t need to enter the username/password on every push.

                    $ git init $GITHUBUSER.github.io
  $ cd $GITHUBUSER.github.io
  $ git remote add origin git@github.com:$GITHUBUSER/$GITHUBUSER.github.io.git
  $ cat > .gitignore << EOF
  \*.swp
  EOF
  $ git add .gitignore
  $ git commit -m "Initial commit"

                

Initialize Jekyll

                    cd $GITHUBUSER.github.io
  jekyll new .
  git add .
  git commit -m "Initialize Jekyll"

                

To install jekyll itself use
```
  gem install github-pages
```
Push changes to GitHub
```
  git push origin master
```
Visit your new website https://<username>.github.io which in my case is (was) https://jpflouret.github.io Update: removed dead link.

DNS With Amazon Route53

Setting up DNS is by far the most complicated task. This can be done in the AWS Console via a web browser on in the command line. Here I chose to use the command line.

Obtain IAM user credentials from the AWS Web Console

Install and configure awscli and enter the IAM user credentials

                    sudo apt-get install pip
  sudo pip install awscli
  aws configure

                

Set $ZONENAME to use the scripts below. Change this to suit your needs.
```
  export ZONENAME=flouret.com
```

Create the hosted zone

                    $ aws route53 create-hosted-zone \
      --name=$ZONENAME  \
      --caller-reference `date -Iseconds`

                

Note the returned zone id and store it in a shell variable
```
  export ZONEID=<id>
```

Create the A records for the bare domain

                    $ set TMPFILE=$(mktemp /tmp/temporary-file.XXXXXXXX)
  $ cat > $TMPFILE << EOF
  {
      "Comment": "Point domain to GitHub",
      "Changes": [{
        "Action": "CREATE",
        "ResourceRecordSet": {
          "Name": "$ZONENAME",
          "Type": "A",
          "TTL": 300,
          "ResourceRecords": [
            { "Value": "192.30.252.153" },
            { "Value": "192.30.252.154" }
          ]
        }
      }]
  }
  EOF
  $ aws route53 change-resource-record-sets \
      --hosted-zone-id $ZONEID \
      --change-batch file://$TMPFILE
  $ rm $TMPFILE

                

Create the CNAME entry for www

                    $ set TMPFILE=$(mktemp /tmp/temporary-file.XXXXXXXX)
  $ cat > $TMPFILE << EOF
  {
      "Comment": "Point www to $GITHUBUSER.github.io",
      "Changes": [{
        "Action": "CREATE",
        "ResourceRecordSet": {
          "Name": "www.$ZONENAME",
          "Type": "CNAME",
          "TTL": 300,
          "ResourceRecords": [
            { "Value": "$GITHUBUSER.github.io" }
          ]
        }
      }]
  }
  EOF
  $ aws route53 change-resource-record-sets \
      --hosted-zone-id $ZONEID \
      --change-batch file://$TMPFILE
  $ rm $TMPFILE

                

GitHub CNAME

Set the CNAME for the site to be flouret.com (or www.flouret.com if you prefer)
```
  echo $ZONENAME > CNAME
  git add CNAME
  git commit -m "Add CNAME"
```

Test the Website

At this point the website should be working. Check it by going to https://flouret.com also check that www is correctly redirected by visiting https://www.flouret.com.

Don’t forget to push your repository to GitHub.

    git push origin master

Google Apps for Work

Configure Google Apps using the Google Admin dashboard
Set Google Apps to use custom URLs for mail, calendar, drive and sites

Configure Google Apps in Route 53

                    $ set TMPFILE=$(mktemp /tmp/temporary-file.XXXXXXXX)
  $ cat > $TMPFILE << EOF
  {
      "Comment": "Setup Google Apps",
      "Changes": [
        {
          "Action": "CREATE",
          "ResourceRecordSet": {
            "Name": "$ZONENAME",
            "Type": "TXT",
            "TTL": 300,
            "ResourceRecords": [
              { "Value": "\"v=spf1 include:_spf.google.com ~all\""}
            ]
          }
        },
        {
          "Action": "CREATE",
          "ResourceRecordSet": {
            "Name": "$ZONENAME",
            "Type": "MX",
            "TTL": 300,
            "ResourceRecords": [
              { "Value": "5\taspmx.l.google.com." },
              { "Value": "10\talt1.aspmx.l.google.com." },
              { "Value": "10\talt2.aspmx.l.google.com." },
              { "Value": "15\talt3.aspmx.l.google.com." },
              { "Value": "15\talt4.aspmx.l.google.com." }
            ]
          }
        },
        {
          "Action": "CREATE",
          "ResourceRecordSet": {
            "Name": "mail.$ZONENAME",
            "Type": "CNAME",
            "TTL": 300,
            "ResourceRecords": [
              { "Value": "ghs.googlehosted.com" }
            ]
          }
        },
        {
          "Action": "CREATE",
          "ResourceRecordSet": {
            "Name": "calendar.$ZONENAME",
            "Type": "CNAME",
            "TTL": 300,
            "ResourceRecords": [
              { "Value": "ghs.googlehosted.com" }
            ]
          }
        },
        {
          "Action": "CREATE",
          "ResourceRecordSet": {
            "Name": "docs.$ZONENAME",
            "Type": "CNAME",
            "TTL": 300,
            "ResourceRecords": [
              { "Value": "ghs.googlehosted.com" }
            ]
          }
        },
        {
          "Action": "CREATE",
          "ResourceRecordSet": {
            "Name": "sites.$ZONENAME",
            "Type": "CNAME",
            "TTL": 300,
            "ResourceRecords": [
              { "Value": "ghs.googlehosted.com" }
            ]
          }
        }
      ]
  }
  EOF
  $ aws route53 change-resource-record-sets \
      --hosted-zone-id $ZONEID \
      --change-batch file://$TMPFILE
  $ rm $TMPFILE

                

Conclusion

Setting up a website like this should be fairly simple for the technically inclined.