Build Websites with Hugo - Part II

8-minute read
Sharan Katragadda
Website • Hugo
Featured image

Hello! Welcome back! 👋

If you are coming from Build Websites with Hugo - Part I post, then you are on the right track. If not, please read the part-I to cover the initial steps to setup the domain and offline hugo server.

While my memory is still fresh, I thought it’s best to document my work here. I’m hoping the article would help someone out there in the world looking for the setup process.

Steps to go through

For the part-II, we’ll be covering below steps. We’ll see how to create a repository on gitlab, and connect our local repo to it. We’ll adjust the DNS configurations on the gitlab repository and as well as on our domain provider side. By then, we are pretty good! Lastly, we’ll get the SSL certificates to make sure our website is secure.

  1. Creating a repository on gitLab.com and hosting the website code using gitLab pages.
  2. DNS Configuration.
  3. Obtaining SSL Certificates.

GitLab Setup

Head over to the gitlab and create an account if you have’t already. If you already have an account, that’s a good start! Create a brand new repository for the website. You can name it whatever you want.

Run below command on your local machine to pull a copy of the online repository you just created to your local machine. This will ensure you have a copy. We’ll use it interact with our online repository. Though it is empty, we’ll add files shortly.

## To download the online repository to your local machine.

git pull <https clone url>

Now, you have the repo offline. Empty repo! Not exactly empty, it should have readme.md and .git directory.

Move the contents of your project from Build Websites with Hugo - Part I (wherever you did the offline setup on your machine) to this empty dir. Make sure you have .gitignore as well. It’ll ensure we are not uploading the themes directory and hugo.exe(windows only) files.

Once the contents are moved, your setup is ready to upload to the gitlab. Run below series of commands under the root dir of your project repo.

## To get the current status of your git at any point during the push /pull process.

git status

## Add modified contents to the local commit status
## .(dot) signifies all files 
## If you need to add specific files, mention the files with appropriate extensions

git add . 

## committing the changes. Text under quotes can be changed

git commit -m "base website"

At this point you have successfully uploaded your offline project to gitlab. You can verify this by logging into the gitlab account and verifying the contents of your repository.

Create .gitlab-ci.yml for CI/ CD Pipeline

Let’s create a CI/ CD pipeline on gitlab for our website repository. If you have noticed, in the Part-I, we have skipped the .gitlab-ci.yml file creation. This is because, it’s a lot easier to pick the default template from the gitlab itself rather than doing our own sorcery. The other reason is, I didn’t wanted to provide a file that is obsolete. Instead, we can create one on the gitlab that is current and latest to the standards.

Click on the new file to create a file. It’s available in the drop down next to the repository name that has a $+$ sign. Alternatively, you can also click on the CI/ CD configuration bun icon in your repository root dir to automatically create the .yml file. Name the file as .gitlab-ci.yml and select the template as hugo. It’ll pick a default template that works for majority of the deployment cases. Or, you can look at the reference code below. In the below code, --debug is optional. I have it because it’ll give you additional information to debug, should your deployment fail. Otherwise, completely optional!

# All available Hugo versions are listed here: 
# https://gitlab.com/pages/hugo/container_registry

image: registry.gitlab.com/pages/hugo:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test:
  script:
  - hugo --debug ## --debug is optional
  except:
  - master

pages:
  script:
  - hugo --debug ## --debug is optional
  artifacts:
    paths:
    - public
  only:
  - master

Add a commit message and click commit changes. We are good! With this file in place, the repository is telling the gitlab to build the code changes whenever a change is detected in the repository. Meaning, whenever you write a new blog post or change the menu items in the look and feel of the website, it’ll be build immediately without any manual intervention. Pretty cool! 👍

GitLab Pages

Now, head over to the Pages sub-menu under settings. We’ll be setting up our static webpage configuration under this section. You should already see a page url that should look like this http://<username>.gitlab.io/<reponame>. Go ahead and open that url in your browser. It should show your website hosted using gitlab pages.

After the first deployment the site looks messy, no css and nothing would be aligned properly. 😱 🤯

DO NOT PANIC! This happens because your base URL in config.toml file is set to your domain name (or your gitlab.io page). To test the gitlab deployment, you can change the baseurl to this <username>.gitlab.io/dotcom, and it should work! But once you have your custom domain configured (which will be done in the further steps down in this article) you can change the baseurl to your new domain ksharan.com.

Changing the visibility

The URL is private, just available to you. You can’t share it and expect friends to see the website. To change the visibility settings, head over to the general under settings and expand the visibility section. Change the Pages visibility to everyone

visibility _gallery ><

Now, you are good to go. You can share your gitlab.io url to your friends to see your website.

DNS Configuration

If you want to setup a custom domain, like the one that we bought in the part-I, then we need to do the DNS configuration step. It’s a two step process! OMG!! So many steps 😄

GitLab Pages

Under the Pages section in settings menu, click on the New Domain that’s available on the top right corner of the page. I hope it’s still available there. You need to add two domains.

  1. Name it to the domain that you got Ex: ksharan.com (main domain)
  2. Another with www.ksharan.com (sub domain)

For each of these, you’ll see that you are provided with a DNS CNAME entry, and as well as DNS TXT entry. These are crucial and needed to verify your domain ownership. Save a copy of these and head over to the next step (DNS provider portal)

DNS provider portal

Let’s login to the namecheap.com or whoever is your provider, and add DNS entries with the values that we saved from the previous step.

Under dashboard click manage. Go to advanced DNS section. You need to have 4 Host Records like below.

  1. Add a A record with host as @ and IP Address as 35.185.44.232 (This is the IP Address of the gitlab pages) GitLab - Custom domains and SSL/TLS Certificates
  2. Add a CNAME record with host as www and Target as <username>.gitlab.io (This will redirect subdomain www to gitlab pages). Remember to replace <domain> with your own gitlab account username
  3. Add a TXT record with host as _gitlab-pages-verification-code and the value set to the text that you picked from the gitlab pages section. This should be the the text after TXT word. Example: gitlab-pages-verification-code=xxxx
  4. Add a second TXT record for your subdomain (www). The host as _gitlab-pages-verification-code.www and the value set to the text that you picked from the gitlab pages section.

At this point you have included the entries provided by your gitlab pages domain. Now, one last time, let’s head back to the gitlab to verify the changes.

Verify on GitLab Pages

Let’s head over to the Pages section again, and for each domain, click verified (click the refresh symbol) to verify the changes that you just made. It’ll turn to green sign. Usually within few minutes. Once you see the green sign, your website should be up immediately! You can head over to the website with the domain https://<yourdomain>.com that you purchased to verify it.

SSL Certificates

Now, you can visit your website through the domain. Your browser might complain about the insecure connection. You need to check the checkbox under the pages section that says Force HTTPS (requires valid certificates). Because we have already verified our ownership, this step should work.

Also, under each domain, you should see an option to enable the Let's Encrypt. It’s usually a toggle sign. Here’s the tutorial. It’ll take anywhere from 30 mins to 1 hour for you to receive the SSL certificates. Note - Issuing the certificate and updating Pages configuration can take up to an hour. Once this step is done, your website should have a padlock symbol next to the URL. It signifies that your connection is secure.

Well done! 👍

The website setup process is completed. All that is needed now is to add your valuable content and make it count.

References