This repository hosts all the playbooks required to deploy and run my homelab. You have to bring your own hardware, Linux operating system, configuration secrets and data though.
My homelab is a single-node x64 (previously ARM) machine, and applications are deployed containerized via K3s (lightweight Kubernetes). Tailscale takes care of all the networking required for administration and deployments. Traefik handles ingress with automatic TLS certificates from Let's Encrypt.
| App | Purpose | Project homepage |
|---|---|---|
| MySQL | Database (common dependency for multiple apps) | https://dev.mysql.com/downloads/mysql/ |
| PostgreSQL | Database (for apps that prefer Postgres) | https://www.postgresql.org/ |
| Redis | In-memory cache (sessions, queues) | https://redis.io/ |
| Firefly-III | Personal finance | https://www.firefly-iii.org/ |
| Bookstack | Documentation & Diary | https://www.bookstackapp.com/ |
| Vikunja | Todo list | https://vikunja.io/ |
| Nextcloud | Google Drive alternative | https://nextcloud.com/ |
| Webtrees | Family tree (genealogy) | https://www.webtrees.net/index.php/en/ |
| Audiobookshelf | Audiobook server (Audible alternative) | https://www.audiobookshelf.org/ |
| Snibox | Snippets organizer | https://github.com/MohamedElashri/Snibox |
| Memoet | Spaced-repetition system | https://github.com/memoetapp/memoet |
| ntfy | Push notifications | https://ntfy.sh/ |
| Frigate | NVR with realtime object detection for IP cameras | https://frigate.video/ |
| Synt | LLM chat archiving | https://github.com/rounakdatta/synt |
| texas-fold-em | fold.money refresh-token broker (in-cluster API) | https://github.com/rounakdatta/texas-fold-em |
| Hugo sites | Personal static sites (rounak2018 / rounak2020 / rounak2025) | https://gohugo.io/ |
| itineris | Travel journal: map, timeline, photo wall, stories (public); tinyauth-gated /admin for uploads | https://github.com/rounakdatta/itineris |
| auth2api | Local AI gateway | https://github.com/AmazingAng/auth2api |
| Component | Purpose | Project homepage |
|---|---|---|
| Tinyauth | Forward-auth SSO via Google OAuth (replaces Authelia) | https://tinyauth.app/ |
| cert-manager | Automatic TLS certificates from Let's Encrypt | https://cert-manager.io/ |
| Velero + Velero-UI | Cluster backups (Kopia-backed, S3-compatible storage) | https://velero.io/ |
| Keel | Image update polling + manual approval gate | https://keel.sh/ |
K3s is a lightweight Kubernetes distribution that's perfect for single-node homelabs. Traefik (bundled with K3s) handles all ingress routing with automatic TLS via cert-manager and Let's Encrypt. Tinyauth sits in front of apps as a forward-auth middleware backed by Google OAuth, so any subset of apps can be put behind a single sign-on with one annotation.
Most third-party apps are inflated from upstream Helm charts via Kustomize's helmCharts block (with values overridden in-tree), so version bumps stay a one-line change. Apps with no chart of their own use bjw-s app-template, a generic chart that takes any image — auth2api is the first. Manifests are organized using Kustomize and secrets are managed through Bitwarden — synced into Kubernetes Secrets by an Ansible play. The setup is fully declarative — adding a new application is just about creating a few YAML files and adding secrets to Bitwarden.
Those charts are vendored: kustomize build --enable-helm writes each one into kubernetes/<group>/<app>/charts/<name>-<version>/ and it is committed, so a deploy reads the tree instead of 13 third-party hosts. That is not tidiness — when the bjw-s chart repo started 404ing, one unfetchable chart broke every deploy. kubernetes/charts.lock records where each chart came from and pins its contents, and .github/scripts/charts-lock.py --check verifies the tree against it offline (run on every PR). A vendored chart is an upstream artifact and is never edited in place; to move one, bump version: in its kustomization.yaml, re-render, drop the old directory, and refresh the lock with --write.
The project was born as a hobby idea to organize knowledge. The core idea is to own the data and build amazing integrations that make everyday easy. As already mentioned, the homelab today hosts financial data lake, documentation & notetaking software, powerful to-do-listing tools, eBook and audiobook readers, file cloud, photo gallery, smart reminder & notification systems and so on!
Deployments happen whenever a PR gets merged to the main branch. GitHub Actions is used for all deployments and secrets are kept in Bitwarden. Whenever there's code merged, the CI runner:
- Joins my Tailscale network
- SSHs into the homelab via Tailscale SSH (no keys needed!)
- Fetches the kubeconfig
- Syncs secrets from Bitwarden to Kubernetes
- Applies all manifests via
kubectl apply -k
The whole setup requires just 5 GitHub secrets: TAILSCALE_AUTHKEY, MACHINE_NAME, and Bitwarden credentials. Idempotence is a strict requirement - running the same deployment twice should have no effect.
Application data lives on local-path PVCs backed by the mounted HDD. Velero (with the Kopia file-system backup plugin) snapshots all PVCs every night and ships the encrypted, deduplicated, incremental chunks to Cloudflare R2 (S3-compatible). Velero-UI gives a web view of backup/restore state.
Yeah I'm a one-machine fan.
- 1GB DigitalOcean droplet
- The now-archived repository used to deploy applications natively (non-containerized) and given memory was limited, very few applications were deployed.
- Since DO droplets have dedicated IPv4, exposing services publicly was not at all a concern.
- Raspberry Pi 4
- The Raspberry Pi performed really well in the initial 3 months of setting up, until summer heat waves spoiled the party.
- Pis being single-board computers tend to get very hot when overworking.
- The Pi (ARM) setup was very efficient on power and had an external USB-connected HDD for storage.
- The Pi ran DietPi - a stripped down Debian-based operating system. With 8GB of memory, it ran a large number of applications really well, although response times were quite high on average.
- Dell Latitude E6400
- Migrating to a x64 (AMD64) old laptop was mostly trivial. The Dell machine runs Ubuntu server.
- CPU, in comparison to the Pi is way more faster and resulted to slightly better response times.
- Being a laptop, the machine provides battery backup to some extent and also a screen for urgent debugging.
- However the laptop being decade-old, it tends to heat up a lot and needs active environmental cooling.
- ASUS Desktop (gaming PC)
- The second-hand-purchased gaming desktop sports i5 7th generation and 16GB RAM (early 2018 model).
- Has powerful motherboard with efficient cooling and power unit.
- Nextcloud, Photoprism, Duplicati performance has clear visible improvements upon migration to this desktop homelab.
- VM (current)
- Migrated from Nomad to K3s (lightweight Kubernetes) for better ecosystem support.
- Tailscale SSH eliminates the need for managing SSH keys.
- All secrets managed in Bitwarden, synced automatically during deployments.
- Traefik + cert-manager handles ingress and TLS certificates.
- Photos: Immich (replacing the old PhotoPrism setup)
- RSS reader: Miniflux
- Metric collection and monitoring (Prometheus + Grafana)
- Multi-node K3s — currently single control-plane; worker-node bootstrap is wired up but not yet in active use
- Distributed storage (Longhorn, SeaweedFS) so RWX mounts and PVC migrations stop being a one-machine constraint