Homelab Knowledge Bundle
Bundle OKF 0.1 · 8 conceitos · adi-amatdev/homelab
Open source Repository Open in the app JSON README (API)
About
# Homelab Knowledge Bundle
Documentation for a single-node k3s homelab running ArgoCD, Traefik, and internal DNS over Tailscale.
## Concepts
- [Architecture Reference](/knowledge.md) — How the pieces fit together (k3s, ArgoCD, Kustomize, Traefik, DNS)
- [DNS & Traffic Flows](/dns.md) — How names resolve and traffic reaches each service (Tailscale + AdGuard + Traefik)
- [Exposure Strategy](/exposure.md) — What is public vs tailnet-only, entrypoints and routes
- [Adding a New Application](/add-app.md) — Playbook for deploying a new app via GitOps
- [kubectl Quick Reference](/kubectl.md) — Cheat sheet for common commands
- [Build History](/history.md) — Chronological record of the homelab build
- [Lessons Learned](/lessons.md) — Hard-earned operational lessons
- [Internal DNS with AdGuard Home](/solved/internal-dns-with-adguard.md) — Postmortem of the DNS solution
Details
- Kind
- OKF bundles
- Topic
- Cloud & DevOps
- Publisher
- adi-amatdev
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 1
- Last push
- 2026-08-12T07:27:18Z
- Repository state
- ativo
- Added
- 2026-09-08 16:04:09
- Updated
- 2026-09-08 16:04:09
- Origin id
adi-amatdev/homelab:docs/index.md
README
# homelab
Personal Kubernetes homelab on k3s. Fully GitOps — push to git, cluster self-updates via ArgoCD.
---
## Stack
| Layer | Tool |
|---|---|
| Cluster | k3s |
| GitOps | ArgoCD |
| Ingress | Traefik |
| DNS | AdGuard Home (Tailnet Split DNS) |
| Registry | GHCR |
---
## How it works
```
git push
└── ArgoCD detects change
└── applies manifests to cluster
└── cluster self-heals to match git
```
One rule: **git is the source of truth**. Never `kubectl apply` manually unless bootstrapping.
---
## Deployments
| Service | Namespace | Access |
|---|---|---|
| ArgoCD | `infra` | argocd.homelab |
| Traefik | `infra` | traefik.homelab (dashboard) |
| Blog | `apps` | **Public** (Funnel): dhridata.tail6a3e40.ts.net — blog `/`, admin `/admin`, images `/s3/*` |
| MinIO | `cloud` | minio.homelab, s3.homelab; public images via blog host `/s3/*` |
| PostgreSQL | `cloud` | postgres.cloud.svc.cluster.local:5432 (ClusterIP only, never public) |
| Redis | `cloud` | redis.cloud.svc.cluster.local:6379 (ClusterIP only, never public) |
| AdGuard Home | `cloud` | adguard.homelab (admin); tailnet-ip:53 (DNS) |
Full exposure map: see `docs/exposure.md`.
---
## Repo Structure
```
k8s/
platform/ — platform components (applied manually)
argocd/ — ArgoCD install (Helm via Kustomize)
traefik/ — ingress controller (Helm via Kustomize)
cloud/ — shared infra services
minio/
postgres/
redis/
adguard/
apps/ — personal projects
argocd-apps/ — app-of-apps registry (auto-synced by root)
root.yaml — the only manifest ever manually applied
cloud/ — ArgoCD Applications for cloud services
apps/ — ArgoCD Applications for app projects
docs/
knowledge.md — how everything works
kubectl.md — debug commands
add-app.md — adding a new app
lessons.md — mistakes documented
history.md — project history & challenges
templates/ — copy these to add new apps
```
---
## Bootstrap
ArgoCD and Traefik are deployed via Kustomize + Helm. Run these once:
```bash
kustomize build --enable-helm k8s/platform/traefik/ | kubectl apply -f -
kustomize build --enable-helm k8s/platform/argocd/ | kubectl apply -f -
kubectl apply -f argocd-apps/root.yaml
```
The last command is the **only** `kubectl apply` you'll ever need again.
---
## Adding a New App
```bash
cp templates/deployment.yaml k8s/apps/<your-app>/deployment.yaml
cp templates/service.yaml k8s/apps/<your-app>/service.yaml
cp templates/kustomization.yaml k8s/apps/<your-app>/kustomization.yaml
cp templates/argocd-app.yaml argocd-apps/apps/<your-app>.yaml
# edit files — set name, image, port, namespace
git add . && git commit -m "add <your-app>" && git push
```
ArgoCD picks it up automatically in ~3 minutes. See `docs/add-app.md` for details.
---
## Namespaces
| Namespace | Purpose |
|---|---|
| `infra` | ArgoCD, Traefik |
| `cloud` | MinIO, PostgreSQL, Redis, AdGuard Home |
| `apps` | Personal projects |