blog-ahmza-com/README.md

# Blog

## Overview
This repository contains the source code for my personal blog hosted at [blog.ahmza.com](https://blog.ahmza.com).

## Features
Using Gitea provides several advantages:
- **Highly Customizable CI/CD Pipelines**: Automated processes for building and deploying the blog via Gitea Actions.
- **Gitea Container Image Repository**: Efficient management and storage of container images.
- **Custom Gitea Runners**: Flexibility in managing the CI/CD environment.

The CI/CD pipeline is configured to build the blog for both amd64 and arm64
architectures, allowing me to host the site on my [Pi cluster](https://blog.ahmza.com/posts/pi-docker-swarm/)
as well as on other x86 platforms.

## Motivation
My previous homelab setup included rack-mounted, power-hungry servers, which
were expensive to run. By migrating to a Raspberry Pi cluster, I significantly
reduced costs and improved efficiency. You can read more about this migration on
my [site](https://blog.ahmza.com/posts/building-a-docker-swarm-with-pis/).

A static site generator was the best choice for my needs, as I don't require a
dynamically updating site. It provides simplicity and efficiency without
sacrificing performance.

## Benefits of Static Sites
- **Security**: Reduced attack surface due to the absence of a server-side backend.
- **Reliability**: Less prone to downtime and issues.
- **Speed**: Faster load times since content is pre-rendered.
- **Scalability**: Easily handle large amounts of traffic.
- **Flexibility**: Greater control over content and design.
- **Low Resource Overhead**: Minimal resource consumption compared to dynamic sites.

## Implementation
- **Hugo**: Converts Markdown files into static HTML/CSS/JS files.
- **Gitea Actions**: Builds amd64/arm64 images and records the exact image digest
  in the separate GitOps repository.
- **Argo CD**: Watches that Git commit and reconciles the Kubernetes deployment.
- **Kubernetes Cluster**: Serves the static files to users.

## GitOps deployment

The workflow in [`.gitea/workflows/build-docker-images.yml`](.gitea/workflows/build-docker-images.yml)
keeps building and publishing `tea.ahmza.com/ahmza/blog-ahmza-com`. Instead of
connecting to NetBird and invoking `kubectl`, it commits the published image's
immutable digest to `apps/blog-ahmza-com/deployment.yaml` in
[`ahmza.com/k8s-starter-pack`](https://tea.ahmza.com/ahmza.com/k8s-starter-pack).
Argo CD then performs the rollout; CI success alone is not confirmation that the
cluster has finished deploying.

Configure these Gitea Actions secrets in this source repository:

- `GITEATOKEN`: the existing registry-push credential.
- `GITOPS_TOKEN`: a separate least-privilege bot PAT with read/write access to
  `ahmza.com/k8s-starter-pack`, including permission to push to `main`.

Commit/push the GitOps app manifests **before** enabling this workflow: the
Deployment file must already exist remotely. Once the migration is verified,
remove the old `KUBE_CONFIG`, `NETBIRD_SETUP_KEY`, and `NETBIRD_URL` secrets only
if no other workflows use them. No Kubernetes credentials are needed by this
workflow. The runner still needs HTTPS access to Gitea and the registry.

The full first-sync, routing, certificate, and rollback checklist is in
[`docs/13-blog-gitops.md`](https://tea.ahmza.com/ahmza.com/k8s-starter-pack/src/branch/main/docs/13-blog-gitops.md)
in the GitOps repository. The older [Caddy examples](docs/caddy-reverse-proxy.md)
are standalone deployment references, not extra components to deploy alongside
the new ingress-nginx manifests.

Test the standard-library-only image updater locally with:

```sh
python3 -m unittest discover -s .gitea/tests -v
```

## To-Do List
- [x] Migrate to Kubernetes
- [x] Migrate to Blowfish theme
- [x] Make repo private to ensure all keys etc are hidden
- [x] Update docker file
- [x] Migrate to hugo modules for the theme
- [ ] Continue to write awesome posts

## Notes

### Cloning the Repository
The Blowfish theme is managed as a Hugo module, so no submodules are required.
Clone the repository with:
```bash
git clone ssh://git@tea.ahmza.com/ahmza/blog-ahmza-com.git
```