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.
- Creating a repository on
gitLab.comand hosting the website code using gitLab pages.
- DNS Configuration.
- Obtaining SSL Certificates.
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
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
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! 👍
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
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
visibility section. Change the
Pages visibility to
Now, you are good to go. You can share your
gitlab.io url to your friends to see your website.
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 😄
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.
- Name it to the domain that you got Ex:
- Another with
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.
manage. Go to
advanced DNS section. You need to have 4
Host Records like below.
- Add a
A recordwith host as
@and IP Address as
188.8.131.52(This is the IP Address of the gitlab pages) GitLab - Custom domains and SSL/TLS Certificates
- Add a
CNAME recordwith host as
wwwand Target as
<username>.gitlab.io(This will redirect subdomain
wwwto gitlab pages). Remember to replace
<domain>with your own gitlab account
- Add a
TXT recordwith host as
valueset to the text that you picked from the gitlab pages section. This should be the the text after
- Add a second
TXT recordfor your subdomain (www). The host as
_gitlab-pages-verification-code.wwwand 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.
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
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.