blog/content/posts/how-to-blog.md

+++ date = '2024-11-27' title = 'How to Host a Simple Blog' tags = ['howto', 'tutorial', 'web'] categories = ['technical'] +++

No. I don't want to have a git repository with a million billion files that are auto generated by hugo, jekyll. No. I don't want to use some non-official, homebrew, backwater, docker image made by some random guy that stopped maintaining the image in 2011. I want my own dockerfile that is based on alpine or even use an image official to the framework. No. I definitely don't want to use a WYSIWYG (What You See Is What You Get) editor - I have my own local markdown editor that works just fine thank you. All I want i one (1) - i repeat - ONE fucking goddamn configuration file for the entire site (toml, conf, yaml I don't care) and blog posts should be written in markdown.

If you are like me, read on.

Additionally, there should be community made themes available - but I shouldn't have to fucking add them as a git submodule, god damn. The blog should be hostable through a docker image that just takes your markdown and config file, builds the static website, and serves it using some standard server (e.g. nginx or python's http.server I don't care which, as long as it is somewhat standard - If I am managing a docker container, I will manage the networking in docker)

Ideally, the directory structure should look like this:

blog
├── Dockerfile      // dockerfile to build and host the site
├── README.md       // info about the repository, not a blogpost
├── hugo.toml       // blog-framework configuration file
├── content
│   ├── about.md    // the "about" page
│   └── posts       // actual blog posts go here
│       └── example.md
└── static          // non-markdown files
    └── example.png

And then to build the site, simply build the container:

docker build .

Then you should just be able to insert the docker image into some docker-compose or kubernetes stack - or even just docker run -d if you'd like. The point of this is that you should really just focus on writing the blog entries - not the blog website.

If you want to use this workflow - this blog is written using this approach, so see my gitea instance or the github mirror for reference.

The Dockerfile I have settled on goes like this:

FROM alpine
RUN apk add hugo git
WORKDIR /hugo
RUN hugo new site /hugo
RUN git clone https://github.com/yihui/hugo-xmin.git themes/hugo-xmin
ADD hugo.toml /hugo/hugo.toml
ADD content /hugo/content
ADD static /hugo/static
ENV PORT=1313
EXPOSE $PORT
CMD hugo serve --bind 0.0.0.0 --port $PORT

For now, I am just using the built-in server in hugo, but it should be possible to serve using nginx.

I mentioned hugo before, but I was mostly mad that I had to add the autogenerated stuff in git - with this approach... I don't have to 🎊!

Images

Just put images in the static directory, and reference to them in your blogposts like you would normally in a hugo project:

![example](/example.png)

This is not centered, and there's no built-in shortcode for centering images (why not, hugo? You have a shortcode for figures, but no css class for centering - you cant even add a style tag? Such an oversight)... So we have to add one dirty thing to this setup. We have to add a shortcodes directory, that is then also added to the docker container in /hugo/layouts/shortcodes:

blog
├── Dockerfile
├── README.md
├── hugo.toml
├── content
│   ├── about.md
│   └── posts
│       ├── example.md
│       └── how-to-blog.md
├── shortcodes
│   └── centered.html        // <-- Added
└── static
    └── example.png

<!-- centered.html -->
<p align="center">
    <img alt="example" src="{{.Get `image`}}" style="max-width: 100%;">
</p>

Then we can use this new shortcode like so:

{{</* centered image="/example.png" */>}}

{{< centered image="/example.png" >}}

Yes! Now we're cooking with gas! ... or atleast cooking with something. Note that this image centering trick does not work in reader mode.

Conclusion

We have made a docker file for automatically downloading, generating and serving a simple hugo blog site. Personally, I would've liked the static and shortcodes directories to not exist, but blogposts need images and it needs to center them, so they are a necessary evil. Could we make the directory structure better and cleaner? Probably yes. Will I make it better for this blog in the future? Probably yes. Will I make another post when I do that? Probably yes!

If you want to just manually build and run docker image on your website server, feel free to stop reading here. The next section concerns about hosting, orchestrating and deploying the site automatically, but it's totally not required.

Deployment

Being able to build and launch the docker image is nice and can suffice for smaller projects. Yes, this blog is a small project and the manual method should be more than enough, but I also play factorio (highly recommend it!), so I hvae to automate everything that is tedious. I also have other projects that I host on my VPS (Virtual Private Server) such my portfolio site gtz.dk and a gitea instance amongst other things.

Continuous Integration

I am using my personal gitea instance to host the source code for this blog - which means that I will be using the integrated CI system there, but you can use whichever CI service you'd like. The general concepts of the workflow should be fairly easy to translate to any kind of CI, but this is how my setup looks like:

name: Release CI action
run-name: ${{ gitea.repository }} release
on:
  push:
    branches:
      - main

jobs:
  build-and-push-container:
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v4
      - name: build container
        run: docker build -t git.gtz.dk/${{ gitea.repository }}:latest .
      - name: login
        uses: docker/login-action@v3
        with:
          # NOTE: See https://gitea.com/gitea/docs/pulls/77/files
          registry: git.gtz.dk
          username: ${{ gitea.actor }}
          password: ${{ secrets.PACKAGE_TOKEN }}
      - name: push container
        run: docker push git.gtz.dk/${{ gitea.repository }}:latest

This may look a bit overwhelming if you don't know Github Actions, but it is really quite straight forward. Every time we push a commit to the main branch, we run the job named build-and-push-container. In the job, we first download our repository with the actions/checkout@v4 action, then we build the container using docker build (we make sure to accurately tag the image), then we log in to the container registry that we want to host the container at using the docker/login-action@v3 action, and the we simply docker push the container image.

Make sure to replace the git.gtz.dk website mentions with your own github hosting service (whether self-hosted, or github.com) and replace the gitea/GITEA mentions with github/GITHUB instead. Note that the syntax is extemely similar to GitHub Actions - in fact Gitea Actions are trying to be 1 to 1 compatible with GitHub Actions, so it should be relatively straight forward.

This setup also gives us the possibility of performing traditional code-review before releasing by using pull requests. This should empower us to identify and correct issues (e.g. spelling mistakes or whatever) before they are pushed to the official website.

I will probably make a post about how to host a private gitea instance with an actions runner and all that jazz. For now, I will consider that particular rabbit hole out-of-scope.

This was the most difficult thing to do. We are almost there.

Continuous Delivery

With a docker image readily available, we can automatically deploy the blog when we push it!

I personally am a big fan of the simplicity of portainer, as it scales really well when doing perosnal server stuff.