Files

T

keyhan 33be1649c4 init

2026-04-05 15:22:01 +03:30

10 KiB

Raw Blame History

☁️ 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

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

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

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

2. Environment Variables

# 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)

docker compose up --build

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

Open http://localhost:3000 in your browser.

4. Run Locally (development)

# 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

10 KiB Raw Blame History