Hugo Framework and Gitlab Pages

Jan 20, 2021 · 4 min read · git gitlab ·

One of the first ideas to have a website or blog is to use a CMS like Wordpress, Drupal or the good SPIP, all of these developed with PHP and require a database to function, a server or hosting.

One of the solutions that exist to avoid buying a hosting or server is to generate static sites with a tool like Jekyll or my favorite Hugo Framework, these combined with Gitlab Pages or Github Pages.

We already made a post to create a blog with Hugo Framework + Github Pages, this time we will make a small demo to use Hugo Framework + Gitlab Pages, using the default domain as USUARIO.gitlab.io and then we will customize the domain to our own.

Step 1: We started the Hugo Project Locally

After installing Hugo Framework, we can use the hugo command from a terminal to initialize the project.

1$ hugo new site usuario.gitlab.io --force

- We prepare the Website and Git files

1$ cd usuario.gitlab.io
2$ git init
3$ echo public > .gitignore
4$ git submodule add https://github.com/dev_name/theme_name themes/theme_name
5$ echo 'theme = "theme_name"' >> config.toml
6$ hugo new posts/first-post.md

- Gitlab Pages Requirements

Before uploading the project to a Gitlab repository, we edit the .gitmodules file to add relative URLs.

Gitlab uses HTTPS to get source code on shared runners, so:

 1## For a fork that belongs to the same group or user
 2$ vim .gitmodules
 3-- [submodule "themes/theme_name"]
 4-- path = themes/theme_name
 5-- url = ../../dev_name/theme_name.git ## New line
 6
 7## For a project outside the group or user
 8$ vim .gitmodules
 9-- [submodule "themes/theme_name"]
10-- path = themes/theme_name
11-- url = https://gitlab.com/dev_name/theme_name.git ## New line
12
13## Update submodules
14$ git submodule update

- Gitlab CI

We create the .gitlab-ci.yml file to deploy the project when pushing to the repository, the content for this file would be the following:

 1$ vim .gitlab-ci.yml
 2-- image: registry.gitlab.com/pages/hugo:latest
 3-- 
 4-- variables:
 5--   GIT_SUBMODULE_STRATEGY: recursive
 6-- 
 7-- test:
 8--   script:
 9--   - hugo
10--   except:
11--   - master
12-- 
13-- pages:
14--   script:
15--   - hugo
16--   artifacts:
17--     paths:
18--     - public
19--   only:
20--   - master

- Gitlab Repository

To create the repository we must do it with the name usuario.gitlab.io where ¨user¨ is the Gitlab username, you can also create a group and use the group name for the name of repository grupo.gitlab.io.

After creating the repository we add the code, after adding the URL to the project:

1$ git remote add origin git@gitlab.com:usuario/usuario.gitlab.io.git
2$ git add .
3$ git commit -m 'Hugo gitlab page'
4$ git push origin master

- We verify the deployment in the repository

If everything went well we should have an output similar to the image, Repositorio -> CI/CD -> Pipelines.

Then we can check with the URL: http://usuario.gitlab.io

Step 2: Gitlab Custom Domain

With what has been done previously and if there was no problem we can customize the domain to one of our own choosing, for the example we will use the domain domain.com and www.domain.com.

- Creating Domains

In Gitlab we can enter the Repository -> Settings -> Papes space and add the chosen domain and subdomain:

For dominio.com

For www.dominio.com

With these two steps completed we will have the repository and the subdomain with the user ready to work, in the case of the personal subdomain, the necessary records should be created in the DNS server.

- DNS Records and Gitlab Checks

For the root domain domain.com an A record must be created with the following data:

The A record for the root domain domain.com with the value 35.185.44.232, then a TXT record with the values provided by Gitlab Pages.

After creating the records we can verify from Gitlab:

For the subdomain www.dominio.com a record CNAME must be created with the values provided by Gitlab Pages.

The CNAME record for the subdomain www.domain.com with the value "usuario.gitlab.io.", then a TXT record with the values provided Gitlab Pages.

Clone repository

1$ git clone --recurse-submodules git@gitlab.com:usuario/usuario.gitlab.io.git

Delete submodules

1$ git submodule deinit -f -- themes/theme_name
2$ rm -rf .git/modules/themes/themes_name
3$ git rm -f themes/themes_name
4$ git submodule status

References

Translations:

"Spanish" |