create-luff-app 1.0.4 → 1.0.6

package/NOTES.md

@@ -0,0 +1,216 @@
+# Luff Boilerplate
+
+This repository contains a full-stack Next.js + Node.js Microservices architecture boilerplate, ready for local execution and seamless Kubernetes (K8s) deployment via ArgoCD.
+
+Everything is containerized, fully configured for Google OAuth authentication, and automatically validated with CI/CD.
+
+---
+
+## 🚀 1. Initial Setup Required
+
+Before running this project for the first time, you must configure your environment locally.
+
+### Prerequisites:
+
+- **Node.js** (v20+)
+- **Docker** and **Docker Desktop / Minikube**
+- **kubectl** (connected to your local Kubernetes cluster)
+- **ArgoCD** (must be installed on your local Kubernetes cluster)
+
+### Step 1: Install Dependencies & Setup Env Files
+
+We have an automated setup script that installs NPM packages and copies the required `.env.example` files to `.env`.
+
+```bash
+npm run setup
+```
+
+Wait for `npm install` and Husky to finish.
+
+### Step 2: Configure Environment Variables
+
+You MUST explicitly provide Google OAuth credentials and URLs for the frontend build and backend authentication to work. Check these three `.env` files and verify their values.
+
+**1. `frontend/.env`**
+
+```env
+NEXT_PUBLIC_API_URL=http://localhost:4000
+NEXT_PUBLIC_GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
+```
+
+**2. `backend/auth/.env`**
+
+```env
+PORT=4001
+JWT_SECRET="your-jwt-secret-change-in-production"
+GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your_client_secret
+FRONTEND_URL=http://localhost:3000
+NODE_ENV=development
+```
+
+**3. `backend/posts/.env`**
+
+```env
+PORT=4002
+JWT_SECRET="your-jwt-secret"
+NODE_ENV=development
+```
+
+**4. `backend/payment/.env`**
+
+```env
+PORT=4003
+RAZORPAY_KEY_ID=rzp_test_your_id
+RAZORPAY_KEY_SECRET=your_secret_key
+DATABASE_URL="postgresql://postgres:postgres@localhost:5435/payment_db"
+JWT_SECRET="your-jwt-secret"
+NODE_ENV=development
+```
+
+### Step 3: Kubernetes Secrets
+
+```bash
+# App, Auth & Posts Secrets (...)
+
+# Create Payment Secrets
+kubectl create secret generic payment-secrets \
+  --from-literal=database-url="postgresql://postgres:postgres@payment-db-service:5432/payment_db" \
+  --from-literal=razorpay-key-id="your_key" \
+  --from-literal=razorpay-key-secret="your_secret" \
+  --from-literal=jwt-secret="your-jwt-secret"
+```
+
+---
+
+## 🌟 2. How To Run Locally
+
+We support two modes of development:
+
+### 1. Native Mode (Recommended)
+
+This is the fastest loop. Run everything directly on your machine:
+
+```bash
+npm run run-local
+```
+
+This script handles:
+
+- Stopping K8s port conflicts
+- Starting local Docker DBs
+- Running all services via `npm run dev`
+
+### 2. Kubernetes Mode (GitOps)
+
+Follow this if you want to test the full K8s stack:
+
+1. **Build & Deploy**: `npm run run-k8s build`
+2. **Access Dashboard**: `npm run argo`
+3. **Connect Ports**: `npm run access`
+
+We utilize ArgoCD as the GitOps agent. It constantly monitors your main branch's `k8s/` folder and applies the configuration locally.
+
+### Step 1: Tell ArgoCD to watch your directory
+
+Apply the custom Application configuration directly:
+
+```bash
+kubectl apply -f argocd/application.yaml
+```
+
+### Step 2: Build the Local Images (Automated)
+
+Your Kubernetes `Deployment` manifests are configured to pull from `ghcr.io/luff-org/...` with an `IfNotPresent` pull policy. To run the images locally exactly as they are configured in your manifests, **we have created an automation script**.
+
+This script pulls your `.env` Client ID, tags images according to your current commit SHA (what ArgoCD expects), and restarts the Kubernetes pods.
+
+```bash
+./scripts/deploy-local.sh
+```
+
+### Step 3: Port Forwarding
+
+Because we are working locally, we must manually expose K8s services to `localhost`:
+
+```bash
+# Terminal 1 - For the Frontend Application
+kubectl port-forward svc/frontend-service 3000:3000
+
+# Terminal 2 - For the API Gateway (Backend)
+kubectl port-forward svc/api-gateway 4000:4000
+```
+
+Visit `http://localhost:3000` — Your Google OAuth login will be functioning seamlessly.
+
+---
+
+## 🔄 3. What To Do Whenever You Run This Afterwards
+
+When returning to development on a new day, you **DO NOT** need to repeat the secret configuration or ArgoCD setup. You just have to build any new changes and run your port-forwards.
+
+1. **Commit your code to Git**: Or ArgoCD will desync!
+2. **Run the Automation Script**: To push the newest changes directly to your local cluster:
+   ```bash
+   ./scripts/deploy-local.sh
+   ```
+3. **Start your tunnels**:
+   ```bash
+   kubectl port-forward svc/frontend-service 3000:3000
+   kubectl port-forward svc/api-gateway 4000:4000
+   ```
+
+_(Alternatively, if you only want to develop quickly on your host machine WITHOUT Kubernetes, you can bypass Docker altogether by running `npm run dev` in the root folder!)_
+
+---
+
+## 🤖 4. Ensuring Automation Works (GitHub Actions CI/CD)
+
+Whenever you push to `main` on GitHub, our unified pipeline (`.github/workflows/pipeline.yml`) runs automatically.
+
+**To ensure this workflow succeeds on the cloud:**
+You MUST add your `GOOGLE_CLIENT_ID` to GitHub Secrets. Failure to do so means the Cloud-built Docker image will have an empty Google Client ID baked into its statically-generated frontend!
+
+**Go to GitHub**:
+
+1. Open Repository > `Settings`
+2. Navigate to `Secrets and variables` > `Actions`
+3. Click `New repository secret`
+4. **Name**: `GOOGLE_CLIENT_ID`
+5. **Secret**: `your_client_id.apps.googleusercontent.com`
+6. Click **Add secret**.
+
+_(The frontend URL and other runtime variables are dynamically passed, but Next.js `NEXT_PUBLIC_` variables are physically built into the Docker image, so this is strictly required!)\_
+
+---
+
+## 🎨 5. Personalization & Customization (For New Users)
+
+If you are cloning this boilerplate to start your own project, you need to update a few hardcoded values to point to your own GitHub Organization and Repository.
+
+### Step 1: Search and Replace
+
+Search the entire repository for `luff-org` and replace it with your own **GitHub Username** or **Organization Name** (in lowercase).
+
+- **Impacts**: K8s image paths, Docker tags, and CI/CD registry paths.
+
+### Step 2: Update ArgoCD Repo URL
+
+Open `argocd/application.yaml` and update the `repoURL` to point to your new fork or repository:
+
+```yaml
+repoURL: https://github.com/YOUR_ORG/YOUR_REPO.git
+```
+
+### Step 3: Update Production API URL
+
+Open `.github/workflows/pipeline.yml` and update the `NEXT_PUBLIC_API_URL` under the `Build & Push` job to your actual production domain:
+
+```yaml
+build-args: |
+  NEXT_PUBLIC_API_URL=https://api.your-actual-domain.com
+```
+
+### Step 4: Database Names & Secrets
+
+If you change the service names or database names in the `k8s/` manifests, remember to update the corresponding `DATABASE_URL` strings in your **Kubernetes Secrets** (Step 1.3 above).

package/README.md

@@ -1,10 +1,35 @@
-# Microservices Boilerplate
+# 💨 Luff Microservices Boilerplate
 
-A **production-grade microservices monorepo** built with Turborepo, TypeScript, Next.js, Express, Prisma, and PostgreSQL.
+[![NPM Version](https://img.shields.io/npm/v/create-luff-app?color=blue&style=flat-square)](https://www.npmjs.com/package/create-luff-app)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
 
-## Architecture
+A **production-grade microservices monorepo** designed for speed, scalability, and developer experience. Built with Turborepo, Next.js, Express, Prisma, and PostgreSQL.
 
+---
+
+## 🚀 Quick Start with CLI
+
+The fastest way to scaffold a new project using this boilerplate is with our official CLI:
+
+```bash
+npx create-luff-app <your-app-name>
 ```
+
+> [!TIP]
+> This command will clone the repository, install dependencies, and set up your project structure automatically.
+
+---
+
+## 📝 Operational Notes
+
+For detailed troubleshooting on database connections, Kubernetes local setup, and Docker build fixes, see [NOTES.md](./NOTES.md).
+
+---
+
+## 🏗️ Architecture
+
+```text
                     ┌─────────────┐
                     │  API Gateway│  :4000
                     │  (Express)  │
@@ -30,127 +55,135 @@ A **production-grade microservices monorepo** built with Turborepo, TypeScript,
             └─────────────────────────────┘
 ```
 
-## Tech Stack
-
-| Layer        | Technology                                   |
-| ------------ | -------------------------------------------- |
-| Frontend     | Next.js 14, React, TailwindCSS, React Query  |
-| API Client   | Axios                                        |
-| Backend      | Node.js, Express, TypeScript                 |
-| Database     | PostgreSQL, Prisma ORM                       |
-| Auth         | Google OAuth (PostMessage flow), JWT         |
-| Gateway      | http-proxy-middleware, rate-limit            |
-| Monorepo     | Turborepo, npm workspaces                    |
-| Logging      | Pino                                         |
-| Config       | Zod validation, dotenv                       |
-| Docker       | Multi-stage builds                           |
-| Orchestrator | Kubernetes                                   |
-| Code Quality | ESLint, Prettier, Husky, Commitlint          |
-
-## Quick Start
+---
+
+## 🛠️ Tech Stack
+
+| Layer        | Technology                                        |
+| :----------- | :------------------------------------------------ |
+| **Frontend** | Next.js 14 (App Router), TailwindCSS, React Query |
+| **Backend**  | Node.js, Express, TypeScript                      |
+| **Database** | PostgreSQL, Prisma ORM                            |
+| **Auth**     | Google OAuth (PostMessage flow), JWT              |
+| **Monorepo** | Turborepo, npm workspaces                         |
+| **Infra**    | Docker, Kubernetes (ArgoCD ready)                 |
+| **Quality**  | ESLint, Prettier, Husky, Commitlint               |
+
+---
+
+## ⚡ Local Development Setup
+
+Follow these steps to get your environment running from scratch.
+
+### 1. Prerequisites
+
+Ensure you have the following installed:
+
+- **Node.js**: `v20.x` or higher
+- **Docker**: For running databases locally
+
+### 2. Installation
+
+If you didn't use the CLI, clone and install manually:
 
 ```bash
-# 1. Clone and install
-git clone <repo-url>
+git clone https://github.com/Luff-Org/Luff-Boilerplate.git
 cd Luff-Boilerplate
 npm install
+```
+
+### 3. Environment & Databases
 
-# 2. Copy environment files
-bash scripts/setup.sh
+We provide a setup script to automate `.env` creation:
 
-# 3. Start databases (requires Docker)
+```bash
+# Automatically creates .env files from .env.example
+npm run setup
+
+# Spin up PostgreSQL instances via Docker
 docker compose -f docker/docker-compose.yml up auth-db posts-db -d
+```
 
-# 4. Generate Prisma clients and push schemas
+### 4. Database Initialization
+
+Generate Prisma clients and push schemas to your local databases:
+
+```bash
+# Auth service
 cd backend/auth && npm run db:push && npm run db:generate && cd ../..
+
+# Posts service
 cd backend/posts && npm run db:push && npm run db:generate && cd ../..
+```
 
-# 5. Start all services
+### 5. Start Developing
+
+```bash
 npm run dev
 ```
 
-This starts:
+Your services will be available at:
+
+- **Web Interface**: [http://localhost:3000](http://localhost:3000)
+- **API Gateway**: [http://localhost:4000](http://localhost:4000)
+- **Auth Service**: [http://localhost:4001](http://localhost:4001)
+- **Posts Service**: [http://localhost:4002](http://localhost:4002)
 
-| Service        | URL                     |
-| -------------- | ----------------------  |
-| API Gateway    | http://localhost:4000   |
-| Auth Service   | http://localhost:4001   |
-| Posts Service  | http://localhost:4002   |
-| Web Frontend   | http://localhost:3000   |
+---
 
-## Project Structure
+## 📂 Project Structure
 
 ```text
-├── frontend/              # Unified Next.js application (Auth + Posts)
+├── frontend/              # Unified Next.js application
 ├── backend/
-│   ├── auth/              # Auth microservice (Google OAuth postmessage, JWT)
+│   ├── auth/              # Auth microservice (Google OAuth + JWT)
 │   ├── posts/             # Posts microservice (CRUD)
-│   └── api-gateway/       # API Gateway (Express proxy, rate-limit)
-├── shared/
-│   ├── types/             # Shared TypeScript types
-│   ├── logger/            # Shared Pino logger setup
-│   ├── config/            # Zod env validation schema
-│   └── eslint-config/     # Default ESLint rules
-├── docker/                # Docker Compose Definitions
-├── k8s/                   # Kubernetes Manifests
-└── scripts/               # CI/CD and Local Setup Scripts
+│   └── api-gateway/       # Express Proxy & Rate Limiting
+├── shared/                # Shared internal packages (Types, Logger, Config)
+├── docker/                # Docker Compose configurations
+├── k8s/                   # Kubernetes manifests
+└── scripts/               # Automation & Setup scripts
 ```
 
-## API Endpoints
+---
 
-### Auth Service (Proxied via Gateway `:4000`)
+## 🔐 Google OAuth Configuration
 
-| Method | Endpoint       | Auth | Description                   |
-| ------ | -------------- | ---- | ----------------------------- |
-| POST   | /auth/login    | No   | Google OAuth postmessage login|
-| GET    | /auth/me       | Yes  | Get current user profile      |
-| POST   | /auth/logout   | Yes  | Logout (clear session)        |
+To enable authentication:
 
-### Posts Service (Proxied via Gateway `:4000`)
+1. Create OAuth credentials in [Google Cloud Console](https://console.cloud.google.com/apis/credentials).
+2. Set authorized origin to `http://localhost:3000`.
+3. Update `GOOGLE_CLIENT_ID` in `backend/auth/.env` and `NEXT_PUBLIC_GOOGLE_CLIENT_ID` in `frontend/.env`.
 
-| Method | Endpoint       | Auth | Description          |
-| ------ | -------------- | ---- | -------------------- |
-| GET    | /posts         | No   | List all posts       |
-| GET    | /posts/:id     | No   | Get post by ID       |
-| POST   | /posts         | Yes  | Create a post        |
-| DELETE | /posts/:id     | Yes  | Delete a post        |
+---
 
-## Docker
+## 🐳 Deployment
 
-### Run with Docker Compose
+### Docker Compose
 
 ```bash
 docker compose -f docker/docker-compose.yml up --build
 ```
 
-### Build individual images
+### Kubernetes
 
 ```bash
-docker build -f backend/auth/Dockerfile -t auth-service .
-docker build -f backend/posts/Dockerfile -t posts-service .
-docker build -f backend/api-gateway/Dockerfile -t api-gateway .
-docker build -f frontend/Dockerfile -t frontend-app .
+kubectl apply -f k8s/
 ```
 
-## Kubernetes
-
-```bash
-# Apply all manifests
-kubectl apply -f k8s/
+---
 
-# Note: You must manually deploy secrets in your cluster:
-# - auth-secrets (database-url, jwt-secret, google auth credentials)
-# - posts-secrets (database-url, jwt-secret)
-```
+## 📜 Scripts
 
-## Scripts
+| Command         | Description                             |
+| :-------------- | :-------------------------------------- |
+| `npm run dev`   | Starts all services in development mode |
+| `npm run build` | Builds all apps and packages            |
+| `npm run setup` | Initializes environment files           |
+| `npm run lint`  | Runs linting across the monorepo        |
 
-```bash
-npm run dev       # Start all services (Turborepo)
-npm run build     # Build all TypeScript packages & apps
-npm run lint      # Lint across the monorepo
-```
+---
 
-## License
+## 📄 License
 
-MIT
+This project is licensed under the [MIT License](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-luff-app",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "CLI to scaffold the Luff Microservices Boilerplate",
   "bin": {
     "create-luff-app": "bin/cli.js"
@@ -13,7 +13,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Luff-Org/Luff-Boilerplate"
+    "url": "git+https://github.com/Luff-Org/Luff-Boilerplate.git"
   },
   "license": "MIT"
 }