# ☁️ 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 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://.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