Using a custom domain with GitHub Pages
Tags: github, webdev, devops
Published: 2020-08-07 14:42:38

*This blog is part of a series where I document rebuilding a website that relies on HTML, CSS and Bootstrap in React.js using the Next.js framework to improve performance, reduce costs and increase my workflow for future changes.*

The finished website (hosted on GitHub Pages): https://wallisconsultancy.co.uk
The source code: https://github.com/james-wallis/wallisconsultancy

## Using a custom domain with GitHub Pages
[Configuring a custom domain for your GitHub Pages site - GitHub Docs](https://docs.github.com/en/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site)

In my [previous blog](https://dev.to/jameswallis/deploying-a-next-js-app-to-github-pages-24pn) I demonstrated how to run a static website on GitHub Pages. But it was using a default domain name specific to GitHub as wasn't very professional. We can fix this by making it accessible using our own domain name of choosing (wallisconsultancy.co.uk in my case).

Let's modify GitHub Pages to use a custom domain. This will be done in three steps:
1. Modify `.travis.yml`
2. Add custom domain to GitHub Pages
3. Update DNS settings

### Modify `.travis.yml`
First we need to modify the `.travis.yml` file we created in the previous to add a `fqdn` field.

The `fqdn` field tells Travis to create a `CNAME` file with our domain in each time we push to the `gh-pages` branch. If we don't keep creating this, it will be deleted on the next push.

```yaml
language: node_js
node_js:
  - 12
cache:
  directories:
  - node_modules
script:
  - npm run eslint
  - npm run build
  - npm run export
  - touch out/.nojekyll
deploy:
  provider: pages
  skip_cleanup: true
  github_token: $github_token
  local_dir: out
  fqdn: wallisconsultancy.co.uk # This instructs Travis to create a CNAME file with wallisconsultancy.co.uk as the contents on every deployment to the gh-pages branch
  on:
    branch: master
```

### Add custom domain to GitHub Pages

Next we need to tell GitHub that we are going to use a custom domain.

To do this:
  1. Go to the settings of your GitHub repository for the project
  2. Scroll to the GitHub Pages section
  3. Enter your domain in the Custom Domain section

![GitHub Pages settings with a custom domain](https://dev-to-uploads.s3.amazonaws.com/i/g0j4lb41uyijrfopzjj0.jpg)
*GitHub Pages settings with a custom domain*

Your `.github.io/repository` domain will now redirect to your custom domain. 

However, the website will not yet be reachable as we need to update the DNS settings for the domain name.

### Update DNS settings to point to GitHub Pages

Now GitHub Pages is expecting to be reached via a custom domain and will redirect the old `user.github.io/` to it. We now need to set the domain up so that it points to the GitHub server where the website is being hosted.

To update the DNS settings you need to go to your DNS provider and do the following:
*Note: I am using Digital Ocean so all the examples are using their UI*

Create a `CNAME` for `www.yoursite.com` that points to your `.github.io` address without the subpath.

Example:
![CNAME record settings Digital Ocean](https://dev-to-uploads.s3.amazonaws.com/i/236sslsn2bseivwxdts2.jpg)
*My CNAME record settings on Digital Ocean*

*Optional, using an apex domain rather than `www.`*

If you want your domain to be `yoursite.com` rather than `www.yoursite.com` you need to do a further step.

Create an `A` record to point to the following IP addresses ([check the GitHub docs to verify they haven't changed since the writing of this post](https://docs.github.com/en/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site#configuring-an-apex-domain).

Example:
![A record settings Digital Ocean](https://dev-to-uploads.s3.amazonaws.com/i/rcxyw55khfe8vw2oeat7.jpg)
*My A record settings on Digital Ocean*

**That's it**
You've successfully setup your website to run on GitHub pages using a custom domain name. It might take a few minutes for the DNS changes to update but soon your website will be production ready!

*Note: If you modified your code for the GitHub subPath issue above, you can now tear this code out.*

## Roundup
This blog demonstrated how to setup a Next.js website onto GitHub Pages with a custom domain name.

The Wallis Consultancy website is now published into production. This marks the end of the series of blog posts in which I rebuilt the old Wallis Consultancy website that ran using Bootstrap in React.js using Next.js and finally hosted it on GitHub Pages.