feat: example post

.gitea/workflows/build.yml

@@ -0,0 +1,26 @@
+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: qemu setup
+        uses: docker/setup-qemu-action@v3
+      - name: dockerx setup
+        uses: docker/setup-buildx-action@v1
+      - 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: build and push container
+        run: docker buildx build --push --platform linux/amd64,linux/arm64 -t git.gtz.dk/${{ gitea.repository }}:latest .

Dockerfile

@@ -5,4 +5,8 @@ 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
-CMD ["hugo", "serve", "--bind", "0.0.0.0"]
+ADD static /hugo/static
+ADD shortcodes /hugo/layouts/shortcodes
+ENV PORT=1313
+EXPOSE $PORT
+CMD ["hugo", "serve", "--bind", "0.0.0.0", "--port", "$PORT"]

content/posts/example.md

@@ -0,0 +1,8 @@
++++
+date = '2024-11-27'
+draft = true
+title = 'Example'
+tags = ['tutorial']
+categories = ['technical']
++++
+content goes here.

content/posts/how-to-blog.md

@@ -1,6 +1,5 @@
 +++
 date = '2024-11-27'
-draft = false
 title = 'How to Host a Simple Blog'
 tags = ['howto', 'tutorial', 'web']
 categories = ['technical']
@@ -24,11 +23,13 @@ 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
-├── config.toml     // blog-framework configuration file
+├── hugo.toml       // blog-framework configuration file
-└── content
+├── content
-    ├── about.md    // the "about" page
+│   ├── about.md    // the "about" page
-    └── posts       // actual blog posts go here
+│   └── posts       // actual blog posts go here
-        └── example.md
+│       └── example.md
+└── static          // non-markdown files
+    └── example.png
 ```
 
 And then to build the site, simply build the container:
@@ -52,9 +53,159 @@ 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
-CMD ["hugo", "serve", "--bind", "0.0.0.0"]
+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:
+
+```markdown
+![example](/example.png)
+```
+
+![example](/example.png#center)
+
+This is not centered, and there's no built-in [shortcode](https://gohugo.io/content-management/shortcodes/) 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
+```
+
+```html
+<!-- 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:
+
+```markdown
+{{</* 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](https://support.mozilla.org/en-US/kb/firefox-reader-view-clutter-free-web-pages).
+
+## 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](https://store.steampowered.com/app/427520/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](https://gtz.dk) and a [gitea instance](https://git.gtz.dk/) amongst other things.
+
+## Continuous Integration
+I am using my personal [gitea instance](https://git.gtz.dk/agj/blog) 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:
+
+```yaml
+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](https://docs.github.com/en/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](https://docs.gitea.com/next/usage/pull-request?_highlight).
+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](https://www.portainer.io/), as it scales really well when doing perosnal server stuff.
+
+What we really just need is a simple webhook... Fuck...
+
+{{< centered image="/screenshot-2024-11-27.png" >}}
+
+Now, don't get me wrong - portainer is a good piece of software - their business tier is even worth the money.
+But I am not running a business here. I just want a personal blog. There has to be another way of automatically pulling and redeploying a container based on a new release event.
+
+IN STEPS [WATCHTOWER](https://containrrr.dev/watchtower/)!
+This amazing piece of software will monitor and automatically update all containers on a system and update them!
+Now, this only updates once per 24 hours (by default), but that should be plenty fine.
+
+```yaml
+services:
+  watchtower:
+    image: containrrr/watchtower
+    container_name: watchtower
+    environment:
+      - DOCKER_CONFIG=/config
+    volumes:
+      - watchtower-config:/config/
+      - /var/run/docker.sock:/var/run/docker.sock
+
+volumes:
+  watchtower-config:
+```
+
+Only one small thing - if you are hosting the container on a private registry (like I am), you have to do some slight configuration regarding credentials - for this, I will simply refer to the [watchtower documentation](https://containrrr.dev/watchtower/private-registries/).
+
+# Conclusion
+PHEW! I started this blog post using words like "simple" and "easy" - but it got a bit out of hand I must admit.
+The workflow is very simple now though. You don't have to contiously deal with the mess of deploying your stuff, and you dont have to commit unneccesary autogenerated stuff to git.
+Just focus on writing posts and publish them by merging to `main`. Nice and automated 😁.
+
+## P.S.
+You may notice that the CI script on the real blog repository is a bit more complicated than what we've went through in this post, but the extra complexity only comes from some stupid technicalities regarding my build server being based on ARM rather than x86 (raspberry pi).
+The script we made here is plenty good to get you started.

shortcodes/centered.html

@@ -0,0 +1,3 @@
+<p align="center">
+    <img alt="example" src="{{.Get `image`}}" style="max-width: 100%;">
+</p>