elearning/DEPLOYMENT.md

# 🚀 E-Learning Platform Deployment Guide

## Overview

This project uses **tag-based deployment** with semantic versioning. Deployments are triggered by pushing Git tags, not by pushing to branches.

---

## 📋 Prerequisites

- Git installed and configured
- Access to push tags to the repository
- Understanding of semantic versioning

---

## 🏷️ Tag Naming Convention

### Format
```
<service>-<environment>-v<version>
```

### Services
- `backend` - Backend API
- `learner` - Frontend Learner
- `management` - Frontend Management

### Environments
- `dev` - Development server
- `staging` - Staging server (future)
- `prod` - Production server (future)

### Version Format (Semantic Versioning)
- **Major.Minor.Patch** (e.g., `1.0.0`)
- **Major.Minor.Patch-PreRelease** (e.g., `1.0.0-beta`, `1.0.0-rc1`)

### Examples
```
backend-dev-v1.0.0
learner-dev-v1.2.3
management-dev-v2.0.0-beta
```

---

## 🚀 Deployment Commands

### 1. Deploy All Services (Same Version)

Use this when deploying a complete release with all services updated.

```bash
# Set version
VERSION="1.0.0"

# Create tags for all services
git tag backend-dev-v${VERSION}
git tag learner-dev-v${VERSION}
git tag management-dev-v${VERSION}

# Push all tags at once
git push origin --tags

# Or push individually
git push origin backend-dev-v${VERSION}
git push origin learner-dev-v${VERSION}
git push origin management-dev-v${VERSION}
```

---

### 2. Deploy Single Service

Use this when only one service needs to be updated (e.g., hotfix).

#### Backend Only
```bash
git tag backend-dev-v1.0.1
git push origin backend-dev-v1.0.1
```

#### Frontend Learner Only
```bash
git tag learner-dev-v1.0.1
git push origin learner-dev-v1.0.1
```

#### Frontend Management Only
```bash
git tag management-dev-v1.0.1
git push origin management-dev-v1.0.1
```

---

### 3. Deploy Pre-Release Version

Use this for testing before official release.

```bash
# Beta release
git tag backend-dev-v1.0.0-beta
git push origin backend-dev-v1.0.0-beta

# Release candidate
git tag backend-dev-v1.0.0-rc1
git push origin backend-dev-v1.0.0-rc1

# Alpha release
git tag backend-dev-v1.0.0-alpha
git push origin backend-dev-v1.0.0-alpha
```

---

### 4. View Existing Tags

```bash
# List all tags
git tag

# List tags for specific service
git tag | grep backend-dev
git tag | grep learner-dev
git tag | grep management-dev

# Show tag details
git show backend-dev-v1.0.0
```

---

### 5. Delete Tag (If Mistake)

```bash
# Delete local tag
git tag -d backend-dev-v1.0.0

# Delete remote tag
git push origin --delete backend-dev-v1.0.0
```

---

## 📝 Complete Deployment Workflow

### Scenario: Release v1.0.0

```bash
# 1. Ensure you're on dev branch and up to date
git checkout dev
git pull origin dev

# 2. Make your changes
git add .
git commit -m "feat: implement user authentication"
git push origin dev

# 3. Test locally (optional but recommended)
cd Backend
docker compose up

# 4. Create version tags
git tag backend-dev-v1.0.0
git tag learner-dev-v1.0.0
git tag management-dev-v1.0.0

# 5. Push tags to trigger CI/CD
git push origin --tags

# 6. Monitor CI/CD pipeline
# - Check Forgejo Actions
# - Check Discord notifications
# - Verify deployment on server

# 7. Verify deployment
curl http://192.168.1.69:20901/health
curl http://192.168.1.69:20902
curl http://192.168.1.69:20903
```

---

### Scenario: Hotfix v1.0.1 (Backend Only)

```bash
# 1. Fix the bug
git checkout dev
git pull origin dev
git add .
git commit -m "fix: resolve authentication bug"
git push origin dev

# 2. Create patch version tag (only backend)
git tag backend-dev-v1.0.1

# 3. Push tag
git push origin backend-dev-v1.0.1

# 4. Only backend will be rebuilt and deployed
# Frontend services remain on v1.0.0
```

---

### Scenario: Feature Release v1.1.0

```bash
# 1. Develop feature
git checkout dev
git add .
git commit -m "feat: add course filtering"
git push origin dev

# 2. Create minor version tags
git tag backend-dev-v1.1.0
git tag learner-dev-v1.1.0
git tag management-dev-v1.1.0

# 3. Push tags
git push origin --tags
```

---

### Scenario: Breaking Change v2.0.0

```bash
# 1. Implement breaking changes
git checkout dev
git add .
git commit -m "feat!: redesign API endpoints (BREAKING CHANGE)"
git push origin dev

# 2. Create major version tags
git tag backend-dev-v2.0.0
git tag learner-dev-v2.0.0
git tag management-dev-v2.0.0

# 3. Push tags
git push origin --tags
```

---

## 🔄 Rollback to Previous Version

If a deployment fails or has issues, rollback to a previous version:

### On Server (SSH)

```bash
# SSH to server
ssh dev@192.168.1.69

# Navigate to repo
cd ~/repo

# Update environment variables to previous version
./replace-env.sh BACKEND_TAG "1.0.0"
./replace-env.sh FRONTEND_TAG "1.0.0"
./replace-env.sh MANAGEMENT_TAG "1.0.0"

# Redeploy with old version
./deploy.sh backend
./deploy.sh learner
./deploy.sh management
```

---

## 📊 Version History

### View Deployment History

```bash
# List all tags sorted by version
git tag -l "backend-dev-v*" --sort=-v:refname

# Show commits for a specific tag
git log backend-dev-v1.0.0 -1

# Compare versions
git diff backend-dev-v1.0.0 backend-dev-v1.1.0
```

---

## 🛠️ Helper Scripts

### Create Multi-Service Tag Script

Create `scripts/tag-release.sh`:

```bash
#!/bin/bash

if [ -z "$1" ]; then
  echo "Usage: ./tag-release.sh <version>"
  echo "Example: ./tag-release.sh 1.0.0"
  exit 1
fi

VERSION=$1

echo "Creating tags for version ${VERSION}..."
git tag backend-dev-v${VERSION}
git tag learner-dev-v${VERSION}
git tag management-dev-v${VERSION}

echo "Tags created:"
git tag | grep "v${VERSION}"

echo ""
echo "Push tags with: git push origin --tags"
```

Usage:
```bash
chmod +x scripts/tag-release.sh
./scripts/tag-release.sh 1.0.0
git push origin --tags
```

---

## ⚠️ Important Notes

> [!IMPORTANT]
> **Pushing to `dev` branch does NOT trigger deployment.** You must create and push a tag to deploy.

> [!WARNING]
> **Tags are immutable.** Once pushed, a tag should not be changed. If you need to fix a release, create a new patch version.

> [!TIP]
> **Use pre-release tags for testing.** Tag with `-beta` or `-rc1` suffix to test before official release.

---

## 🔍 Troubleshooting

### Tag Already Exists
```bash
# Error: tag 'backend-dev-v1.0.0' already exists
# Solution: Use next version number
git tag backend-dev-v1.0.1
```

### CI/CD Not Triggering
```bash
# Check if tag matches pattern
git tag | grep backend-dev-v1.0.0

# Verify tag was pushed to remote
git ls-remote --tags origin | grep backend-dev-v1.0.0
```

### Wrong Tag Pushed
```bash
# Delete from remote
git push origin --delete backend-dev-v1.0.0

# Delete from local
git tag -d backend-dev-v1.0.0

# Create correct tag
git tag backend-dev-v1.0.1
git push origin backend-dev-v1.0.1
```

---

## 📚 Semantic Versioning Guide

### When to Increment

| Change Type | Version | Example |
|-------------|---------|---------|
| Bug fix | Patch (x.x.1) | `1.0.0` → `1.0.1` |
| New feature (backward compatible) | Minor (x.1.x) | `1.0.0` → `1.1.0` |
| Breaking change | Major (1.x.x) | `1.0.0` → `2.0.0` |
| Pre-release | Add suffix | `1.0.0-beta` |

### Examples

```bash
# Bug fixes
1.0.0 → 1.0.1 → 1.0.2

# New features
1.0.0 → 1.1.0 → 1.2.0

# Breaking changes
1.0.0 → 2.0.0 → 3.0.0

# Pre-releases
1.0.0-alpha → 1.0.0-beta → 1.0.0-rc1 → 1.0.0
```

---

## 🎯 Quick Reference

```bash
# Deploy all services v1.0.0
git tag backend-dev-v1.0.0 learner-dev-v1.0.0 management-dev-v1.0.0
git push origin --tags

# Deploy backend only v1.0.1
git tag backend-dev-v1.0.1 && git push origin backend-dev-v1.0.1

# View tags
git tag | grep dev

# Delete tag
git tag -d backend-dev-v1.0.0
git push origin --delete backend-dev-v1.0.0
```

---

**Last Updated:** 2026-02-11