abrban/cloud-host
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite ARCHITECTURE.md, README.md; add CHANGELOG and CONTRIBUTING

Browse Source 
- ARCHITECTURE.md: all modules, Helm charts, billing/lifecycle flow, WordPress
- README.md: updated features, API endpoints, configuration, project structure
- CHANGELOG.md: full changelog for all unreleased changes
- CONTRIBUTING.md: commit conventions, documentation requirements, PR checklist
This commit is contained in:
keyhan
2026-04-22 16:45:30 +03:30
parent e10f9c5235
commit 5f77c07183
4 changed files with 538 additions and 284 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ARCHITECTURE.md
+160 -141
View File
@@ -2,7 +2,7 @@
## Overview
CloudHost is a self-service PaaS platform that enables users to deploy Node.js and Laravel applications onto Kubernetes clusters managed by a super admin.
CloudHost is a self-service PaaS platform that enables users to deploy **Node.js**, **Laravel**, and **WordPress** applications onto Kubernetes clusters managed by a super admin. It includes a full billing/wallet system, automated lifecycle management, and Helm-based deployments.
---
@@ -16,7 +16,7 @@ CloudHost is a self-service PaaS platform that enables users to deploy Node.js a
│ HTTPS
▼
┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND (Next.js) │
│ FRONTEND (Next.js 14) │
│ ┌──────────┐ ┌───────────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Auth UI │ │ Deploy Wizard │ │ Dashboard│ │Admin Panel│ │
│ └──────────┘ └───────────────┘ └──────────┘ └───────────┘ │
@@ -24,205 +24,224 @@ CloudHost is a self-service PaaS platform that enables users to deploy Node.js a
│ REST API (JSON)
▼
┌─────────────────────────────────────────────────────────────────┐
│ BACKEND (NestJS) │
│ BACKEND (NestJS 10) │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────┐ │
│ │Auth │ │Applications │ │Deployments │ │Clusters │ │
│ │Module │ │Module │ │Module │ │Module │ │
│ └──────────┘ └──────────────┘ └────────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────┐ │
│ │Billing │ │Lifecycle │ │Snapshots │ │Tickets │ │
│ │Module │ │Module │ │Module │ │Module │ │
│ └──────────┘ └──────────────┘ └────────────┘ └──────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Kubernetes │ │ Build │ │ Logs & │ │
│ │ Service │ │ Service │ │ Metrics Service │ │
│ └────────┬─────────┘ └──────┬───────┘ └──────────────────┘ │
│ │ │ │
└───────────┼───────────────────┼──────────────────────────────────┘
│ │
┌───────▼────────┐ ┌──────▼────────┐
│ Kubernetes │ │ Container │
│ Cluster(s) │ │ Registry │
│ │ │ (Harbor/ECR) │
│ ┌───────────┐ │ └───────────────┘
│ │Namespace A│ │
│ │ ┌─Pod────┐│ │
│ │ │App ││ │ ┌────────────────┐
│ │ └────────┘│ │ │ PostgreSQL │
│ │ ┌─Pod────┐│ │ │ (Metadata DB) │
│ │ │DB ││ │ └────────────────┘
│ │ └────────┘│ │
│ └───────────┘ │
│ ┌───────────┐ │
│ │Namespace B│ │
│ │ ... │ │
│ └───────────┘ │
└───────────────┘
│ │ Kubernetes │ │ Helm │ │ Build │ │
│ │ Service │ │ Service │ │ Service │ │
│ └────────┬─────────┘ └──────┬───────┘ └──────┬───────────┘ │
└───────────┼───────────────────┼──────────────────┼───────────────┘
│ │ │
┌───────▼────────┐ ┌──────▼────────┐ ┌──────▼────────┐
│ Kubernetes │ │ Helm CLI │ │ Kaniko │
│ Cluster(s) │ │ (v3) │ │ (in-cluster) │
└───────────────┘ └───────────────┘ └───────────────┘
```
---
## 🔧 Tech Stack Justification
## 🧩 Module Overview
### Frontend: **Next.js 14 (App Router) + Tailwind CSS**
| Module | Purpose |
|--------|---------|
| **Auth** | JWT access/refresh tokens, Passport strategies, role guards |
| **Users** | User CRUD, admin activate/deactivate, profile management |
| **Applications** | App CRUD, code upload (zip), metadata, runtime detection |
| **Build** | Kaniko-based image builds via BullMQ queue; auto-detects Node.js/Laravel/WordPress |
| **Kubernetes** | K8s API interactions — namespace, scale, delete, pod logs, build pods |
| **Helm** | Helm CLI wrapper — install/upgrade, rollback, uninstall, history |
| **Deployments** | Deployment lifecycle orchestration, history, stop/restart |
| **Clusters** | Multi-cluster management, kubeconfig storage, default cluster selection |
| **Billing** | Wallet system (deposit/deduct), transaction ledger, plan cost calculation |
| **Lifecycle** | Cron-based scanner: auto-suspend expired apps, auto-delete after grace period |
| **Snapshots** | Application snapshot/backup management |
| **Tickets** | Support ticket system for users |
---
## 🔧 Tech Stack
### Frontend: Next.js 14 (App Router) + Tailwind CSS
| Reason | Detail |
|--------|--------|
| **SSR & SEO** | Server-side rendering for fast initial loads |
| **App Router** | Modern React Server Components, layouts, loading states |
| **App Router** | React Server Components, layouts, loading states |
| **Tailwind CSS** | Rapid UI development, consistent design system |
| **TypeScript** | End-to-end type safety with shared types |
| **React Query** | Efficient server state management, caching, polling for live status |
| **React Query** | Server state management, caching, polling for live status |
| **Zustand** | Lightweight client state management (auth store) |
### Backend: **NestJS (Node.js)**
### Backend: NestJS 10 (Node.js)
| Reason | Detail |
|--------|--------|
| **Modular architecture** | Each domain (auth, apps, deployments, clusters) is a self-contained module |
| **Modular architecture** | Each domain is a self-contained module |
| **TypeScript native** | Full type safety, shared interfaces with frontend |
| **Decorator-based** | Clean controller/service pattern, guards, interceptors |
| **@kubernetes/client-node** | Official K8s client for Node.js — direct API interaction |
| **Bull/BullMQ** | Redis-backed job queues for async build & deploy pipelines |
| **TypeORM** | Mature PostgreSQL ORM with migration support |
| **@kubernetes/client-node** | Official K8s client for direct API interaction |
| **Helm CLI** | Shell-out to helm for chart-based deployments |
| **Bull/BullMQ** | Redis-backed job queues for async build pipelines |
| **TypeORM** | PostgreSQL ORM with entity-based schema |
### Database: **PostgreSQL**
### Build System: Kaniko (in-cluster)
| Reason | Detail |
|--------|--------|
| **ACID compliance** | Critical for deployment state tracking |
| **JSON columns** | Store flexible config/metadata without schema changes |
| **Mature ecosystem** | Battle-tested, excellent TypeORM support |
| **Scalability** | Read replicas, partitioning for growth |
| **No Docker daemon** | Builds inside K8s pods — no Docker-in-Docker |
| **Runtime detection** | Auto-detects Node.js, Laravel, WordPress from source files |
| **WordPress support** | Custom entrypoint script for wp-content merging |
| **Registry push** | Native push to insecure or authenticated registries |
### Build System: **Kaniko (in-cluster)**
### Deployment: Helm v3 Charts
| Reason | Detail |
|--------|--------|
| **No Docker daemon** | Builds images inside K8s pods — no Docker-in-Docker security issues |
| **Registry push** | Native push to any OCI-compatible registry |
| **Caching** | Layer caching for faster rebuilds |
### Container Registry: **Harbor (self-hosted) or cloud-managed (ECR/GCR/ACR)**
| Reason | Detail |
|--------|--------|
| **Private images** | User apps must not be publicly accessible |
| **Vulnerability scanning** | Harbor provides built-in image scanning |
| **Multi-tenancy** | Project-based access control |
### Queue System: **Redis + BullMQ**
| Reason | Detail |
|--------|--------|
| **Async builds** | Image builds are long-running — must not block API |
| **Retries** | Failed builds auto-retry with backoff |
| **Progress tracking** | Real-time build status updates |
| **Templated manifests** | Single chart handles Node.js, Laravel, WordPress |
| **Rollback support** | Built-in revision history and rollback |
| **Resource policies** | PVCs and secrets persist across helm uninstall |
| **Registry pull secrets** | Auto-created per namespace for insecure registries |
---
## 🔐 Security Architecture
```
┌─────────────────────────────────────────┐
│ Security Layers │
├─────────────────────────────────────────┤
│ │
│ 1. JWT Authentication (access/refresh) │
│ 2. Role-Based Access (User / Admin) │
│ 3. K8s Namespace Isolation per user │
│ 4. K8s RBAC — scoped ServiceAccounts │
│ 5. Network Policies between namespaces │
│ 6. Resource Quotas & Limit Ranges │
│ 7. Secrets encryption (K8s Secrets) │
│ 8. Input validation on all user inputs │
│ 9. Rate limiting on API endpoints │
│ │
└─────────────────────────────────────────┘
```
- JWT Authentication (access + refresh tokens)
- Role-Based Access Control (User / Admin)
- K8s Namespace Isolation per user
- K8s RBAC — scoped ServiceAccounts
- Network Policies between namespaces
- Resource Quotas & Limit Ranges
- Secrets encryption (K8s Secrets)
- Input validation (class-validator on all DTOs)
- Helmet HTTP security headers
- Bcrypt password hashing (12 rounds)
---
## 🔄 Deployment Flow
```
User uploads code ──► API receives ──► Store metadata in PostgreSQL
│
▼
Queue build job (BullMQ)
│
▼
Kaniko Pod builds image
│
▼
Push to Container Registry
│
▼
Generate K8s manifests from templates
│
▼
Apply to target cluster via K8s API
│
▼
Create: Namespace, Deployment, Service,
Ingress, PVC, DB, Secrets
│
▼
Update deployment status in DB
│
▼
User sees live status in dashboard
User uploads code (zip)
│
▼
API stores file + metadata in PostgreSQL
│
▼
BullMQ build job queued
│
▼
detectRuntime() → nodejs | laravel | wordpress
│
▼
Generate Dockerfile per runtime
│
▼
Kaniko Pod builds image → pushes to registry
│
▼
HelmService.installOrUpgrade() with cloudhost-app chart
│
▼
Helm creates: Namespace, Deployment, Service, Ingress,
DB, PVC, Secrets, Registry Pull Secret, TLS cert
│
▼
App live at https://<subdomain>.apps.cloudhost.ir
```
---
## 💰 Billing & Lifecycle Flow
```
ACTIVE ──(expires)──► SUSPENDED ──(grace)──► PENDING_DELETION ──► DELETED
▲ │ │
└────── payment ────────┘ │
└────── payment (within grace) ──────────────────┘
```
- **Billing Cycles**: HOURLY | MONTHLY | YEARLY
- **Hourly plans**: auto-renew from wallet each hour
- **Grace periods**: admin-configurable via PlatformSettings table
- **Lifecycle Scanner**: runs every 60s (configurable)
---
## 🚀 Helm Chart: cloudhost-app
Single chart at `backend/helm/cloudhost-app/` handles all runtimes:
| Template | Purpose |
|----------|---------|
| `deployment.yaml` | App pod with imagePullSecrets, probes, WordPress volumes |
| `service.yaml` | ClusterIP (port 80 → app port) |
| `ingress.yaml` | Nginx ingress with cert-manager TLS |
| `secret.yaml` | User env vars as K8s Secret |
| `db-deployment.yaml` | PostgreSQL or MySQL with health probes |
| `db-service.yaml` | Database ClusterIP service |
| `db-pvc.yaml` | Database storage (resource-policy: keep) |
| `db-secret.yaml` | Database credentials (resource-policy: keep) |
| `wp-pvc.yaml` | WordPress wp-content PVC (resource-policy: keep) |
| `registry-pull-secret.yaml` | imagePullSecret for insecure registry |
---
## 📁 Project Structure
```
host/
├── ARCHITECTURE.md
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── docker-compose.yml
├── backend/ # NestJS API
│ ├── src/
│ │ ├── main.ts
│ │ ├── app.module.ts
│ │ ├── common/ # Shared utilities, guards, decorators
│ │ ├── config/ # Environment configuration
│ │ ├── auth/ # JWT auth, strategies, guards
│ │ ├── users/ # User management
│ │ ├── applications/ # App CRUD, code upload
│ │ ├── deployments/ # Deployment lifecycle
│ │ ├── clusters/ # K8s cluster management (admin)
│ │ ├── kubernetes/ # K8s client, manifest generation
│ │ ├── build/ # Image build pipeline
│ │ └── database/ # TypeORM entities, migrations
│ ├── templates/ # K8s YAML templates (Handlebars)
├── backend/
│ ├── Dockerfile
│ ├── package.json
│ └── tsconfig.json
├── frontend/ # Next.js App
│ ├── helm/cloudhost-app/ # Helm chart for user apps
│ ├── src/
│ │ ├── app/ # App Router pages
│ │ ├── components/ # Reusable UI components
│ │ ├── lib/ # API client, utilities
│ │ ├── hooks/ # Custom React hooks
│ │ └── types/ # TypeScript interfaces
│ │ ├── main.ts / app.module.ts
│ │ ├── auth/ # JWT + Passport
│ │ ├── users/ # User management
│ │ ├── applications/ # App CRUD + upload
│ │ ├── deployments/ # Deploy orchestration
│ │ ├── clusters/ # Multi-cluster (admin)
│ │ ├── kubernetes/ # K8s client + Helm service
│ │ ├── build/ # Kaniko builds (BullMQ)
│ │ ├── billing/ # Wallet + transactions
│ │ ├── lifecycle/ # Auto-suspend/delete
│ │ ├── snapshots/ # App snapshots
│ │ └── tickets/ # Support tickets
│ └── templates/ # Legacy Handlebars (deprecated)
├── frontend/
│ ├── Dockerfile
│ ├── package.json
│ └── tailwind.config.ts
└── k8s/ # Platform's own K8s deployment
├── base/
└── overlays/
│ └── src/
│ ├── app/dashboard/ # Apps, deploy, admin pages
│ ├── components/
│ ├── lib/ # API client, auth store
│ └── types/ # Shared TS interfaces
└── uploads/ # User-uploaded code archives
```
---
## 🚀 Future Scaling Considerations
## 🔮 Future Considerations
1. **Multi-cluster support** — Deploy to different clusters/regions
2. **Custom domains** — Let users bring their own domains with auto TLS
3. **Horizontal Pod Autoscaler** — Auto-scale based on metrics
4. **WebSocket/SSE** — Real-time build logs streaming
5. **Plugin system** — Support Python, Go, Rust runtimes
6. **Marketplace** — Pre-built app templates (WordPress, etc.)
7. **Billing integration** — Usage-based billing per resource consumption
8. **GitOps** — ArgoCD integration for declarative deployments
1. Custom domains with auto TLS via cert-manager
2. Horizontal Pod Autoscaler based on CPU/memory
3. WebSocket/SSE for real-time build log streaming
4. GitOps integration (ArgoCD)
5. Additional runtimes (Python, Go, Rust)
6. App marketplace with pre-built templates
7. Per-app resource consumption dashboards