96e3f32f28
Turborepo + pnpm monorepo for k3s homelab cluster on Intel NUCs. - Apps: Next.js web frontend, Express API (TypeScript, Dockerfiles, k8s manifests) - Packages: shared UI, ESLint config, TypeScript config, Drizzle DB schemas - Infra/Ansible: bare-metal provisioning with roles for common, k3s-server, k3s-agent, hardening - Infra/Kubernetes: ArgoCD GitOps (app-of-apps + ApplicationSets), platform components (cert-manager, Traefik, CloudNativePG, Valkey, Longhorn, Sealed Secrets), namespaces - Observability: kube-prometheus-stack, Loki, Promtail as ArgoCD Applications - CI/CD: GitHub Actions for PR builds, preview deploys, production deploys - DX: Taskfile, utility scripts, copier templates, Ubiquiti network docs
49 lines
2.1 KiB
Markdown
49 lines
2.1 KiB
Markdown
# Homelab Monorepo
|
|
|
|
## Overview
|
|
Monorepo for frontend/backend apps deployed to a k3s cluster on Intel NUC machines.
|
|
GitOps via ArgoCD, bare-metal provisioning via Ansible, Turborepo for app builds.
|
|
|
|
## Tech Stack
|
|
- **Monorepo**: Turborepo + pnpm workspaces
|
|
- **Apps**: Next.js (frontend), Express (API), TypeScript
|
|
- **Infrastructure**: k3s, ArgoCD, Ansible
|
|
- **Platform**: Traefik, cert-manager, CloudNativePG, Valkey, Longhorn, Sealed Secrets
|
|
- **Observability**: kube-prometheus-stack, Loki, Promtail, Grafana
|
|
- **CI/CD**: GitHub Actions → ghcr.io → ArgoCD
|
|
- **Task Runner**: Taskfile (go-task)
|
|
|
|
## Directory Structure
|
|
- `apps/` — Deployable applications (each has src/, Dockerfile, k8s/ manifests)
|
|
- `packages/` — Shared libraries (ui, config-eslint, config-typescript, db)
|
|
- `infra/ansible/` — Bare-metal provisioning playbooks and roles
|
|
- `infra/kubernetes/` — K8s manifests (argocd, platform, observability, namespaces)
|
|
- `infra/ubiquiti/` — Network documentation for Ubiquiti Cloud Gateway
|
|
- `scripts/` — Utility scripts (new-app, seal-secret, kubeconfig-fetch)
|
|
- `templates/` — Copier templates for scaffolding new apps
|
|
|
|
## Conventions
|
|
- All apps use Kustomize with base + overlays (preview, production)
|
|
- K8s manifests live inside each app at `k8s/`
|
|
- Secrets are sealed with kubeseal before committing
|
|
- Branch deploys create `preview-<PR#>` namespaces automatically
|
|
- Use `task <command>` for all operations (see Taskfile.yaml)
|
|
- Docker images tagged with git SHA, pushed to ghcr.io
|
|
|
|
## Common Commands
|
|
```bash
|
|
task dev # Start all apps in dev mode
|
|
task build # Build all apps
|
|
task lint # Lint everything
|
|
task cluster:bootstrap # Provision NUCs with Ansible
|
|
task cluster:kubeconfig # Fetch kubeconfig from server node
|
|
task platform:install # Bootstrap ArgoCD + platform
|
|
task secrets:seal # Seal a secret for git
|
|
```
|
|
|
|
## Testing
|
|
- Run `task test` for all tests
|
|
- Run `task lint` for linting (includes ansible-lint)
|
|
- K8s manifests: `kubectl apply --dry-run=client -f <file>`
|
|
- Kustomize: `kustomize build <dir>` to verify rendering
|