Forgejo - Hướng dẫn xây dựng Git Server "chính chủ" với Docker Compose

Ở bài viết trước, mình có hướng dẫn bạn cách self-hosted Gitea, thì ở bài này mình giới thiệu thêm 1 lựa chọn nữa là Forgejo. Đây không chỉ là một giải pháp thay thế về mặt kỹ thuật, mà còn là câu trả lời đanh thép cho câu hỏi: “Ai thực sự kiểm soát nền tảng phát triển phần mềm của chúng ta?”

Được bảo trợ bởi Codeberg e.V. (một tổ chức phi lợi nhuận uy tín tại Đức), Forgejo cam kết một tương lai mà nền tảng Git của bạn sẽ mãi mãi là mã nguồn mở 100%, do cộng đồng điều hành, thoát khỏi sự chi phối của các toan tính thương mại.

Trong bài viết này, mình sẽ không chỉ giải thích lý do tại sao Forgejo là tương lai, mà còn cầm tay chỉ việc, hướng dẫn bạn từng bước triển khai một Forgejo server hoàn chỉnh với Docker Compose, bao gồm cả HTTPS và Database riêng biệt.

Forgejo là gì? Câu chuyện “Beyond Gitea”

Để thực sự hiểu giá trị của Forgejo, chúng ta cần nhìn lại dòng chảy lịch sử của các Git server mã nguồn mở. Nó giống như một cây phả hệ vậy:

Gogs (2014): “Ông tổ” của dòng này. Dự án Git self-hosted đầu tiên, cực kỳ nhẹ và dễ dùng, nhưng tiến độ phát triển chậm dần.
Gitea (2016): Một bản fork từ Gogs do cộng đồng tách ra khi Gogs không còn đáp ứng được tốc độ phát triển mong muốn. Gitea nhanh chóng chiếm lĩnh thị trường nhờ tính năng phong phú.
Forgejo (2022): Được sinh ra từ nỗi lo ngại sâu sắc khi dự án Gitea bị chuyển giao quyền kiểm soát cho một công ty vì lợi nhuận. Forgejo là lời khẳng định về sự tự do vĩnh viễn.

Từ “Soft Fork” đến sự độc lập hoàn toàn

Ban đầu, Forgejo hoạt động như một “soft fork” của Gitea (hãy tưởng tượng như mối quan hệ giữa LineageOS và Android).

Nó dùng chung phần lớn mã nguồn với Gitea.
Bạn có thể cập nhật từ Gitea sang Forgejo mượt mà như thay áo.
Các tính năng mới của Gitea vẫn được đưa vào Forgejo.

Tuy nhiên, kể từ tháng 2 năm 2024, Forgejo đã chính thức trở thành “hard fork”. Điều này cực kỳ quan trọng: codebase của Forgejo đã bắt đầu tách biệt và phát triển độc lập. Giờ đây, Forgejo tự quyết định vận mệnh của mình mà không cần phụ thuộc vào lộ trình (roadmap) của Gitea nữa.

Triết lý vị cộng đồng

Forgejo không chỉ là phần mềm, nó là một bản cam kết:

Exclusively Free Software: Toàn bộ hệ sinh thái (công cụ dev, test, release) đều miễn phí.
No Copyright Assignment: Không yêu cầu bạn phải nhượng quyền tác giả khi đóng góp code (khác với Gitea).
Quản lý dân chủ: Quyết định nằm trong tay cộng đồng, không phải CEO của một công ty nào đó.
Hướng tới Federation: Kết nối các server với nhau qua ActivityPub (tương tự Mastodon), tạo nên mạng lưới phi tập trung.

Tại sao bạn nên chọn Forgejo ngay hôm nay?

Là một người đã trải nghiệm cả hai, dưới đây là những lý do khiến mình tin rằng Forgejo là bến đỗ an toàn và mạnh mẽ hơn:

1. Bảo đảm mã nguồn mở 100% mãi mãi

Đây là “kim bài miễn tử” cho dự án của bạn. Forgejo thuộc về Codeberg e.V. (phi lợi nhuận).

Sẽ không có chuyện một ngày đẹp trời tính năng bạn đang dùng bị khóa lại và dán nhãn “Enterprise Only” (Chỉ dành cho trả phí).
Thực tế: Dự án Fedora Linux danh tiếng cũng đang chuyển nền tảng Pagure của họ sang Forgejo vì lý do này.

2. Nhẹ nhàng và hiệu suất “khủng”

Được viết bằng Go, Forgejo tối ưu tài nguyên đến mức kinh ngạc:

Tiêu chí	Forgejo	GitHub (Cloud)	GitLab
RAM tối thiểu	~1 GB	N/A	4-8 GB (Rất nặng)
CPU tối thiểu	1 Core	N/A	2-4 Cores
Database	SQLite, PostgreSQL, MySQL	Kín (Proprietary)	PostgreSQL
Docker Image	~100 MB	N/A	~1 GB

Pro Tip: 
Bạn hoàn toàn có thể chạy Forgejo mượt mà trên một chiếc Raspberry Pi 4 hoặc một VPS giá rẻ ($5/tháng).

3. Tính năng không thua kém ai

Đừng nghĩ “nhẹ” là “thiếu”. Forgejo kế thừa và phát triển mọi thứ bạn cần:

Quản lý Repo, Issues, Pull Requests (PR).
Wiki, CI/CD (Forgejo Actions – tương thích với GitHub Actions).
Package Registry (Docker, npm, PyPI…).
Quản lý user qua LDAP, OAuth, SAML.

4. Bảo mật là ưu tiên hàng đầu

Forgejo làm tốt hơn Gitea ở mảng này nhờ quy trình kiểm thử nghiêm ngặt:

End-to-End Tests & Upgrade Tests: Có sẵn.
Thông báo bảo mật: Công khai cho tất cả mọi người (trong khi Gitea ưu tiên thông báo cho khách hàng trả phí trước).

5. Dữ liệu là của BẠN

Khi dùng GitHub/GitLab Cloud, bạn đang “ở trọ”. Họ có thể tăng giá, đổi luật, hoặc khóa tài khoản của bạn. Với Forgejo self-hosted, bạn nắm giữ 100% dữ liệu.

Chuẩn bị môi trường triển khai

Trước khi bắt tay vào gõ lệnh, hãy chuẩn bị “nguyên liệu”.

Yêu cầu phần cứng (VPS/Server)

OS: Linux (Ubuntu 20.04+, Debian 11+…) – Bất kỳ OS nào chạy được Docker.
RAM: Tối thiểu 1GB (Khuyên dùng 2-4GB để chạy thoải mái cùng Database).
CPU: 1-2 Cores.
Ổ cứng: 20-50GB (Tùy thuộc code của bạn nặng hay nhẹ).
Gợi ý: Hetzner Cloud, DigitalOcean, hoặc một máy tính cũ ở nhà.

Tên miền (Domain)

Bạn nên có một tên miền (ví dụ: git.ten-cua-ban.com). Dù có thể chạy qua IP, nhưng có tên miền sẽ giúp việc thiết lập SSL/HTTPS dễ dàng và chuyên nghiệp hơn rất nhiều.

Cài đặt Docker & Docker Compose

Mình sẽ hướng dẫn trên Ubuntu/Debian (môi trường phổ biến nhất).

# 1. Cập nhật hệ thống
sudo apt update && sudo apt upgrade -y

# 2. Cài đặt Docker (script chính chủ cực nhanh)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 3. Thêm user hiện tại vào nhóm docker (để không phải gõ sudo mỗi lần)
sudo usermod -aG docker $USER
newgrp docker

# 4. Cài đặt Docker Compose (bản mới nhất)
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 5. Kiểm tra lại version để chắc chắn đã thành công
docker --version
docker-compose --version

(Nếu bạn dùng macOS để test, chỉ cần cài OrbStack là đủ).

Hướng dẫn triển khai Forgejo với Docker Compose

Đây là phần quan trọng nhất. Chúng ta sẽ dựng một stack gồm:

Forgejo: App chính.
PostgreSQL: Cơ sở dữ liệu (mạnh hơn SQLite mặc định).
Traefik: Reverse Proxy (giúp tự động lấy chứng chỉ SSL miễn phí từ Let’s Encrypt).

Bước 1: Tạo cấu trúc thư mục

Hãy giữ mọi thứ ngăn nắp.

# Tạo thư mục dự án
mkdir -p ~/forgejo && cd ~/forgejo

# Tạo các thư mục con để lưu dữ liệu (Persistence)
mkdir -p data db letsencrypt

# Kiểm tra lại
ls -la

Giải thích:

data/: Nơi chứa code, repos, ssh keys.
db/: Nơi chứa dữ liệu của PostgreSQL.
letsencrypt/: Nơi Traefik lưu chứng chỉ SSL.

Bước 2: Tạo file `.env` (Quản lý biến môi trường)

Chúng ta không nên hard-code mật khẩu vào file cấu hình. Hãy dùng file .env.

nano .env

Dán nội dung sau vào (nhớ sửa lại thông tin của bạn):

# --- Cấu hình Database PostgreSQL ---
POSTGRES_USER=forgejo
POSTGRES_PASSWORD=your_secure_db_password_here
POSTGRES_DB=forgejodb

# --- Cấu hình Forgejo ---
FORGEJO_DB_USER=forgejo
FORGEJO_DB_PASS=your_secure_db_password_here
FORGEJO_DB_NAME=forgejodb
FORGEJO_DOMAIN=forgejo.example.com
FORGEJO_ROOT_URL=https://forgejo.example.com

# --- Email cho Let's Encrypt (để nhận thông báo SSL) ---
[email protected]

LƯU Ý:
Thay forgejo.example.com bằng domain thật của bạn và đặt your_secure_db_password_here thật khó đoán nhé.

Bước 3: Tạo file `docker-compose.yml`

Đây là bản thiết kế cho toàn bộ hệ thống của chúng ta.

nano docker-compose.yml

Copy toàn bộ nội dung bên dưới:

networks:
  forgejo-network:
    driver: bridge

services:
  # --- Service 1: Traefik (Reverse Proxy & SSL) ---
  traefik:
    image: traefik:latest
    container_name: traefik
    restart: unless-stopped
    environment:
      - DOCKER_API_VERSION=1.44
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      # Tự động chuyển hướng HTTP sang HTTPS
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      # Cấu hình Let's Encrypt Challenge
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - forgejo-network

  # --- Service 2: PostgreSQL (Database) ---
  db:
    image: postgres:15
    container_name: forgejo-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - ./db:/var/lib/postgresql/data
    networks:
      - forgejo-network
    # Database nằm trong mạng nội bộ, an toàn tuyệt đối

  # --- Service 3: Forgejo (The Star) ---
  forgejo:
    image: codeberg.org/forgejo/forgejo:13
    container_name: forgejo
    restart: unless-stopped
    depends_on:
      - db
    environment:
      # User ID trong container
      - USER_UID=1000
      - USER_GID=1000

      # Kết nối Database
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=${FORGEJO_DB_NAME}
      - FORGEJO__database__USER=${FORGEJO_DB_USER}
      - FORGEJO__database__PASSWD=${FORGEJO_DB_PASS}

      # Cấu hình Server
      - FORGEJO__server__DOMAIN=${FORGEJO_DOMAIN}
      - FORGEJO__server__ROOT_URL=${FORGEJO_ROOT_URL}
      - FORGEJO__server__HTTP_PORT=3000
      - FORGEJO__server__SSH_PORT=22
      - FORGEJO__server__SSH_LISTEN_PORT=2222

      # Tính năng Service
      - FORGEJO__service__DISABLE_REGISTRATION=false
      - FORGEJO__service__REQUIRE_SIGNIN_VIEW=false
      - FORGEJO__service__ENABLE_NOTIFY_MAIL=true

      # Thông tin chung
      - FORGEJO__DEFAULT__APP_NAME=My Forgejo Instance
      - FORGEJO__DEFAULT__RUN_MODE=prod

    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

    ports:
      # Expose port SSH Git (đổi thành 2222 để tránh trùng SSH hệ thống)
      - "2222:2222"
      # Port 3000 chỉ expose cục bộ cho Traefik (nếu cần debug thì mở ra)
      - "127.0.0.1:3000:3000"

    networks:
      - forgejo-network

    # Cấu hình cho Traefik nhận diện Forgejo
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.forgejo.rule=Host(`${FORGEJO_DOMAIN}`)"
      - "traefik.http.routers.forgejo.entrypoints=websecure"
      - "traefik.http.routers.forgejo.tls=true"
      - "traefik.http.routers.forgejo.tls.certresolver=le"
      - "traefik.http.services.forgejo.loadbalancer.server.port=3000"

      # Middleware redirect HTTPS (bổ trợ)
      - "traefik.http.routers.forgejo-http.rule=Host(`${FORGEJO_DOMAIN}`)"
      - "traefik.http.routers.forgejo-http.entrypoints=web"
      - "traefik.http.routers.forgejo-http.middlewares=redirect-to-https"
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"

Phân tích kỹ thuật:

Traefik: Đóng vai trò như người bảo vệ cổng. Nó lắng nghe port 80/443, tự động xin chứng chỉ SSL và chuyển traffic vào Forgejo (đang chạy ở port 3000 bên trong).
SSH Port 2222: Vì VPS của bạn đã dùng port 22 để SSH quản trị, nên ta phải map port SSH của Forgejo sang 2222.
PostgreSQL: Chỉ giao tiếp với Forgejo qua mạng nội bộ forgejo-network, không lộ ra internet -> Bảo mật tối đa.

Bước 4: Khởi chạy “con tàu”

Giờ G đã điểm, hãy chạy lệnh sau:

# Kiểm tra file config xem có lỗi cú pháp không
docker-compose config

# Nếu ổn, khởi chạy background (-d)
docker-compose up -d

# Xem logs thời gian thực để đảm bảo mọi thứ khởi động tốt
docker-compose logs -f forgejo

Nếu bạn thấy dòng chữ Forgejo is running... trong logs, xin chúc mừng! Bạn đã thành công 90%. Nhấn Ctrl+C để thoát màn hình logs.

Thiết lập ban đầu (Post-Installation)

Bước 1: Truy cập và Cài đặt

Mở trình duyệt và vào địa chỉ: https://forgejo.example.com.

Bạn sẽ thấy trang Initial Configuration. Đừng lo lắng nếu thấy nhiều trường nhập liệu, vì chúng ta đã cấu hình gần hết qua Docker rồi.

Database Settings: Các trường Host, User, Password… đã được điền tự động nhờ file .env. Bạn chỉ cần nhấn “Test Database Connection” để yên tâm.
Server Settings: Domain và URL cũng đã được điền sẵn.

Bước 2: Tạo tài khoản Admin

Kéo xuống dưới cùng, tìm mục Administrator Account Settings. Đây là bước quan trọng, đừng bỏ qua nếu không muốn ai đó nhanh tay đăng ký trước bạn.

Admin Username: admin (hoặc tên bạn).
Password: Đặt mật khẩu thật mạnh.
Email: Email chính chủ của bạn.

Nhấn “Install Forgejo”. Hệ thống sẽ mất khoảng 10-30 giây để khởi tạo database. Sau đó, bạn sẽ được chuyển thẳng vào Dashboard.

Sử dụng Forgejo: Những bước đi đầu tiên

Giao diện Forgejo rất quen thuộc nếu bạn đã dùng GitHub hay Gitea.

Tạo Repository đầu tiên

Nhấn dấu “+” trên thanh menu -> New Repository.
Điền tên: my-first-project.
Chọn Private hoặc Public.
Nhấn Create Repository.

Clone code về máy

Do chúng ta đổi port SSH sang 2222, lệnh clone sẽ hơi khác một chút:

# Cách 1: Clone qua HTTPS (Đơn giản nhất)
git clone https://forgejo.example.com/admin/my-first-project.git

# Cách 2: Clone qua SSH (Cần add SSH Key trước trong Settings)
git clone ssh://[email protected]:2222/admin/my-first-project.git

Sau đó thì dùng Git như bình thường:

cd my-first-project
echo "# Hello Forgejo" > README.md
git add .
git commit -m "First commit on my own server"
git push origin main

So sánh nhanh: Forgejo vs. Gitea vs. GitHub

Để bạn dễ hình dung vị thế của Forgejo:

Tiêu Chí	Forgejo	Gitea	GitHub
Chi phí	Miễn phí (Self-hosted)	Miễn phí (Self-hosted)	Miễn phí / Trả phí
Quyền sở hữu	Cộng đồng (Phi lợi nhuận)	Công ty thương mại	Microsoft
Bảo mật	Rất cao (Kiểm tra kỹ)	Cơ bản	Rất cao
Dữ liệu	100% của bạn	100% của bạn	GitHub nắm giữ
Resource	Siêu nhẹ	Siêu nhẹ	Nặng (nếu dùng Enterprise)
Federation	Đang phát triển mạnh	Không ưu tiên	Không có
CI/CD	Forgejo Actions	Gitea Actions	GitHub Actions

Cấu hình nâng cao (Tuỳ chọn)

Nếu bạn muốn hệ thống “xịn” hơn, hãy thêm các biến môi trường sau vào phần forgejo trong file docker-compose.yml.

1. Cấu hình Email (SMTP)

Để server gửi email reset mật khẩu hoặc thông báo:

    environment:
      - FORGEJO__mailer__ENABLED=true
      - [email protected]
      - FORGEJO__mailer__MAILER_TYPE=smtp
      - FORGEJO__mailer__HOST=smtp.gmail.com:587
      - [email protected]
      # Lưu ý: Dùng App Password nếu là Gmail, không phải mật khẩu đăng nhập
      - FORGEJO__mailer__PASSWD=your-app-password
      - FORGEJO__mailer__SKIP_VERIFY=false

2. Kết nối LDAP (Cho doanh nghiệp)

Nếu công ty bạn dùng LDAP để quản lý nhân sự:

    environment:
      - FORGEJO__auth_ldap__ENABLED=true
      - FORGEJO__auth_ldap__NAME=Corporate LDAP
      - FORGEJO__auth_ldap__HOST=ldap.company.com
      - FORGEJO__auth_ldap__PORT=389
      - FORGEJO__auth_ldap__BIND_DN=cn=forgejo,ou=services,dc=company,dc=com
      # ... (các thông số khác tùy hệ thống LDAP của bạn)

3. Tăng giới hạn Upload

Mặc định là 512MB. Muốn tăng lên 2GB?

    environment:
      - FORGEJO__server__MAX_REQUEST_SIZE=2147483648

Sau khi sửa file, nhớ chạy lại: docker-compose up -d forgejo.

Backup và Recovery: Đừng để mất bò mới lo làm chuồng

Dữ liệu code là tài sản vô giá. Hãy backup thường xuyên.

Backup thủ công

# 1. Backup Database ra file SQL
docker-compose exec db pg_dump -U forgejo forgejodb > forgejo-backup-$(date +%Y%m%d).sql

# 2. Nén thư mục data lại
tar -czf forgejo-data-backup-$(date +%Y%m%d).tar.gz data/

# 3. Sao lưu file cấu hình
cp .env forgejo-config-backup-$(date +%Y%m%d).env

Khôi phục (Restore)

# 1. Nạp lại Database
docker-compose exec -T db psql -U forgejo forgejodb < forgejo-backup-YYYYMMDD.sql

# 2. Giải nén data
tar -xzf forgejo-data-backup-YYYYMMDD.tar.gz

Forgejo là tương lai của sự tự do

Forgejo không đơn thuần là một phần mềm thay thế. Nó là một phong trào. Nó đại diện cho quyền tự chủ, sự minh bạch và sức mạnh của cộng đồng.

Nếu bạn là một lập trình viên coi trọng sự riêng tư, một tổ chức muốn toàn quyền kiểm soát hạ tầng, hay đơn giản là người yêu thích mã nguồn mở, Forgejo là lựa chọn hoàn hảo ngay lúc này.

Bạn đã sẵn sàng sở hữu Git Server của riêng mình chưa? Hãy làm theo hướng dẫn trên và chia sẻ kết quả nhé!

Gợi ý: Nếu chưa có server để cài, bạn có thể ghé thăm Codeberg.org để trải nghiệm Forgejo miễn phí trên instance công cộng của họ.

Duy Nghiện

Hãy làm khán giả, đừng làm nhân vật chính :)