How to run and deploy gitlab pages on your own domain
Not so long ago I had to make a static website, and was figuring out how to do this. I came across hugo. And I really liked how quickly you can build and publish a website from markdown.
A while ago google made the .dev available for peanuts, so, impulsively, I bought one. From $12 you can get one, and start doing awesome stuff with this. But I didn’t. I parked the domain for a while. There are plenty of cloud providers that will host your website for you, like AWS, Netlify and many more.
But I had no clue where to host this, because I am lazy and cheap. Then for work I had to do something similar, and I wondered if I could just host my GitLab Pages on my own domain. And guess what, you can, and it is amazingly simple!
I started to write out some boilerplate (easy), picked a theme I liked (easy, I used m10c), and off I went.
Here I will try to explain how I got from writing some basic markdown to running it on my own domain (well, technically it doesn’t. But it appears so).
You can find the repository of this site here. I like
Therefor I will use the
yaml configuration option from hugo.
My config is as follows, but also available here
title: Rik de Groot baseURL: https://www.forsure.dev/ enableRobotsTXT: true languageCode: en-us assetsDir: content/assets themesDir: themes metaDataFormat: yaml permalinks: posts: /-/:year/:month/:day/:title tags: /:slug paginate: 10 theme: m10c enableGitInfo: true googleAnalytics: <GA tracking code> # enable auto code highlighting without effort pygmentsCodefencesGuessSyntax: true pygmentsUseClasses: true pygmentsStyle: monokai pygmentsCodeFences: true # Site parameters params: author: Rik de Groot description: Code, cook and bake. Tech Lead @FinLeaseNL avatar: assets/images/rik-de-groot.jpg images: - assets/og/cover.png social: - name: gitlab url: https://gitlab.com/hwdegroot - name: twitter url: https://twitter.com/hwdegroot - name: linkedin url: https://www.linkedin.com/in/rikhwdegroot/ ## Use the green styles style: darkestColor: "#282e37" darkColor: "#3d434c" primaryColor: "#67eba2" lightColor: "#d3d3d3" lighestColor: "#fff"
The nice thing about using the tools that are popular, is that a lot of people already figured out stuff for you. All you need to do is Google it. So I did. You can find all about deploying a hugo app to GitLab pages in this example.
I used the following
.gitlab-ci.yml configuration to get the job done. Gitlab published a docker container,
that can be used to build your project (see the above example form GitLab). But I like to have the extended features as well, so I created my own which is available in the container registry of the project. But not too much credits to myself, because I based it on the container from jguyomard.
You can find the project on GitHub.
# .gitlab-ci.yml stages: - pages # the theme is submoduled, so make sure to do a recursive clone variables: GIT_SUBMODULE_STRATEGY: recursive pages: stage: pages image: registry.gitlab.com/hwdegroot/forsure.dev/hugo:latest before_script: - git clean -ffdx script: # files are in a subdirectory of the project - cd site - hugo --contentDir content/ --config config/config.yaml --destination ../public/ artifacts: paths: - public only: - tags - main
Now that you build your static site in GitLab, and deploy it to GitLab Pages, you can add your own domain to GitLab pages by following a few steps.
Add your domain to GitLab Pages
Now we can add the domain to GitLab Pages. In your project, go to
Pages. Here click the
New domain button.
Fill in your domain, and set the
Automatic certificate management using Let's Encrypt switch on.
Verify your domain
To verify your domain, you will need to add two fields to your DNS. I am using Google domains, but it is all more or less the same. All you need is privileges to alter the DNS settings of your domain.
Youl will have to add two records, so GitLab can verify you own the domain.
First you will have to add a
<www.yourdomain.dev> CNAME <yourusername>.gitlab.io. to forward the url to gitlab pages,
TXT record to verify the domain is yours
_gitlab-pages-verification-code.www.yourdomain.dev TXT gitlab-pages-verification-code=<somerandomcode>.
Then hit the
verify button. It might not work straight away because the records need to be synced. But in my case it was less than 5 minutes.
If it worked, the status will change to verified
And in the overview, you will see that your domain is listed in the
Access pages section
Add a let’s encrypt certificate to your page
Gitlab has this great help on how to use let’s encrypt in combination with GitLab Pages. Following the steps from their manual will get you all you need to register your https certificate to your domain.
I had to register using
certbot. Just install the binary using the package manager of your OS.
certbot certonly -a manual -d www.forsure.dev --email firstname.lastname@example.org
And it gave me the code in return of format
A.B. Mine looked like
then create a directory
public/.well-known/acme-challenge/A, in my case
Inside this directory, put a file
index.html with the full
A.B key in it, just as suggested by the certbot output
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - NOTE: The IP of this machine will be publicly logged as having requested this certificate. If you're running certbot in manual mode on a machine that is not your server, please ensure you're okay with that. Are you OK with your IP being logged? - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - (Y)es/(N)o: y - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Create a file containing just this data: MXDCs3RTdKM5KNIJFbogSwTLoiduCbtyHKZ2k1zxvWQ.JEZ1UZmU4x3wCgSiV9gom4Irb8AgSkVFrsCju6sFLa8 And make it available on your web server at this URL: http://www.forsure.dev/.well-known/acme-challenge/TfBYIcpd4uO4y4kkH3GAYdsUXeCycAYLPcsF6JEiq1I - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
At this point, pause. DO NOT continue yet. If you did, no problem. Validation will fail, but the next time you run it, you will get the same code.
So the file
public/.well-known/acme-challenge/MXDCs3RTdKM5KNIJFbogSwTLoiduCbtyHKZ2k1zxvWQ/index.html would look like
<!-- index.html --> MXDCs3RTdKM5KNIJFbogSwTLoiduCbtyHKZ2k1zxvWQ.JEZ1UZmU4x3wCgSiV9gom4Irb8AgSkVFrsCju6sFLa8
Basically that is it. You can continue the certificate registration, although it will probably fail. Make sure that GitLab deploys your
pages with the certificate directory
.well-known/acme-challenge/A in it. You can check this by visiting
https://<your-domain>/.wel-known/acme-challenge/A/. It should serve you this html page with the key in it. Then you can run the
certbot command again, and it should present you the success message
IMPORTANT NOTES - Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/blog.rikdegroot.dev/fullchain.pem Your key file has been saved at: /etc/letsencrypt/live/blog.rikdegroot.dev/privkey.pem Your cert will expire on 2019-10-17. To obtain a new or tweaked version of this certificate in the future, simply run certbot again. To non-interactively renew *all* of your certificates, run "certbot renew" - If you like Certbot, please consider supporting our work by: Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate Donating to EFF: https://eff.org/donate-le
Hope it helps