271 lines
4.1 KiB
Markdown
271 lines
4.1 KiB
Markdown
# 🚀 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
|