Homelab

Monorepo for self-hosted applications running on a k3s cluster across Intel NUC machines.

What's Inside

• Apps: Next.js frontend, Express API (TypeScript)
• Infrastructure: Ansible provisioning, ArgoCD GitOps, full Kubernetes platform
• Observability: Prometheus, Grafana, Loki

Prerequisites

• Node.js >= 20
• pnpm >= 9
• go-task >= 3
• kubectl >= 1.31
• Helm >= 3.16
• Ansible >= 2.16
• kubeseal >= 0.27

Quick Start

# Install dependencies
pnpm install

# Start development
task dev

# Build all apps
task build

Bootstrap Cluster (Day 1)

1. Flash Ubuntu Server 24.04 on NUCs, configure SSH access
2. Configure Ubiquiti Cloud Gateway (see infra/ubiquiti/)
3. Provision nodes and install k3s:

   task cluster:bootstrap
   task cluster:kubeconfig
   

4. Install platform components:

   task platform:install
   

5. Seal initial secrets:

   task secrets:seal
   

6. Push an app — ArgoCD handles the rest

Branch Deploys

Push a branch or open a PR → GitHub Actions builds changed apps → ArgoCD creates a preview namespace → merge to main deploys to production.

Project Structure

homelab/
├── apps/           # Deployable applications
├── packages/       # Shared libraries
├── infra/
│   ├── ansible/    # Bare-metal provisioning
│   ├── kubernetes/ # K8s manifests (ArgoCD, platform, observability)
│   └── ubiquiti/   # Network documentation
├── scripts/        # Utility scripts
├── templates/      # App scaffolding templates
└── Taskfile.yaml   # Task runner

License

Private — All rights reserved.