Files

Julia McGhee 96e3f32f28 Initial monorepo scaffold

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

2026-03-19 22:24:56 +00:00

2.1 KiB

Raw Blame History

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

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

2.1 KiB Raw Blame History