From 4d2ababddf4516adc76075a37609af632937e964 Mon Sep 17 00:00:00 2001
From: Rajendra Reddy <rajendra@wdipl.com>
Date: Tue, 14 Apr 2026 16:51:22 +0000
Subject: [PATCH] Add readme.md

---
 readme.md | 270 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 270 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..fd2c419
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,270 @@
+# 🚀 CI/CD Deployment Guide (Template)
+
+> 📌 This is a **ready-to-use template**. Replace example values with your own before using.
+
+---
+
+# 📦 Overview
+
+This CI/CD setup automatically deploys your application when code is merged into environment branches.
+
+---
+
+# 🔁 Workflow (How Deployment Happens)
+
+```
+feature/* → PR → main → PR → (beta/testing/staging/production) → 🚀 deploy
+```
+
+### Steps:
+
+1. Create feature branch → `feature/xyz`
+2. Raise PR → `main`
+3. Merge into `main`
+4. Raise PR → `main` → target environment branch
+5. Merge → Deployment runs automatically
+
+---
+
+# 🌿 Branch Strategy
+
+| Branch       | Purpose          |
+| ------------ | ---------------- |
+| `main`       | Stable code      |
+| `beta`       | Internal testing |
+| `testing`    | QA testing       |
+| `staging`    | Pre-production   |
+| `production` | Live             |
+
+---
+
+# ⚙️ Environment Configuration
+
+Each branch deploys to a different server.
+
+### Example Mapping
+
+| Branch     | Folder Path Example      | PM2_ID Example      |
+| ---------- | ------------------------ | ------------------- |
+| beta       | `/home/user/app-beta`    | `app-beta[3000]`    |
+| testing    | `/home/user/app-testing` | `app-testing[3001]` |
+| staging    | `/var/www/app-staging`   | `app-staging[4000]` |
+| production | `/var/www/app-prod`      | `app-prod[5000]`    |
+
+---
+
+# ⚠️ PM2 Naming (VERY IMPORTANT)
+
+Your PM2 process should be named like:
+
+```
+app-name[port]
+```
+
+### ✅ Example
+
+```
+app-backend[3000]
+```
+
+### ❌ Do NOT confuse with:
+
+```
+app-name[1234]   ← random ID (WRONG)
+```
+
+---
+
+# ⚠️ IMPORTANT RULE (Shell Safety)
+
+Always wrap PM2_ID in quotes:
+
+```
+pm2 reload "$PM2_ID"
+pm2 logs "$PM2_ID" --lines 50 --nostream
+```
+
+---
+
+# ⚡ What the Deployment Does
+
+On every deploy:
+
+```bash
+cd <PROJECT_FOLDER>
+
+git fetch
+git reset --hard origin/<BRANCH_NAME>
+git pull origin <BRANCH_NAME>
+
+git log --oneline -5
+
+npm install
+
+pm2 reload "<PM2_ID>"
+
+pm2 logs "<PM2_ID>" --lines 50 --nostream
+```
+
+---
+
+# 🔐 Required Secrets (VERY IMPORTANT)
+
+You MUST configure these in your CI/CD (Gitea → Repository → Settings → Secrets)
+
+---
+
+## 🟡 For Beta / Testing (Password-based SSH)
+
+### Required Secrets:
+
+```
+BETA_SERVER_HOST=1.2.3.4
+BETA_SERVER_USERNAME=your-user
+BETA_SERVER_PASSWORD=your-password
+BETA_SERVER_PORT=22
+```
+
+👉 Used for:
+
+* `beta`
+* `testing`
+
+---
+
+## 🔵 For Staging (SSH Key-based)
+
+### Required Secrets:
+
+```
+STAGING_SERVER_HOST=1.2.3.5
+STAGING_SERVER_USERNAME=ubuntu
+STAGING_SERVER_KEY=<private-key-content>
+STAGING_SERVER_PORT=22
+```
+
+---
+
+## 🔴 For Production (SSH Key-based)
+
+### Required Secrets:
+
+```
+PRODUCTION_SERVER_HOST=1.2.3.6
+PRODUCTION_SERVER_USERNAME=ubuntu
+PRODUCTION_SERVER_KEY=<private-key-content>
+PRODUCTION_SERVER_PORT=22
+```
+
+---
+
+# 🔑 How to Add SSH Key
+
+1. On your server:
+
+   ```
+   cat ~/.ssh/id_rsa
+   ```
+
+2. Copy the full private key:
+
+   ```
+   -----BEGIN OPENSSH PRIVATE KEY-----
+   ...
+   -----END OPENSSH PRIVATE KEY-----
+   ```
+
+3. Paste into:
+
+   ```
+   STAGING_SERVER_KEY / PRODUCTION_SERVER_KEY
+   ```
+
+---
+
+# 🚀 How to Deploy
+
+### Deploy to Beta
+
+* Create PR → `main` → `beta`
+* Merge → auto deploy
+
+### Deploy to Testing
+
+* PR → `main` → `testing`
+
+### Deploy to Staging
+
+* PR → `main` → `staging`
+
+### Deploy to Production
+
+* PR → `main` → `production`
+
+---
+
+# 🛠️ Debugging
+
+### Check CI Logs
+
+* Gitea → Actions → Logs
+
+### SSH into Server
+
+```
+ssh user@server-ip
+cd /your/project/path
+```
+
+### Check PM2
+
+```
+pm2 list
+pm2 logs
+```
+
+---
+
+# ⚠️ Common Mistakes
+
+### ❌ Using wrong PM2 ID
+
+```
+app-name[1234]  ← dynamic ID
+```
+
+### ❌ Not quoting PM2_ID
+
+```
+pm2 reload $PM2_ID   ❌
+```
+
+### ❌ Manual changes on server
+
+```
+git reset --hard will delete them
+```
+
+---
+
+# 📈 Recommended Improvements
+
+* Add `npm run build`
+* Add health check
+* Add rollback strategy
+* Add notifications (Slack/Email)
+* Add caching
+
+---
+
+# 🧑‍💻 TL;DR
+
+* Always deploy via PR
+* Use PM2 format: `app-name[port]`
+* Always wrap in quotes
+* Set correct secrets
+* Never edit server manually
+
+---
+
+✅ Copy → Update values → Ready to use