docs: Add Forgejo and development setup guides, and refactor API documentation structure.
This commit is contained in:
JakkrapartXD
parent
7b1ed6f6cc
commit
a6427b2083
9 changed files with 2446 additions and 7 deletions
493
docs/forgejo_setup.md
Normal file
493
docs/forgejo_setup.md
Normal file
|
|
@ -0,0 +1,493 @@
|
|||
# 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! 🚀
|
||||
Loading…
Add table
Add a link
Reference in a new issue