Main page¶

Welcome to the rpi-homelab documentation.

rpi-homelab is focused on running opensource apps on single node k8s cluster, infra provisioned by opentofu, hosts are managed by ansible, docs created with Material for mkdocs

Software stack¶

Kubernetes (K3S)¶

Single-node Kubernetes cluster running on Raspberry Pi 5. K3s is used instead of installing full Kubernetes from scratch, providing a lightweight but fully featured control plane for homelab services like Home Assistant, Opencloud, Jellyfin, Joplin, and more.

OpenTofu¶

OpenTofu (Terraform fork) manages external cloud resources and Kubernetes resources. It encodes cluster and infrastruction as code, so changes are applied reproducibly via tofu plan / tofu apply.

Ansible¶

Ansible roles and playbooks automate OS and service configuration on hosts. It handles package installation, system settings, and application setup to keep machines consistent.

Project repositories¶

`rpi-homelab/infra`¶

Infrastructure as Code.

`rpi-homelab/kubernetes-manifests`¶

Kubernetes apps YAML manifests (Deployments, Services, HTTPRoutes, etc.) per app directory.

Usage: Primary Argo CD source for manifest-based apps; each app directory is wired via locals.argocd_apps into an argocd_application resource. Changes merged to main are automatically picked up by Argo CD and applied to the K3s cluster.

`rpi-homelab/ansible`¶

Host automation. Playbooks, roles, and inventory.

Usage: Run manually or via Forgejo Actions to apply OS and service configuration consistently across all hosts. Used for updating packages and maintaining a reproducible environment.

`rpi-homelab/configs` (private repo)¶

Application configuration: ConfigMaps, kustomize configMapGenerator definitions, BitwardenSecret manifests, and Helm values files.

Usage: Attached to Argo CD apps with configs_access = true, providing additional manifests (ConfigMaps, Secrets) or Helm values ($values/<app>/values.yml). Secrets are exposed via sm-operator; Terraform creates bw-auth-token for apps with bw_secrets_access = true.

`rpi-homelab/docs` (private repo)¶

Project documentation. MkDocs site (Markdown, images, config) describing the software stack, hosts, and repositories.

Usage: Built and served as the main homelab documentation site; updated alongside infra and application changes to keep docs in sync with the actual state.

Hosts inventory¶

RPI5¶

Main homelab server rpi5

Raspberry Pi 5 (8 GB RAM) + SSD HAT + Sonoff Zigbee USB3.0 dongle

Workloads: - K3s single-node cluster - Ansible control node for automating other hosts.

RPI02W¶

3D printer management node

RPI02W

Hardware: Raspberry Pi Zero 2W (512 MB RAM) + RaspberryPI Camera 3

Workloads: - OctoPrint for controlling the 3D printer. - Camera for monitoring prints.

PC¶

Admin and automation workstation.

Usage: - Manages repositories and OpenTofu (Terraform) operations. - Used for troubleshooting RPI5 via SSH and general development tasks.