Cài Forgejo trên VPS: thay GitHub Private cho team indie

GitHub Free private repo unlimited nhưng giới hạn CI minutes, không có advanced features (code search, audit log). GitHub Team 4 USD/user/tháng. Team 10 người là 40 USD, năm 480 USD. Bonus: code internal lên GitHub Microsoft, một số doanh nghiệp ngại data sensitivity. Forgejo là alternative tuyệt vời: self-host trên VPS riêng, full feature, free, single binary 100MB.

Mình đang chạy Forgejo cho 4 team Việt Nam: 1 startup B2B 8 dev, 1 fintech 12 dev, 1 agency 6 dev, 1 personal cá nhân. Tổng 200+ private repo, 50+ CI workflow runs/ngày, VPS Cloud 40 đủ chạy thoải mái. Bài này hướng dẫn full setup, migrate từ GitHub, CI Actions, backup.

1. Forgejo vs Gitea vs GitLab vs Gogs

Forgejo là fork Gitea (sau khi Gitea bị acquire bởi corp 2022), do community Codeberg và contributors độc lập maintain. Triết lý: lightweight, free forever, community-first.

2. Cài Forgejo Docker Compose

mkdir -p /opt/forgejo && cd /opt/forgejo

# docker-compose.yml
services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:9
    container_name: forgejo
    restart: unless-stopped
    environment:
      USER_UID: 1000
      USER_GID: 1000
      FORGEJO__database__DB_TYPE: postgres
      FORGEJO__database__HOST: db:5432
      FORGEJO__database__NAME: forgejo
      FORGEJO__database__USER: forgejo
      FORGEJO__database__PASSWD: forgejo_strong_pass
      FORGEJO__server__ROOT_URL: https://git.your-domain.com
      FORGEJO__server__DOMAIN: git.your-domain.com
      FORGEJO__server__SSH_DOMAIN: git.your-domain.com
      FORGEJO__server__SSH_PORT: 2222
      FORGEJO__mailer__ENABLED: "true"
      FORGEJO__mailer__SMTP_ADDR: smtp.mailgun.org:587
      FORGEJO__mailer__USER: [email protected]
      FORGEJO__mailer__PASSWD: $MAILGUN_PASSWORD
    volumes:
      - forgejo-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"

  db:
    image: postgres:16-alpine
    container_name: forgejo-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: forgejo_strong_pass
      POSTGRES_DB: forgejo
    volumes:
      - forgejo-db:/var/lib/postgresql/data

volumes:
  forgejo-data:
  forgejo-db:

docker compose up -d
docker logs -f forgejo

3. Caddy reverse proxy với SSH port forward

# /etc/caddy/Caddyfile
git.your-domain.com {
    reverse_proxy 127.0.0.1:3000
    encode gzip
    request_body {
        max_size 500MB    # cho large file upload
    }
}

SSH port 2222 expose trực tiếp qua firewall (không proxy). User clone bằng [email protected]:2222 hoặc thêm config SSH:

# ~/.ssh/config
Host git.your-domain.com
  Port 2222
  User git

# Sau đó clone bình thường
git clone [email protected]:myorg/myrepo.git

4. Setup wizard và admin account

Truy cập https://git.your-domain.com, wizard hiện ra:

1. Database settings: đã pre-config qua env, click Install
2. General settings: Site Title "TND Code", Repository Root đã default OK
3. Server settings: HTTP/SSH ports đã set, không cần đổi
4. Admin Account: tạo admin user đầu tiên
5. Click "Install Forgejo"

Sau khi setup, Settings -> Site Administration -> Configuration: bật/tắt registration, max repo per user, max file size, etc.

5. Tạo org và repo đầu tiên

1. + icon top right -> New Organization: "tnd"
2. Add member với role Owner/Member/Admin
3. Trong org tnd, New Repository: "app-backend"
4. Choose Private, init README, .gitignore Node, license MIT
5. Clone về local: git clone [email protected]:tnd/app-backend.git

6. Migration từ GitHub

1. + icon -> New Migration -> chọn GitHub
2. Migration Type: All hoặc chọn items (issue, PR, label, milestone, wiki)
3. Clone URL: https://github.com/myorg/myrepo
4. Auth Token: GitHub Personal Access Token (scope repo)
5. Owner: chọn org/user destination, repo name
6. Start Migration, đợi 1-10 phút tuỳ repo size

Migration giữ nguyên commit history, branch, tag, issue, PR, milestone. Mình migrate 30 repo từ GitHub trong 2 ngày, total 5GB code, không lỗi gì lớn.

7. Forgejo Actions: CI/CD tương thích GitHub

# .forgejo/workflows/ci.yml (giống .github/workflows/ci.yml)
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: docker
    container:
      image: node:20-alpine
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
      - run: npm run build

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to VPS
        run: |
          ssh -i ${{ secrets.SSH_KEY }} [email protected] 
            "cd /opt/app && git pull && npm install && pm2 restart all"

Workflow file y chang GitHub Actions, copy-paste là chạy được. Setup runner riêng:

# Download runner binary
wget https://code.forgejo.org/forgejo/runner/releases/download/v6.0.0/forgejo-runner-amd64
chmod +x forgejo-runner-amd64
mv forgejo-runner-amd64 /usr/local/bin/forgejo-runner

# Register runner
forgejo-runner register 
  --no-interactive 
  --instance https://git.your-domain.com 
  --token YOUR_RUNNER_TOKEN 
  --name vps-runner 
  --labels docker

# Run as systemd service
forgejo-runner daemon

8. Package registry: npm, Docker, Maven

Forgejo có package registry private cho 12+ format. Setup npm:

# Generate package token: User Settings -> Applications -> Generate New Token (scope: write:package)

# .npmrc
@tnd:registry=https://git.your-domain.com/api/packages/tnd/npm/
//git.your-domain.com/api/packages/tnd/npm/:_authToken=YOUR_TOKEN

# Publish package
npm publish

# Install
npm install @tnd/my-internal-lib

Tương tự cho Docker (login docker, push image vào git.your-domain.com), Maven, NuGet, Composer. Tiện cho team share lib internal mà không public ra npm.

9. Issue, PR, project board

Forgejo có tất cả tính năng project management cơ bản:

• Issue tracker với label, milestone, assignee, due date
• Pull Request với review, comment, approval workflow
• Project board Kanban (Backlog, In Progress, Done)
• Wiki built-in mỗi repo
• Release tag với binary attachment
• Markdown editor preview realtime

UX gần ngang GitHub Free, đủ cho 95% workflow team nhỏ và indie.

10. SSO với OAuth Google/GitHub/GitLab

1. Site Administration -> Authentication Sources -> Add Source
2. Type: OAuth2
3. Provider: Google (hoặc GitHub, GitLab, Microsoft, OIDC custom)
4. Client ID, Client Secret từ OAuth provider
5. Update OAuth provider callback URL: https://git.your-domain.com/user/oauth2/Google/callback
6. Save, user thấy nút "Sign in with Google" trên trang login

SSO giảm friction onboarding team mới, đặc biệt team đã có Google Workspace.

11. Webhook tích hợp Slack, Discord, n8n

# Repo Settings -> Webhooks -> Add Webhook -> Slack
Webhook URL: https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
Channel: #git-activity
Events: Push, Pull Request, Issue, Release

# Hoặc custom webhook generic
URL: https://n8n.your-domain.com/webhook/git-event
Content Type: application/json
Events: All

n8n workflow lắng nghe webhook git, trigger automation: deploy to staging on push to develop, notify designer khi merge feature branch.

12. Backup repo và database

# Backup hằng đêm
docker exec forgejo /bin/sh -c 'cd /tmp && forgejo dump -c /data/gitea/conf/app.ini -f forgejo-dump-$(date +%F).zip'
docker cp forgejo:/tmp/forgejo-dump-$(date +%F).zip /backup/

# Push lên R2
rclone copy /backup/forgejo-dump-*.zip r2:backup-forgejo/

# Retention 30 ngày
find /backup -name "forgejo-dump-*.zip" -mtime +30 -delete

Dump file chứa toàn bộ: DB, repo bare, LFS, attachment, config. Restore: stop container, extract vào /data, start lại.

13. Performance và scale

• Cloud VPS 20: 5-10 dev, 50 repo nhỏ, 10 CI/ngày
• Cloud VPS 40: 10-20 dev, 200 repo, 50 CI/ngày
• Cloud VPS 80: 30-50 dev, 500 repo, 200 CI/ngày + Forgejo Actions runner
• Cloud VPS 160: 50-100 dev, 1000+ repo, multi-runner CI

Forgejo rất hiệu quả về resource. So với GitLab CE cần 4GB+ RAM minimum, Forgejo chỉ cần 200MB cho cùng tải.

14. Security hardening

1. 2FA bắt buộc cho admin account
2. SSH key only, disable HTTP push password
3. Disable public registration (only admin invite)
4. Limit max file size, max repo size per user
5. Rate limit API: 60 req/min cho anonymous, 600/min cho user
6. Audit log: ai làm gì khi nào, lưu vào file
7. Update Forgejo version định kỳ, theo security advisory

15. Federation với fediverse

Forgejo đang phát triển ActivityPub federation, cho phép user trên Forgejo instance khác nhau follow, star, comment cross-instance. Tương tự Mastodon cho code. Hiện ở beta, chưa stable đầy đủ, nhưng hướng đi quan trọng cho ecosystem dev độc lập khỏi GitHub Microsoft monopoly.

16. Cost so sánh thực tế

Tiết kiệm 20-80% cost, đồng thời data nội bộ không gửi ra ngoài. Win-win cho team Việt Nam.

17. Forgejo Actions advanced workflow

Workflow CI/CD phức tạp hơn với matrix, secret, cache, artifact:

name: Full CI Pipeline
on: [push, pull_request]

jobs:
  test:
    runs-on: docker
    strategy:
      matrix:
        node: [18, 20, 22]
        os: [ubuntu-latest]
    container:
      image: node:${{ matrix.node }}-alpine
    steps:
      - uses: actions/checkout@v4
      - name: Cache deps
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ matrix.node }}-${{ hashFiles('package-lock.json') }}
      - run: npm ci
      - run: npm test
      - name: Upload coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage-node-${{ matrix.node }}
          path: coverage/

  build:
    needs: test
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - name: Build Docker image
        run: |
          docker build -t git.your-domain.com/tnd/app:${{ github.sha }} .
          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login git.your-domain.com -u registry-user --password-stdin
          docker push git.your-domain.com/tnd/app:${{ github.sha }}

Matrix test 3 Node version song song, cache npm để build nhanh, push Docker image vào Forgejo registry. Workflow này production-grade cho team backend.

18. Repo template và issue template

Forgejo hỗ trợ template repo: setup repo "starter-node" có sẵn structure, Dockerfile, .gitignore, README, CI workflow. Khi tạo repo mới, chọn "Create from template", lấy luôn structure standard.

# .forgejo/issue_template/bug_report.md
---
name: Bug Report
about: Report a bug
labels: bug
---

## Mô tả


## Steps to reproduce
1.
2.
3.

## Expected behavior

## Screenshots

Template giúp issue và PR format thống nhất, dễ triage. Team scale lên 20+ dev rất cần.

19. Mirror repo từ GitHub (sync 2 chiều)

Workflow hybrid: code chính trên GitHub (public), mirror sang Forgejo internal cho backup + CI tự host:

1. Repo Settings -> Mirror Settings -> Add Push Mirror hoặc Pull Mirror
2. Push Mirror: Forgejo -> GitHub (sync mỗi 8h)
3. Pull Mirror: GitHub -> Forgejo (sync mỗi 8h)
4. Bidirectional: cẩn thận conflict, recommend chỉ 1 chiều

Pattern này hữu ích cho open source: phát triển public trên GitHub (visibility), backup mirror Forgejo (disaster recovery khi GitHub down hoặc account bị ban).

20. Disaster recovery procedure

1. Backup hằng đêm: dump file zip push R2/S3
2. Snapshot VPS hằng tuần: full system snapshot Cloud TND
3. Test restore quarterly: pull backup vào VPS staging, verify Forgejo lên đầy đủ data
4. Standby VPS: option có VPS thứ 2 sẵn cold standby, switch DNS khi primary chết
5. Code đã clone local trên dev laptop: backup layer cuối, dev luôn có code local có thể push lên instance mới

Mình từng gặp 1 lần VPS Forgejo crash do disk hỏng. Restore từ snapshot mất 30 phút, từ backup zip mất 1 giờ. Toàn bộ team continue work bình thường.

21. Tổng kết và roadmap

Forgejo là Git platform tự host tốt nhất hiện tại cho team indie và startup VN. Tỷ lệ giá/tính năng vượt trội GitLab CE (nặng) và Gogs (basic). Đặc biệt phù hợp khi team muốn data privacy, không phụ thuộc GitHub Microsoft, và tiết kiệm subscription cost. Đầu tư 1 buổi setup, sau đó chạy ổn định nhiều năm với chi phí thấp. Combine với CI runner và package registry tích hợp tạo thành development platform hoàn chỉnh không cần SaaS bên ngoài. Đây là một trong những self-hosted setup ROI cao nhất mình recommend cho dev Việt Nam.

FAQ

Forgejo vs Gitea nên chọn cái nào?

Forgejo hiện phát triển nhanh hơn, community driven, governance non-profit. Gitea sau khi bị corp acquire 2022 có lo ngại commercialization. Cho user mới, recommend Forgejo. Migration giữa 2 cái dễ vì cùng codebase gốc.

CI runner cần VPS riêng không?

Tuỳ load. Team nhỏ runner chạy chung VPS Forgejo OK. Team CI heavy nên tách runner sang VPS riêng để tránh CI compile block UI. Cloud VPS 40 thêm cho runner.

Forgejo có hỗ trợ GitHub PR review workflow đầy đủ không?

Có: comment line-by-line, approve/request changes, merge button (squash, rebase, merge commit), protected branch, required reviewer, status check CI. UX 90% giống GitHub.

LFS có hỗ trợ không?

Có, Git LFS built-in. Storage backend filesystem local hoặc S3-compatible (MinIO, R2). Setup max file size tuỳ admin.

Có support code search như GitHub không?

Có basic full-text search trong repo. Cho code search advanced (regex, multi-repo), bật indexer Elasticsearch hoặc Meilisearch backend. Performance không bằng GitHub Code Search nhưng đủ dùng cho team nhỏ.

Sau 2 năm chạy Forgejo cho 4 team, mình tự tin recommend platform này cho mọi dev Việt Nam. Bắt đầu với Cloud VPS 20 (199k/tháng), upgrade dần khi team grow. Không bao giờ tốn quá 1 triệu/tháng cho 50+ dev. Đó là cái rẻ nhất so với mọi giải pháp Git platform khác hiện tại.