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.ymlservices:  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 -ddocker logs -f forgejo

3. Caddy reverse proxy với SSH port forward

# /etc/caddy/Caddyfilegit.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/configHost git.your-domain.com  Port 2222  User git # Sau đó clone bình thườnggit 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 binarywget https://code.forgejo.org/forgejo/runner/releases/download/v6.0.0/forgejo-runner-amd64chmod +x forgejo-runner-amd64mv forgejo-runner-amd64 /usr/local/bin/forgejo-runner # Register runnerforgejo-runner register   --no-interactive   --instance https://git.your-domain.com   --token YOUR_RUNNER_TOKEN   --name vps-runner   --labels docker # Run as systemd serviceforgejo-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 packagenpm publish # Installnpm 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 -> SlackWebhook URL: https://hooks.slack.com/services/YOUR/SLACK/WEBHOOKChannel: #git-activityEvents: Push, Pull Request, Issue, Release # Hoặc custom webhook genericURL: https://n8n.your-domain.com/webhook/git-eventContent Type: application/jsonEvents: 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 đêmdocker 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 R2rclone copy /backup/forgejo-dump-*.zip r2:backup-forgejo/ # Retention 30 ngàyfind /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 Pipelineon: [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 Reportabout: Report a buglabels: bug--- ## Mô tả<!-- Mô tả ngắn gọn bug --> ## Steps to reproduce1.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 nổi bậ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.