elearning/docs/forgejo_setup.md

# Forgejo Setup Guide

## 🎯 What is Forgejo?

**Forgejo** is a self-hosted Git server (like GitHub or GitLab) that you can run on your own server. It's perfect for:
- 📦 Hosting your code repositories privately
- 👥 Team collaboration with pull requests
- 🔍 Code review
- 📋 Issue tracking
- 🔄 CI/CD integration

---

## 🚀 Initial Setup

### Step 1: Access Forgejo

After starting Docker Compose, open your browser:

```
http://192.168.1.100:3030
```

You'll see the **Initial Configuration** page.

---

### Step 2: Configure Forgejo

Fill in the following settings:

#### **Database Settings** (Already configured via Docker)
- ✅ Database Type: `PostgreSQL`
- ✅ Host: `postgres:5432`
- ✅ Username: `elearning`
- ✅ Password: `dev_password_change_in_prod`
- ✅ Database Name: `forgejo`

#### **General Settings**
- **Site Title**: `E-Learning Dev`
- **Repository Root Path**: `/data/git/repositories` (default)
- **Git LFS Root Path**: `/data/git/lfs` (default)
- **Run As Username**: `git` (default)

#### **Server and Third-Party Service Settings**
- **SSH Server Domain**: `192.168.1.100`
- **SSH Port**: `2222`
- **Forgejo HTTP Listen Port**: `3000` (internal)
- **Forgejo Base URL**: `http://192.168.1.100:3030`
- **Log Path**: `/data/forgejo/log` (default)

#### **Email Settings** (Optional - use Mailhog)
- **SMTP Host**: `mailhog:1025`
- **Send Email As**: `forgejo@elearning.local`
- **Require Sign-In to View Pages**: ✅ (recommended)

#### **Administrator Account Settings**
Create your admin account:
- **Username**: `admin`
- **Password**: `admin123` (change in production!)
- **Email**: `admin@elearning.local`

Click **Install Forgejo**

---

## 👥 Creating Developer Accounts

### Option 1: Self-Registration (if enabled)

Users can register at: `http://192.168.1.100:3030/user/sign_up`

### Option 2: Admin Creates Users

1. Login as admin
2. Go to **Site Administration** (top right)
3. Click **User Accounts**
4. Click **Create User Account**
5. Fill in:
   - Username
   - Email
   - Password
6. Click **Create User Account**

---

## 📦 Creating Your First Repository

### Via Web Interface

1. Login to Forgejo
2. Click **+** (top right) → **New Repository**
3. Fill in:
   - **Owner**: Your username
   - **Repository Name**: `elearning-backend`
   - **Description**: Backend API for E-Learning Platform
   - **Visibility**: Private
   - **Initialize Repository**: ✅ Add README
   - **Add .gitignore**: Node
   - **Add License**: MIT (optional)
4. Click **Create Repository**

---

## 🔑 Setting Up SSH Access

### Step 1: Generate SSH Key (if you don't have one)

```bash
# On your developer machine
ssh-keygen -t ed25519 -C "your_email@example.com"

# Press Enter to accept default location (~/.ssh/id_ed25519)
# Enter a passphrase (optional but recommended)
```

### Step 2: Add SSH Key to Forgejo

```bash
# Copy your public key
cat ~/.ssh/id_ed25519.pub
```

1. Login to Forgejo
2. Click your **avatar** (top right) → **Settings**
3. Click **SSH / GPG Keys**
4. Click **Add Key**
5. Paste your public key
6. Give it a name (e.g., "MacBook Pro")
7. Click **Add Key**

### Step 3: Test SSH Connection

```bash
ssh -T git@192.168.1.100 -p 2222
```

You should see:
```
Hi there, <username>! You've successfully authenticated, but Forgejo does not provide shell access.
```

---

## 💻 Using Git with Forgejo

### Clone Repository

```bash
# Via SSH (recommended)
git clone ssh://git@192.168.1.100:2222/<username>/elearning-backend.git

# Via HTTP
git clone http://192.168.1.100:3030/<username>/elearning-backend.git
```

### Push Existing Project

```bash
cd /path/to/your/project

# Initialize git (if not already)
git init

# Add Forgejo as remote
git remote add origin ssh://git@192.168.1.100:2222/<username>/elearning-backend.git

# Add files
git add .
git commit -m "Initial commit"

# Push to Forgejo
git push -u origin main
```

---

## 🏢 Organizing Repositories

### Create Organization

1. Click **+** (top right) → **New Organization**
2. Fill in:
   - **Organization Name**: `elearning-team`
   - **Visibility**: Private
3. Click **Create Organization**

### Add Team Members

1. Go to Organization → **Teams**
2. Click **Create New Team**
3. Fill in:
   - **Team Name**: `Developers`
   - **Permission**: Write
4. Click **Create Team**
5. Click **Add Team Member** and select users

### Create Repository in Organization

1. Click **+** → **New Repository**
2. **Owner**: Select `elearning-team`
3. Fill in repository details
4. Click **Create Repository**

---

## 🔄 Recommended Repository Structure

```
elearning-team/
├── elearning-backend          # Backend API
├── elearning-frontend-student # Student Frontend
├── elearning-frontend-admin   # Admin Frontend
├── elearning-docs             # Documentation
└── elearning-infrastructure   # Docker, CI/CD configs
```

---

## 🎯 Workflow Example

### 1. Clone Repository

```bash
git clone ssh://git@192.168.1.100:2222/elearning-team/elearning-backend.git
cd elearning-backend
```

### 2. Create Feature Branch

```bash
git checkout -b feature/add-quiz-api
```

### 3. Make Changes

```bash
# Edit files
nano src/controllers/quizController.js

# Commit changes
git add .
git commit -m "feat: add quiz submission endpoint"
```

### 4. Push Branch

```bash
git push origin feature/add-quiz-api
```

### 5. Create Pull Request

1. Go to repository in Forgejo
2. Click **Pull Requests**
3. Click **New Pull Request**
4. Select:
   - **Base**: `main`
   - **Compare**: `feature/add-quiz-api`
5. Fill in title and description
6. Click **Create Pull Request**

### 6. Code Review

Team members can:
- Review code changes
- Add comments
- Approve or request changes

### 7. Merge

Once approved:
1. Click **Merge Pull Request**
2. Select merge method (Merge / Squash / Rebase)
3. Click **Confirm Merge**

---

## 🔧 Git Configuration

### Set Git Config for Forgejo

```bash
# Set your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Use SSH by default
git config --global url."ssh://git@192.168.1.100:2222/".insteadOf "http://192.168.1.100:3030/"

# Set default branch name
git config --global init.defaultBranch main
```

### SSH Config (Optional)

Create `~/.ssh/config`:

```
Host forgejo
    HostName 192.168.1.100
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519
```

Now you can clone with:
```bash
git clone forgejo:<username>/elearning-backend.git
```

---

## 📋 Common Tasks

### Create .gitignore

```bash
# Create .gitignore for Node.js
cat > .gitignore << 'EOF'
# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Environment variables
.env
.env.local
.env.*.local

# Build output
dist/
build/
.next/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Logs
logs/
*.log

# Database
*.sqlite
*.db
EOF

git add .gitignore
git commit -m "chore: add .gitignore"
git push
```

### Protect Main Branch

1. Go to Repository → **Settings**
2. Click **Branches**
3. Click **Add Rule**
4. Fill in:
   - **Branch Name Pattern**: `main`
   - **Enable Branch Protection**: ✅
   - **Require Pull Request**: ✅
   - **Require Approvals**: 1
   - **Dismiss Stale Approvals**: ✅
5. Click **Save**

---

## 🐛 Troubleshooting

### Cannot Connect via SSH

```bash
# Check if Forgejo is running
docker ps | grep forgejo

# Test SSH connection
ssh -T git@192.168.1.100 -p 2222 -v

# Check if port 2222 is open
telnet 192.168.1.100 2222
```

### Permission Denied (publickey)

```bash
# Make sure your SSH key is added to Forgejo
# Check SSH agent
ssh-add -l

# Add your key to agent
ssh-add ~/.ssh/id_ed25519
```

### Cannot Push to Repository

```bash
# Check remote URL
git remote -v

# Update remote URL
git remote set-url origin ssh://git@192.168.1.100:2222/<username>/repo.git

# Check your permissions in Forgejo
# Make sure you have write access to the repository
```

---

## 🎯 Best Practices

### 1. **Use SSH for Authentication**
- More secure than HTTP
- No need to enter password every time

### 2. **Protect Main Branch**
- Require pull requests
- Require code reviews
- Prevent force pushes

### 3. **Use Meaningful Commit Messages**
```bash
# Good
git commit -m "feat: add user authentication endpoint"
git commit -m "fix: resolve quiz submission bug"
git commit -m "docs: update API documentation"

# Bad
git commit -m "update"
git commit -m "fix bug"
git commit -m "changes"
```

### 4. **Create Feature Branches**
```bash
# Feature
git checkout -b feature/user-profile

# Bug fix
git checkout -b fix/login-error

# Hotfix
git checkout -b hotfix/security-patch
```

### 5. **Regular Commits**
- Commit often
- Keep commits focused
- One logical change per commit

---

## 📚 Additional Resources

- [Forgejo Documentation](https://forgejo.org/docs/)
- [Git Documentation](https://git-scm.com/doc)
- [GitHub Flow Guide](https://guides.github.com/introduction/flow/)

---

## ✅ Quick Reference

| Action | Command |
|--------|---------|
| Clone repo | `git clone ssh://git@192.168.1.100:2222/<user>/<repo>.git` |
| Create branch | `git checkout -b feature/name` |
| Stage changes | `git add .` |
| Commit | `git commit -m "message"` |
| Push | `git push origin branch-name` |
| Pull latest | `git pull origin main` |
| Check status | `git status` |
| View history | `git log --oneline` |
| Switch branch | `git checkout branch-name` |
| Delete branch | `git branch -d branch-name` |

---

## 🎊 You're Ready!

Now you have a fully functional Git server for your E-Learning project! 

**Next Steps**:
1. Create repositories for each component (backend, frontend-student, frontend-admin)
2. Invite team members
3. Set up branch protection
4. Start collaborating! 🚀