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