Welcome to the rpi-homelab documentation.¶
Software stack¶
Kubernetes (K3S)¶
Use in project: Cluster orchestration.
Documentation: docs.k3s.io
Description: 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.
Terraform (OpenTofu)¶
Use in project: Infrastructure as Code (IaC).
Documentation: opentofu.org
Description: OpenTofu manages external cloud resources and Kubernetes resources (Helm releases, Secrets, Argo CD Applications). It encodes cluster and infra configuration in code, so changes are applied reproducibly via tofu plan / tofu apply.
Ansible¶
Use in project: Host automation.
Documentation: docs.ansible.com
Description: Ansible roles and playbooks automate OS and service configuration on hosts (PC, Raspberry Pis). It handles package installation, system settings, and application setup to keep machines consistent.
Forgejo Actions¶
Use in project: CI/CD.
Documentation: forgejo.org/docs/latest/user/actions/
Description: Forgejo Actions (Codeberg Actions) run workflows for this project: linting, Terraform plans, Kubernetes manifest validation, and other checks on commits and pull requests, similar to GitHub Actions but hosted on Codeberg.
Hosts inventory¶
RPI5¶
Role: Main homelab server.
Hardware: 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¶
Role: 3D printer management node.
Hardware: Raspberry Pi Zero 2W (512 MB RAM) + RaspberryPI Camera 3
Workloads: - OctoPrint for controlling the 3D printer. - Camera for monitoring prints.
PC¶
Role: Admin and automation workstation. Usage: - Manages repositories and OpenTofu (Terraform) operations. - Used for troubleshooting RPI5 via SSH and general development tasks.
Project repositories¶
rpi-homelab/infra¶
Purpose: Infrastructure as Code.
Contents: OpenTofu stacks for Argo CD, cluster components (for example Tailscale, cert-manager), and external cloud resources.
Usage: The argocd stack defines locals.argocd_apps and creates argocd_application resources for both manifest and Helm apps. Infra changes are applied reproducibly with tofu plan / tofu apply from the admin workstation or CI.
rpi-homelab/kubernetes-manifests¶
Purpose: Application manifests.
Contents: Kubernetes YAML (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/configs (private)¶
Purpose: Application configuration.
Contents: 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)¶
Purpose: Project documentation.
Contents: 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.
rpi-homelab/ansible¶
Purpose: Host automation.
Contents: Playbooks, roles, and inventory for RPI5, RPI02W, and PC.
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.