Failing Horribly Creating a Blog

One might be surprised but those who know me won’t. One day I was trying to solve a problem with some code and after few google searches I end up browsing through one blog. I don’t remember the site nor the solution I found there but one thing stuck in my mind. I need my own dev blog! “Ok, but what are you gonna write about? You are the one looking for help, you don’t have anything to share with others.” I thought to myself. Anyway as a proper developer I created subdomain on my website and let it rest for a while.

Domain name must be properly rested

A month passed by and as the poor subdomain collected dust I was kind of sorry for it and decided to start building the blog. I knew that it is not going to be easy and today I wouldn’t hesitate to call it difficult process. First things first, I had to choose a blog platform. There are plenty of reasonable ‘ready to blog’ choices but I obviously wanted something more developer worthy. Something you can and you will play with, change the layout you don’t like, add link here and remove there, write it in markdown and also version control it with git. After quick research I decided to use one of many static site generators. I set filters on SSG comparison tool to my taste, got a few adepts and finally I picked Hugo.

It is simple, fast, supports markdown, has nice themes and it is even preconfigured in GitLab pages! What more could I wish? Let’s get to work. Fork the GitLab template, clone it, setup test pages and write some lorem ipsum content. And it works! Out of the box, no need to setup anything, everything prepared for you. Nice. So far so good. Let’s add some pretty theme. Search the theme library for some simple, responsive, black and white theme and let’s go and install it. I picked pixyll but hold on, here it comes, first troubles.

Git has submodules? What is that?

Apparently Hugo themes use tool called submodules. That is something I never heard of and I use git on daily basis (meaning I only know 3 basic commands). So let’s find out what is it good for? After reading the docs it suddenly makes sense. So I can have other git repositories inside my own? Nice. I already know few projects I would use this feature if I knew it before. Now I can proceed with the theme. So install it using git submodule add, configure hugo config, build on local and voila, themed blog. But wait a second. Now that I look at it I don’t like the main layout very much, date is in wrong format and I would slightly change the footer. How do I do that? The theme itself doesn’t offer much of a config options so let’s dig deeper into it. Update the templates in the pixyll folder with a little bit of test and fail and I’m happy now.

But I still haven’t used my precious domain. I can leave GitLab pages now and write some CI/CD script for auto deploy to my web hosting. I’ve already written few simple CI scripts so it should be done save and sound. Simple .gitlab-ci.yml done and we can push all our work. Wait a second. Why do I have things from my submodule theme in staged files? Oh I changed them. But now git wants me to clear the changes made to that repository. I don’t want to commit them (I also can’t). So what now? It was late and I didn’t want to resolve this issue so I decided to simply copy the changed files, remove the added submodule and push the theme as if it was part of my repository. I will fix this later (never?). Pipeline is running, everything looks promising. Blog is built and now only deploy is missing. Do you think it passed? You are right it didn’t. I’m using alpine-hugo docker image for build and deploy with lftp installed to synchronize with my web hosting. Unfortunately my provider doesn’t support verifying of ssl certificate. So turn off verification and deploy again. Well the blog was online, subdomain was finally filled with content. The only problem is that it is dummy content and after month and few days I still haven’t written single post. Oops. So maybe next time?

Write some posts, common!

Another month later, still no post but while doing other stuff I came across interesting css framework which would suit my blog just perfect. PaperCSS the less formal framework, as it presents itself. Exact fit for my less formal blog. So instead of writing some post lets change the theme.

I already know how to work with git submodule so I install the theme and try to run Hugo. Error. The theme supports only higher version of Hugo. But how is that possible, I installed Hugo from debian package shared with ubuntu. Check version, only 40.x when current is 58.x. Well do I really need Hugo installed. Wouldn’t it be nice if I only have Hugo in docker? Then on other machine I only need docker and it will take care of everything.

So I took woahbase/alpine-hugo:latest docker image used in .gitlab-ci.yml, put it in docker-compose file and tried to run it. Container runs but I’m not able to connect trough localhost even though I exposed port. When something doesn’t work call your friend google. After 20 minutes of reading docs, stackoverflow questions and some blog posts I still didn’t know the issue. I’m guessing some setting in the docker image itself? I will have to look at it more in detail later. Anyway I picked different image yanqd0/hugo which offers docker-compose config in its description and it works right away. Great. So I can run the blog with new theme. Try deploy to my web hosting, wait for it, it fails. Luckily I see the mistake immediately, the git submodule of the theme isn’t pulled in the CI/CD pipeline. Just add GIT_SUBMODULE_STRATEGY: recursive so that GitLab automatically pulls latest theme files and done.

Check the website. It works. One tiny detail, there is no theme background. Hmm, it loads from bad url. And also links don’t work properly. Ah, I forgot to set baseUrl in Hugo config. Fix it, try it on localhost, still not fixed. After a while I realized I’m working on newly installed machine and chrome does cache sites by default. Now it works properly and I can deploy. Everything setup? Yes. Let’s finally write the post!

Hugo does provide command for post creation. Simply run hugo new content/post/post-name.md. Not error but warning. I still have lower version of Hugo locally so I will need newer one anyway. Install it from binary and run the command again. Finally everything works and I can focus on the post writing. And here we are. First post done and it took just about 2 months. Let’s summarize it:

Summary