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.

# 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

git tag backend-dev-v1.0.1
git push origin backend-dev-v1.0.1

Frontend Learner Only

git tag learner-dev-v1.0.1
git push origin learner-dev-v1.0.1

Frontend Management Only

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.

# 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

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

# 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

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

# 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

# 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

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

# 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

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

#!/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:

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

# 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

# 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

# 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

# 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

# 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