# 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](https://nodejs.org/) >= 20
- [pnpm](https://pnpm.io/) >= 9
- [go-task](https://taskfile.dev/) >= 3
- [kubectl](https://kubernetes.io/docs/tasks/tools/) >= 1.31
- [Helm](https://helm.sh/) >= 3.16
- [Ansible](https://docs.ansible.com/) >= 2.16
- [kubeseal](https://github.com/bitnami-labs/sealed-secrets) >= 0.27

## Quick Start

```bash
# 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:
   ```bash
   task cluster:bootstrap
   task cluster:kubeconfig
   ```
4. Install platform components:
   ```bash
   task platform:install
   ```
5. Seal initial secrets:
   ```bash
   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.