cloud-host/README.md

# ☁️ CloudHost — Self-Service PaaS Platform

A self-service Platform-as-a-Service (PaaS) that lets developers deploy **Node.js** and **Laravel** applications onto Kubernetes with zero DevOps overhead. Super admins manage clusters, quotas, and users; developers simply push code and deploy.

---

## Architecture Overview

```
┌─────────────┐          ┌─────────────────┐        ┌──────────────┐
│  Next.js 14  │  REST   │   NestJS API     │  K8s   │  Kubernetes  │
│  Frontend    │◄───────►│   Backend        │◄──────►│  Cluster(s)  │
└─────────────┘          └────────┬────────┘        └──────────────┘
                                  │
                       ┌──────────┼──────────┐
                       ▼          ▼          ▼
                  PostgreSQL    Redis     Container
                                (Bull)    Registry
```

| Layer        | Technology                                              |
| ------------ | ------------------------------------------------------- |
| Frontend     | Next.js 14, Tailwind CSS, React Query, Zustand          |
| Backend API  | NestJS 10, TypeORM, Passport JWT, Bull (Redis)          |
| Build Engine | Kaniko (in-cluster, daemon-less Docker builds)          |
| Orchestrator | @kubernetes/client-node, Handlebars YAML templates      |
| Database     | PostgreSQL 16                                           |
| Queue        | Redis 7 + BullMQ                                        |

---

## Features

### For Developers
- 🚀 **One-click deploys** from a Git URL or uploaded code archive
- 🟢 **Node.js** (with `npm run build` & `npm start`) support
- 🟣 **Laravel** (PHP 8.3 + Nginx + Supervisor) support
- 🗄️ **Managed databases** — PostgreSQL or MySQL provisioned automatically
- 📊 **Live logs** & deployment history
- 🔒 **Environment variables** managed as Kubernetes Secrets
- ⚙️ **Resource controls** — CPU, memory, replica count

### For Super Admins
- 🖥️ **Multi-cluster management** — register/remove Kubernetes clusters
- 👥 **User management** — activate, deactivate, change roles
- 📈 **Quotas** — per-cluster limits (CPU, memory, max apps)
- 🔐 **RBAC** — role-based guards on every endpoint

---

## Project Structure

```
host/
├── ARCHITECTURE.md          # Detailed architecture document
├── docker-compose.yml       # Local dev / production compose
│
├── backend/                 # NestJS API
│   ├── Dockerfile
│   ├── package.json
│   ├── src/
│   │   ├── main.ts
│   │   ├── app.module.ts
│   │   ├── auth/            # JWT auth (register, login, refresh)
│   │   ├── users/           # User CRUD + admin ops
│   │   ├── applications/    # Application CRUD
│   │   ├── deployments/     # Deployment pipeline orchestration
│   │   ├── clusters/        # Cluster management (admin)
│   │   ├── kubernetes/      # K8s client & manifest generator
│   │   ├── build/           # Kaniko build jobs (Bull queue)
│   │   ├── common/          # Enums, decorators, guards
│   │   └── config/          # Env configuration loader
│   └── templates/           # Handlebars K8s YAML templates
│
└── frontend/                # Next.js 14 App Router
    ├── Dockerfile
    ├── package.json
    └── src/
        ├── app/
        │   ├── login/       # Auth pages
        │   ├── register/
        │   └── dashboard/   # Protected dashboard
        │       ├── apps/    # App list & detail
        │       ├── deploy/  # 4-step deploy wizard
        │       └── admin/   # Admin: users & clusters
        ├── components/
        ├── lib/             # API client, auth store
        └── types/           # TypeScript interfaces
```

---

## Quick Start

### Prerequisites

| Tool            | Version |
| --------------- | ------- |
| Node.js         | ≥ 20    |
| Docker & Compose| ≥ 24    |
| PostgreSQL      | 16 (or use Docker) |
| Redis           | 7 (or use Docker)  |

### 1. Clone & Install

```bash
git clone <repo-url> host && cd host

# Backend
cd backend && npm install && cd ..

# Frontend
cd frontend && npm install && cd ..
```

### 2. Environment Variables

```bash
# Backend
cp backend/.env.example backend/.env
# Edit backend/.env with your DB, JWT, Redis, and registry settings

# Frontend
cp frontend/.env.local.example frontend/.env.local
```

### 3. Run with Docker Compose (recommended)

```bash
docker compose up --build
```

This spins up **PostgreSQL**, **Redis**, **Backend** (port 4000), and **Frontend** (port 3000).

Open [http://localhost:3000](http://localhost:3000) in your browser.

### 4. Run Locally (development)

```bash
# Terminal 1 — Backend
cd backend
npm run start:dev

# Terminal 2 — Frontend
cd frontend
npm run dev
```

---

## API Endpoints

All endpoints are prefixed with `/api/v1`.

### Auth
| Method | Path              | Description         |
| ------ | ----------------- | ------------------- |
| POST   | /auth/register    | Create account      |
| POST   | /auth/login       | Get JWT tokens      |
| POST   | /auth/refresh     | Refresh access token|

### Applications
| Method | Path               | Description         |
| ------ | ------------------ | ------------------- |
| POST   | /applications      | Create app          |
| GET    | /applications      | List user's apps    |
| GET    | /applications/:id  | Get app details     |
| PATCH  | /applications/:id  | Update app          |
| DELETE | /applications/:id  | Delete app          |

### Deployments
| Method | Path                                 | Description          |
| ------ | ------------------------------------ | -------------------- |
| POST   | /applications/:appId/deployments     | Trigger deploy       |
| GET    | /applications/:appId/deployments     | List deployments     |
| GET    | /deployments/:id                     | Deployment detail    |
| GET    | /deployments/:id/logs                | Get pod logs         |
| POST   | /deployments/:id/stop                | Stop deployment      |
| POST   | /deployments/:id/restart             | Restart deployment   |

### Users (authenticated)
| Method | Path       | Description      |
| ------ | ---------- | ---------------- |
| GET    | /users/me  | Current user     |
| PATCH  | /users/me  | Update profile   |

### Admin — Users
| Method | Path                           | Description        |
| ------ | ------------------------------ | ------------------ |
| GET    | /users                         | List all users     |
| PATCH  | /users/:id/activate            | Activate user      |
| PATCH  | /users/:id/deactivate          | Deactivate user    |
| PATCH  | /users/:id/role                | Change role        |

### Admin — Clusters
| Method | Path            | Description       |
| ------ | --------------- | ----------------- |
| POST   | /clusters       | Add cluster       |
| GET    | /clusters       | List clusters     |
| GET    | /clusters/:id   | Cluster details   |
| PATCH  | /clusters/:id   | Update cluster    |
| DELETE | /clusters/:id   | Remove cluster    |

> 📖 Full Swagger docs available at `http://localhost:4000/docs` when the backend is running.

---

## Deployment Flow

```
Developer creates app  →  Uploads code / provides Git URL
         │
         ▼
    Build Service creates Kaniko Job in K8s
         │
         ▼
    Kaniko builds Docker image  →  Pushes to Container Registry
         │
         ▼
    Kubernetes Service generates manifests from Handlebars templates:
      • Namespace  • Deployment  • Service  • Ingress
      • Database (optional)  • PVC  • Secret
         │
         ▼
    Applies manifests to target cluster via @kubernetes/client-node
         │
         ▼
    App is live at  https://<subdomain>.apps.yourdomain.com
```

---

## Kubernetes Templates

The platform dynamically generates K8s manifests using **Handlebars** templates located in `backend/templates/`:

| Template          | Purpose                                       |
| ----------------- | --------------------------------------------- |
| `namespace.yaml`  | Per-user namespace with resource quotas        |
| `deployment.yaml` | App deployment with health probes & resources  |
| `service.yaml`    | ClusterIP service                              |
| `ingress.yaml`    | Ingress with TLS (cert-manager annotations)    |
| `database.yaml`   | PostgreSQL or MySQL StatefulSet                |
| `pvc.yaml`        | Persistent volume claim for databases          |
| `secret.yaml`     | Environment variables as K8s Secrets           |

---

## Security

- **JWT** access + refresh tokens with configurable expiry
- **Bcrypt** password hashing (12 rounds)
- **Helmet** HTTP security headers
- **RBAC** role-based route guards (`@Roles(UserRole.ADMIN)`)
- **Namespace isolation** — each user deploys to their own K8s namespace
- **Secrets** — env vars stored as K8s Secrets, never in plain manifests
- **Input validation** — `class-validator` on all DTOs

---

## Configuration

All configuration is via environment variables. See `backend/.env.example` for the full list:

| Variable            | Description                      | Default           |
| ------------------- | -------------------------------- | ----------------- |
| `PORT`              | Backend port                     | `4000`            |
| `DB_HOST`           | PostgreSQL host                  | `localhost`       |
| `DB_PORT`           | PostgreSQL port                  | `5432`            |
| `DB_USERNAME`       | Database user                    | `cloudhost`       |
| `DB_PASSWORD`       | Database password                | —                 |
| `DB_NAME`           | Database name                    | `cloudhost`       |
| `JWT_SECRET`        | JWT signing secret               | —                 |
| `JWT_EXPIRES_IN`    | Access token TTL                 | `15m`             |
| `REDIS_HOST`        | Redis host                       | `localhost`       |
| `REDIS_PORT`        | Redis port                       | `6379`            |
| `REGISTRY_URL`      | Container registry URL           | —                 |
| `PLATFORM_DOMAIN`   | Base domain for app subdomains   | `apps.localhost`  |

---

## License

MIT