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)

# 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

# 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

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

# 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

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

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

2. Create Feature Branch

git checkout -b feature/add-quiz-api

3. Make Changes

# Edit files
nano src/controllers/quizController.js

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

4. Push Branch

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

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

git clone forgejo:<username>/elearning-backend.git

---

📋 Common Tasks

Create .gitignore

# 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

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

# 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

# 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

# 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

# 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
• Git Documentation
• GitHub Flow Guide

---

✅ 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! 🚀