Skip to content
@syahshiimi Homelab Docs

README

An Introduction To The Homelab

This is my homelab repository, designed to encapsulate and share my interest in DevOps, GitOps and Software Engineering practice.

This repository was initially spawned from notes, stored within a larger second-brain directory for my Obsidian Notes. It was designed this way as a consequence of using Obsidian as my personal notes editor and also to write documentation for the homelab.

I realised, later on, adopting a monorepo approach might work well for a multiple intended use case. For instance, if I were to ever wish to showcase an application/plugin I’ve built – folks can easily see how the application could be deployed in the homelab. I’d like to show the different types of work I can do 😏

Nonetheless, this homelab monorepo was designed with a few initial goals that later expanded:

  1. Homelab documentation notes as md files,
  2. The documentation site (Starlight) as a deployable Static Site application
  3. The codebase for my homelab.
  4. Other homelab-related/self-learning application development

This is the current structure.

README.md
- docs
  - excalidraw
  - images
  - resources
  - *.md notes
- forge

Building With A Note-taking Philosophy

Intentions

The docs and Obsidian repository-level plugins are synced with my paid Obsidian Sync subscription. In instances where I do want to capture notes – I am free to do from any devices to which Obsidian had been installed.

At the same time, the markdown notes written should live and breathe as the source of truth for me to share and write documentation for the homelab.

Doing it this way provides me with the benefits of using Obsidian Sync and having it loosely coupled to the process of sharing, documenting and writing code for my homelab. I am free to add in notes whenever I want to but with git, I can version control when these notes are deployed and shared.

Zettelkasten Philosophy

Building my note-taking process to be co-located with my code creates a close but loosely coupled relation between what goes through my head and the outcomes from it.

If you have noticed, the MD files are timestamped. I’ve taken this approach from a system of note-taking called zettelkasten (if you’ve figured from the way these notes have a timestamp, good for you!). Fundamentally, it is a way for me to weave in notes from other parts of my second-brain vault with documentation found here.

This need to interweave is just a way I’d like to take notes. My day-to-day experience can be recorded and later an idea can be sprung from it. I don’t see any differences between writing notes for my art practice, my daytime job as a software engineer and my constant state of always thinking.

Homelab IaC

forge is the monorepo root where we orchestrate app creation, docker builds, kubernetes deploys etc. It is built with a philosophy of simple abstractions on top of Turborepo which by itself is built on top of pnpm workspaces as a light abstraction above it.

Prior to using turborepo, I was using nx and I found it very unwiedly with its concepts of plugins, generators and DSL over configuring package.json. Turborepo will be the de-facto tooling used for TS/JS applications and as a wrapper over any non-TS/JS apps and builds.

The homelab consists of a mixed-bag between bare-metal and virtual machined deployments.

Tooling

This repository stores the various automation and IaC tooling to support idempotent, reproducible and portable deployments.

forge/ansible

The automated provisioning of these machines (either bare-metal or VMs) is done through the use of Ansible.

Currently, we can automate the bootstraps of new linux VM’s into K3S clsuters easily via k3s-ansible collection. Otherwise, we also use it for managing OS-level configuration of Linux VM’s.

forge/terraform

Terraform is used to manage

  1. The provisioning of virtual machines/and or our containers to the Proxmox Hypervisor.
  2. The management of the Backblaze B2 Buckets (S3-compatible)
  3. Creation of Infisical Projects for cluster secrets
  4. Our CloudFlare DNS and account
  5. And last but not least, the Tailscale Client for our homelab.

forge/kubernetes

FluxCD in forge/kuberentes manages the cluster ina GitOps fashion. It currently uses a mix of

  1. Raw Kubernetes manifests
  2. Helm Charts

Raw Kubernetes manifests are built using the kustomize.config.k8s.io/v1beta1 overlay abstraction and a combination of FluxCD kustomize.toolkit.fluxcd.io/v1 API. These manifests are then managed through the Kustomize Controller

For Helm Charts, they are managed through the Helm Controller, more specifically by implementing the Helm Release API helm.toolkit.fluxcd.io/v2 and the Helm Repository API source.toolkit.fluxcd.io/v1

Some resources

  1. Helm Release